Using the DynamoDB Encryption Client for Java

This topic explains some of the features of the DynamoDB Encryption Client in Java that might not be found in other programming language implementations.

For details about programming with the DynamoDB Encryption Client, see the Java examples, the examples in the aws-dynamodb-encryption-java repository on GitHub, and the Javadoc for the DynamoDB Encryption Client.

Item encryptors: AttributeEncryptor and DynamoDBEncryptor

The DynamoDB Encryption Client in Java has two item encryptors: the lower-level DynamoDBEncryptor and the AttributeEncryptor.

The AttributeEncryptor is a helper class that helps you use the DynamoDBMapper in the AWS SDK for Java with the DynamoDB Encryptor in the DynamoDB Encryption Client. When you use the AttributeEncryptor with the DynamoDBMapper, it transparently encrypts and signs your items when you save them. It also transparently verifies and decrypts your items when you load them.

Configuring save behavior

You can use the AttributeEncryptor and DynamoDBMapper to add or replace table items with attributes that are signed only or encrypted and signed. For these tasks, we recommend that you configure it to use the PUT save behavior, as shown in the following example. Otherwise, you might not be able to decrypt your data.

DynamoDBMapperConfig mapperConfig = DynamoDBMapperConfig.builder().withSaveBehavior(SaveBehavior.PUT).build();
DynamoDBMapper mapper = new DynamoDBMapper(ddb, mapperConfig, new AttributeEncryptor(encryptor));

If you use the default save behavior, which updates only the attributes that are modeled in the table item, attributes that are not modeled are not included in the signature, and are not changed by table writes. As a result, on later reads of all attributes, the signature will not validate, because it doesn't include un-modeled attributes.

You can also use the CLOBBER save behavior. This behavior is identical to the PUT save behavior except that it disables optimistic locking and overwrites the item in the table.

To prevent signature errors, the DynamoDB Encryption Client throws a runtime exception if an AttributeEncryptor is used with a DynamoDBMapper that is not configured with a save behavior of CLOBBER or PUT.

To see this code used in an example, see Using the DynamoDBMapper and the AwsKmsEncryptedObject.java example in the aws-dynamodb-encryption-java repository in GitHub.

Attribute actions in Java

Attribute actions determine which attribute values are encrypted and signed, which are only signed, and which are ignored. The method you use to specify attribute actions depends on whether you use the DynamoDBMapper and AttributeEncryptor, or the lower-level DynamoDBEncryptor.

// Attributes are encrypted and signed
@DynamoDBAttribute(attributeName="Description")

// Partition keys are signed but not encrypted
@DynamoDBHashKey(attributeName="Title")

// Sort keys are signed but not encrypted
@DynamoDBRangeKey(attributeName="Author")

// Sign only
@DoNotEncrypt

// Do nothing; not encrypted or signed
@DoNotTouch

// Sign only (override the default)
@DoNotEncrypt
@DynamoDBAttribute(attributeName="PublicationYear")

// Do nothing (override the default)
@DoNotTouch
@DynamoDBAttribute(attributeName="ISBN")

ENCRYPT
SIGN

final EnumSet<EncryptionFlags> signOnly = EnumSet.of(EncryptionFlags.SIGN);
final EnumSet<EncryptionFlags> encryptAndSign = EnumSet.of(EncryptionFlags.ENCRYPT, EncryptionFlags.SIGN);
final Map<String, Set<EncryptionFlags>> actions = new HashMap<>();

for (final String attributeName : record.keySet()) {
  switch (attributeName) {
    case partitionKeyName: // no break; falls through to next case
    case sortKeyName:
      // Partition and sort keys must not be encrypted, but should be signed
      actions.put(attributeName, signOnly);
      break;
    case "test":
      // Don't encrypt or sign
      break;
    default:
      // Encrypt and sign everything else
      actions.put(attributeName, encryptAndSign);
      break;
  }
}

// Encrypt the plaintext record
final Map<String, AttributeValue> encrypted_record = encryptor.encryptRecord(record, actions, encryptionContext);

Overriding table names

In the DynamoDB Encryption Client, the name of the DynamoDB table is an element of the DynamoDB encryption context that is passed to the encryption and decryption methods. When you encrypt or sign table items, the DynamoDB encryption context, including the table name, is cryptographically bound to the ciphertext. If the DynamoDB encryption context that is passed to the decrypt method doesn't match the DynamoDB encryption context that was passed to the encrypt method, the decrypt operation fails.

Occasionally, the name of a table changes, such as when you back up a table or perform a point-in-time recovery. When you decrypt or verify the signature of these items, you must pass in the same DynamoDB encryption context that was used to encrypt and sign the items, including the original table name. The current table name is not needed.

When you use the DynamoDBEncryptor, you assemble the DynamoDB encryption context manually. However, if you are using the DynamoDBMapper, the AttributeEncryptor creates the DynamoDB encryption context for you, including the current table name. To tell the AttributeEncryptor to create an encryption context with a different table name, use the EncryptionContextOverrideOperator.

For example, the following code creates instances of the cryptographic materials provider (CMP) and the DynamoDBEncryptor. Then it calls the setEncryptionContextOverrideOperator method of the DynamoDBEncryptor. It uses the overrideEncryptionContextTableName operator, which overrides one table name. When it is configured this way, the AttributeEncryptor creates a DynamoDB encryption context that includes newTableName in place of oldTableName. For a complete example, see EncryptionContextOverridesWithDynamoDBMapper.java.

final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, keyArn);
final DynamoDBEncryptor encryptor = DynamoDBEncryptor.getInstance(cmp);

encryptor.setEncryptionContextOverrideOperator(EncryptionContextOperators.overrideEncryptionContextTableName(
                oldTableName, newTableName));

When you call the load method of the DynamoDBMapper, which decrypts and verifies the item, you specify the original table name.

mapper.load(itemClass, DynamoDBMapperConfig.builder()
                .withTableNameOverride(DynamoDBMapperConfig.TableNameOverride.withTableNameReplacement(oldTableName))
                .build());

You can also use the overrideEncryptionContextTableNameUsingMap operator, which overrides multiple table names.

The table name override operators are typically used when decrypting data and verifying signatures. However, you can use them to set the table name in the DynamoDB encryption context to a different value when encrypting and signing.

Do not use the table name override operators if you are using the DynamoDBEncryptor. Instead, create an encryption context with the original table name and submit it to the decryption method.