changes documents

Author: ajewellamz

specification/changes/2024-02-29-encryption-context/background.md

@@ -1,6 +1,10 @@
+[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved."
+[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0"
+
 # Additional Encryption Context
 
 ## Motivation
+
 In the current design, the primary hash and sort keys are made available for branch key calculations. This is sufficient for any system specifically designed with branch keys in mind, but may be insufficient for some legacy systems.
 
 For example, imagine two tables : Users and Groups.
@@ -12,15 +16,15 @@ Thus when querying the User table, the GroupID is unavailable to the branch key
 
 Designate some sign-only attributes to be available to customers for branch key calculations, KMS encryption contexts and such.
 
-### Where to handle the additions 
+### Where to handle the additions
 
-#### Option Taken : Add attributes to the encryption context.
+#### Option Taken : Add attributes to the encryption context
 
 Advantages include :
 * Simple user story
 * Tiny change to API
 
-#### Option Not Taken : Pass attributes to the keyring.
+#### Option Not Taken : Pass attributes to the keyring
 
 We could have extended the keyring interface to receive a set of key-value pairs, and then passed all signed attributes to the keyring, which would use that to choose the branch key.
 
@@ -33,16 +37,15 @@ Drawbacks include :
 
 ### Which Attributes to Include
 
-#### Option Taken : Allow the user to configure which signed fields are included.
+#### Option Taken : Allow the user to configure which signed fields are included
 
 Where the customer used to designate “sign only” they now specify a subset of those to be in the encryption context.
 
 #### Option Not Taken : Include all signed fields
 
 Simplest for the customer, but this could be very large in some cases, and the KMS limit on encryption context size is fairly small.
 
-
-### Versioning 
+### Versioning
 
 We need some way, at decrypt time, to know which attributes were used in the encryption context.
 
@@ -64,33 +67,37 @@ Once we support version 2, we always write version 2. The downside to this is th
 
 Currently, the primary hash and sort keys must be SIGN_ONLY, even though they behave as SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT. Going forward, the primary keys must continue to have the SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT functionality.
 
-#### Option Taken - If any attributes are marked SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT then primary keys must also be SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT.
+#### Option Taken - If any attributes are marked SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT then primary keys must also be SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT
 
 This keeps a consistent meaning for all the CryptoActions, while not requiring a version2 header for customers not using the new feature.
 
 #### Option Not Taken - Primary keys MUST still be SIGN_ONLY
+
 When customers adopt SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT, they don’t need to update their primary keys; however, this means that SIGN_ONLY sometimes means SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT leading to confusion
 
 #### Option Not Taken - Primary keys can be either SIGN_ONLY or SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT
+
 Even easier on customers, as they can change or not, but this still means that SIGN_ONLY sometimes means SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT leading to confusion
 
 ### Where to calculate the new encryption context entries?
 
 Currently, we generate the encryption context in the Item Encryptor, but only the Structure Encryptor has access to the header and its legend.
 
-#### Option Taken - Structure Encryptor 
+#### Option Taken - Structure Encryptor
+
 On Decrypt, the Structure Encryptor has the necessary context to determine which attributes were used in the encryption context.
 
 On encrypt, the Structure Encryptor adds to the required encryption context any attributes marked as SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT.
 
 On decrypt, the Structure Encryptor examines the legend in the header to determine which fields were SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT, and performs the same operation as in encrypt.
 
 #### Option Not Taken - Item Encryptor
+
 This would be simplest for Encrypt, as we already generate the encryption context in the Item Encryptor and pass it into the Structure Encryptor. Unfortunately, on Decrypt things are more complex, and we need to parse the header to find out which attributes were used in the encryption context. Trying to do this in the Item Encryptor would require too much back and forth across the Item/Structure boundary.
 
 # User Friendly Encryption Context
 
-## Background 
+## Background
 
 In the DBESDK, we include the values of the primary hash and sort keys in the encryption context. We serialize the AttributeValue into a a sequence of bytes (as per StructuredEncryption) and then Base64 encode the result.
 Thus the string “key” is in the encryption context as “AAFrZXk=”.
@@ -106,7 +113,7 @@ The branch key selector function takes a map of AttributeName to AttributeValue.
 
 Further, we can’t ameliorate this with something in the config file, or even the encrypted record’s version number, because the only input to the branch key selector function is the encryption context.
 
-#### Option Taken - plain strings, plus a legend.
+### Option Taken - plain strings, plus a legend
 
 In the version 2 records, add a new entry to the encryption context : aws-crypto-legend. Much like the legend in the StructuredEncryption header, this holds one character per attribute in the encryption context. Sort the keys in the encryption context and the values in the legend are in that same order.
 
@@ -123,7 +130,7 @@ Whenever we generate an encryption context, we know what record version we’re
 
 If a customer wants this new functionality, they can simply change their primary hash and sort keys to SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT.
 
-#### Option Not Taken : DynamoDB's JSON syntax
+### Option Not Taken : DynamoDB's JSON syntax
 
 We could do without the legend if we used the DynamoDB JSON syntax for values. Thus key would become {”S“ : ”key“}
 
@@ -133,28 +140,24 @@ This has the advantage of simplicity, and is more user friendly then the current
 * A key policy referring directly to {”S“ : ”key“} is still a suboptimal user experience
 * This would increase the size of the encryption context. Eventually somebody’s going to bump up against the 4K barrier for encryption contexts in KMS.
 
-#### Option Not Taken - Change interface to branch key selector
+### Option Not Taken - Change interface to branch key selector
 
 If this took a map of string to string, instead of an AttributeMap, then it would be ok to lose the type information. Unfortunately, this would break all the customers currently using one.
 
-#### Option Not Taken - Change interface to branch key selector for version 2 records
+### Option Not Taken - Change interface to branch key selector for version 2 records
 
 The place where we construct the branchKeyIdSupplier, we don’t know the version. Once we know the version, we’ve lost the knowledge of which supplier we are using.
 
-#### Option Not Taken - Deduce the type
+### Option Not Taken - Deduce the type
 
 Skip the legend. If it looks like a number or a literal, that’s what it is. If it ends with a ‘=’ it’s binary, otherwise it’s a string.
 This would work 99% of the time, but we need 100%.
 
-#### Option Not Taken - Pass in everything as a string
+### Option Not Taken - Pass in everything as a string
 
 We could store everything in this new way, but don’t keep the legend. Then wrap everything up as an AttributeValue of type String.
 Any customer with a binary key would be out of luck entirely.
 Any customer that actually cares about the difference between String(123) and Number(123) would also be sad.
 
 Add type information to the config for every SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT attribute.
 This would be great, except that the branch key selector doesn’t have access to the config.
-
-
-
-

specification/changes/2024-02-29-encryption-context/change.md

@@ -27,7 +27,7 @@ and therefore available to the Branch Key Selector.
 A fourth Crypto Action will be made available : `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, to join the existing `DO_NOTHING`, `SIGN_ONLY` and `ENCRYPT_AND_SIGN`.
 
 The presence of any SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT attribute in the configuration
-will cause a version 2 record to be written. 
+will cause a version 2 record to be written.
 
 If any SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT attribute is configured,
 then the primary partition and sort keys must also be SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT.
@@ -62,7 +62,7 @@ based solely on the encryption context -- since no configuration or version numb
 ### Parsed Header
 
 For both record versions, the Parsed Header returned from Structured Encryption operations now
-contains an additional field : the full encryption context. 
+contains an additional field : the full encryption context.
 
 Similarly, the Parsed Header returned from Item Encryptor operations now
 contains two additional fields : the full encryption context,
@@ -71,7 +71,7 @@ and the value map that would be passed to the Branch Key Selector.
 ## Implementation Changes
 
 For version 1 records, only the Item Encryptor operations know which attributes should
-be in the encryption context, 
+be in the encryption context,
 The logical table name, plus the names and values of the primary hash and sort keys,
 and so the full encryption context,
 along with the associated RequiredEncryptionContextCMM,
@@ -93,13 +93,13 @@ another layer of RequiredEncryptionContextCMM to include those value.
 To use this new functionality with the DynamoDB Enhanced Client in Java,
 tag your attribute with `@DynamoDbEncryptionSignAndIncludeInEncryptionContext`
 
-### Single Table Design
+## Single Table Design
 
 To better handle [Single-Table Design](https://aws.amazon.com/blogs/compute/creating-a-single-table-design-with-amazon-dynamodb/),
 one can now specify multiple schemas when building a DynamoDbEnhancedTableEncryptionConfig
 as shown below.
 
-```
+```java
 TableSchema<SimpleClass> tableSchema1 = TableSchema.fromBean(Class1.class);
 TableSchema<SimpleClass2> tableSchema2 = TableSchema.fromBean(Class2.class);
 TableSchema<SimpleClass3> tableSchema3 = TableSchema.fromBean(Class3.class);
@@ -121,4 +121,4 @@ TransactWriteItemsEnhancedRequest.builder()
   .addPutItem(table2, item2)
   .addPutItem(table3, item3)
   .build();
-```
+```