Direct KMS Materials Provider - AWS Database Encryption SDK
How to use itHow it works

Direct KMS Materials Provider

Note

Our client-side encryption library was renamed to AWS Database Encryption SDK. The following topic provides information on versions 1.x—2.x of the DynamoDB Encryption Client for Java and versions 1.x—3.x of the DynamoDB Encryption Client for Python. For more information, see AWS Database Encryption SDK for DynamoDB version support.

The Direct KMS Materials Provider (Direct KMS Provider) protects your table items under an AWS KMS key that never leaves AWS Key Management Service (AWS KMS) unencrypted. This cryptographic materials provider returns a unique encryption key and signing key for every table item. To do so, it calls AWS KMS every time you encrypt or decrypt an item.

If you're processing DynamoDB items at a high frequency and large scale, you might exceed the AWS KMS requests-per-second limits, causing processing delays. If you need to exceed a limit, create a case in the AWS Support Center. You might also consider using a cryptographic materials provider with limited key reuse, such as the Most Recent Provider.

To use the Direct KMS Provider, the caller must have an AWS account, at least one AWS KMS key, and permission to call the GenerateDataKey and Decrypt operations on the AWS KMS key. The AWS KMS key must be a symmetric encryption key; the DynamoDB Encryption Client does not support asymmetric encryption. If you are using a DynamoDB global table, you might want to specify an AWS KMS multi-Region key. For details, see How to use it.

Note

When you use the Direct KMS Provider, the names and values of your primary key attributes appear in plaintext in the AWS KMS encryption context and AWS CloudTrail logs of related AWS KMS operations. However, the DynamoDB Encryption Client never exposes the plaintext of any encrypted attribute values.

The Direct KMS Provider is one of several cryptographic materials providers (CMPs) that the DynamoDB Encryption Client supports. For information about the other CMPs, see Cryptographic materials provider.

For example code, see:

How to use it

To create a Direct KMS Provider, use the key ID parameter to specify a symmetric encryption KMS key in your account. The value of the key ID parameter can be the key ID, key ARN, alias name, or alias ARN of the AWS KMS key. For details about the key identifiers, see Key identifiers in the AWS Key Management Service Developer Guide.

The Direct KMS Provider requires a symmetric encryption KMS key. You cannot use an asymmetric KMS key. However, you can use a multi-Region KMS key, a KMS key with imported key material, or a KMS key in a custom key store. You must have kms:GenerateDataKey and kms:Decrypt permission on the KMS key. As such, you must use a customer managed key, not an AWS managed or AWS owned KMS key.

The DynamoDB Encryption Client for Python determines the Region for calling AWS KMS from the Region in the key ID parameter value, if it includes one. Otherwise, it uses the Region in the AWS KMS client, if you specify one, or the Region that you configure in the AWS SDK for Python (Boto3). For information about Region selection in Python, see Configuration in the AWS SDK for Python (Boto3) API Reference.

The DynamoDB Encryption Client for Java determines the Region for calling AWS KMS from the Region in the AWS KMS client, if the client you specify includes a Region. Otherwise, it uses the Region that you configure in the AWS SDK for Java. For information about Region selection in the AWS SDK for Java, see AWS Region selection in the AWS SDK for Java Developer Guide.

Java
// Replace the example key ARN and Region with valid values for your application
final String keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
final String region = 'us-west-2'
      
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, keyArn);
Python

The following example uses the key ARN to specify the AWS KMS key. If your key identifier doesn't include an AWS Region, the DynamoDB Encryption Client gets the Region from the configured Botocore session, if there is one, or from Boto defaults.

# Replace the example key ID with a valid value
kms_key = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=kms_key)

If you are using Amazon DynamoDB global tables, we recommend that you encrypt your data under an AWS KMS multi-Region key. Multi-Region keys are AWS KMS keys in different AWS Regions that can be used interchangeably because they have the same key ID and key material. For details, see Using multi-Region keys in the AWS Key Management Service Developer Guide.

Note

If you are using the global tables version 2017.11.29, you must set attribute actions so the reserved replication fields are not encrypted or signed. For details, see Issues with older version global tables.

To use a multi-Region key with the DynamoDB Encryption Client, create a multi-Region key and replicate it into the Regions in which your application runs. Then configure the Direct KMS Provider to use the multi-Region key in the Region in which the DynamoDB Encryption Client calls AWS KMS.

The following example configures the DynamoDB Encryption Client to encrypt data in the US East (N. Virginia) (us-east-1) Region and decrypt it in the US West (Oregon) (us-west-2) Region using a multi-Region key.

Java

In this example, the DynamoDB Encryption Client gets the Region for calling AWS KMS from the Region in the AWS KMS client. The keyArn value identifies a multi-Region key in the same Region.

// Encrypt in us-east-1

// Replace the example key ARN and Region with valid values for your application
final String usEastKey = 'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
final String region = 'us-east-1'
      
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, usEastKey);
// Decrypt in us-west-2

// Replace the example key ARN and Region with valid values for your application
final String usWestKey = 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
final String region = 'us-west-2'
      
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, usWestKey);
Python

In this example, the DynamoDB Encryption Client gets the Region for calling AWS KMS from the Region in the key ARN.

# Encrypt in us-east-1

# Replace the example key ID with a valid value
us_east_key = 'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=us_east_key)
# Decrypt in us-west-2

# Replace the example key ID with a valid value
us_west_key = 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=us_west_key)

How it works

The Direct KMS Provider returns encryption and signing keys that are protected by an AWS KMS key that you specify, as shown in the following diagram.

The input, processing, and output of the Direct KMS Provider in the DynamoDB Encryption Client

  • To generate encryption materials, the Direct KMS Provider asks AWS KMS to generate a unique data key for each item using an AWS KMS key that you specify. It derives encryption and signing keys for the item from the plaintext copy of the data key, and then returns the encryption and signing keys, along with the encrypted data key, which is stored in the material description attribute of the item.

    The item encryptor uses the encryption and signing keys and removes them from memory as soon as possible. Only the encrypted copy of the data key from which they were derived is saved in the encrypted item.

  • To generate decryption materials, the Direct KMS Provider asks AWS KMS to decrypt the encrypted data key. Then, it derives verification and signing keys from the plaintext data key, and returns them to the item encryptor.

    The item encryptor verifies the item and, if verification succeeds, decrypts the encrypted values. Then, it removes the keys from memory as soon as possible.

Get encryption materials

This section describes in detail the inputs, outputs, and processing of the Direct KMS Provider when it receives a request for encryption materials from the item encryptor.

Input (from the application)

  • The key ID of an AWS KMS key.

Input (from the item encryptor)

Output (to the item encryptor)

  • Encryption key (plaintext)

  • Signing key

  • In actual material description: These values are saved in the material description attribute that the client adds to the item.

    • amzn-ddb-env-key: Base64-encoded data key encrypted by the AWS KMS key

    • amzn-ddb-env-alg: Encryption algorithm, by default AES/256

    • amzn-ddb-sig-alg: Signing algorithm, by default, HmacSHA256/256

    • amzn-ddb-wrap-alg: kms

Processing

  1. The Direct KMS Provider sends AWS KMS a request to use the specified AWS KMS key to generate a unique data key for the item. The operation returns a plaintext key and a copy that is encrypted under the AWS KMS key. This is known as the initial key material.

    The request includes the following values in plaintext in AWS KMS encryption context. These non-secret values are cryptographically bound to the encrypted object, so the same encryption context is required on decrypt. You can use these values to identify the call to AWS KMS in AWS CloudTrail logs.

    • amzn-ddb-env-alg – Encryption algorithm, by default AES/256

    • amzn-ddb-sig-alg – Signing algorithm, by default HmacSHA256/256

    • (Optional) aws-kms-table – table name

    • (Optional) partition key name – partition key value (binary values are Base64-encoded)

    • (Optional) sort key name – sort key value (binary values are Base64-encoded)

    The Direct KMS Provider gets the values for the AWS KMS encryption context from the DynamoDB encryption context for the item. If the DynamoDB encryption context doesn't include a value, such as the table name, that name-value pair is omitted from the AWS KMS encryption context.

  2. The Direct KMS Provider derives a symmetric encryption key and a signing key from the data key. By default, it uses Secure Hash Algorithm (SHA) 256 and RFC5869 HMAC-based Key Derivation Function to derive a 256-bit AES symmetric encryption key and a 256-bit HMAC-SHA-256 signing key.

  3. The Direct KMS Provider returns the output to the item encryptor.

  4. The item encryptor uses the encryption key to encrypt the specified attributes and the signing key to sign them, using the algorithms specified in the actual material description. It removes the plaintext keys from memory as soon as possible.

Show moreShow less

Get decryption materials

This section describes in detail the inputs, outputs, and processing of the Direct KMS Provider when it receives a request for decryption materials from the item encryptor.

Input (from the application)

  • The key ID of an AWS KMS key.

    The value of the key ID can be the key ID, key ARN, alias name or alias ARN of the AWS KMS key. Any values that aren't included in the key ID, such as the Region, must be available in the AWS named profile. The key ARN provides all of the values that AWS KMS needs.

Input (from the item encryptor)

Output (to the item encryptor)

  • Encryption key (plaintext)

  • Signing key

Processing

  1. The Direct KMS Provider gets the encrypted data key from the material description attribute in the encrypted item.

  2. It asks AWS KMS to use the specified AWS KMS key to decrypt the encrypted data key. The operation returns a plaintext key.

    This request must use the same AWS KMS encryption context that was used to generate and encrypt the data key.

    • aws-kms-table – table name

    • partition key name – partition key value (binary values are Base64-encoded)

    • (Optional) sort key name – sort key value (binary values are Base64-encoded)

    • amzn-ddb-env-alg – Encryption algorithm, by default AES/256

    • amzn-ddb-sig-alg – Signing algorithm, by default HmacSHA256/256

  3. The Direct KMS Provider uses Secure Hash Algorithm (SHA) 256 and RFC5869 HMAC-based Key Derivation Function to derive a 256-bit AES symmetric encryption key and a 256-bit HMAC-SHA-256 signing key from the data key.

  4. The Direct KMS Provider returns the output to the item encryptor.

  5. The item encryptor uses the signing key to verify the item. If it succeeds, it uses the symmetric encryption key to decrypt the encrypted attribute values. These operations use the encryption and signing algorithms specified in the actual material description. The item encryptor removes the plaintext keys from memory as soon as possible.

Show moreShow less