Amazon DynamoDB Encryption Client
Developer Guide

Direct KMS Materials Provider

The Direct KMS Materials Provider (Direct KMS Provider) protects your table items under an AWS Key Management Service (AWS KMS) customer master key (CMK) that never leaves 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 limit, causing processing delays. If you need to exceed the request-per-second limit and avoid delays, create a case in the AWS Support Center.

To use the Direct KMS Provider, the caller must have an AWS account, at least one AWS KMS CMK, and permission to call the GenerateDataKey and Decrypt operations on the CMK.

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 provider (CMPs) that the DynamoDB Encryption Client supports. For information about the other CMPs, see How to Choose a Cryptographic Materials Provider.

For example code, see:

How to Use It

To create a Direct KMS Provider, specify an AWS KMS customer master key (CMK) in your account.

The value of the key ID parameter can be the ID or Amazon Resource Name (ARN) of the CMK, or an alias or alias ARN. Any values that are not specified in the ID, such as the region, must be available in the AWS named profile. The CMK ARN provides all of the values that AWS KMS needs.

JavaPython
Java
// Replace the example CMK ID and region with valid values for your application final String cmkArn = '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, cmkArn);
Python
// Replace the example CMK ID with a valid value aws_cmk_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' aws_kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=aws_cmk_id)

How It Works

The Direct KMS Provider returns encryption and signing keys that are protected by an AWS KMS CMK 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 a customer master key (CMK) 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 CMK.

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 CMK

    • 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 CMK to generate a unique data key for the item. The operation returns a plaintext key and a copy that is encrypted under the CMK. 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 namepartition key value (binary values are Base64-encoded)

    • (Optional) sort key namesort 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.

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 CMK.

    The value of the key ID can be the ID or Amazon Resource Name (ARN) of the CMK, or an alias or alias ARN, provided that any values that are omitted, such as the region, are available in the AWS named profile. The CMK 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 CMK 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 namepartition key value (binary values are Base64-encoded)

    • (Optional) sort key namesort 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.

On this page: