Amazon DynamoDB Encryption Client Developer Guide

(1)

Amazon DynamoDB Encryption Client

Developer Guide

(2)

Amazon DynamoDB Encryption Client: Developer Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

What is the Amazon DynamoDB Encryption Client?

The Amazon DynamoDB Encryption Client is a software library that enables you to include client- side encryption in your Amazon DynamoDB design. The DynamoDB Encryption Client is designed to be implemented in new, unpopulated databases. Encrypting your sensitive data in transit and at rest helps ensure that your plaintext data isn’t available to any third party, including AWS. The DynamoDB Encryption Client is provided free of charge under the Apache 2.0 license.

Important

The DynamoDB Encryption Client does not support the encryption of existing, unencrypted DynamoDB table data.

This developer guide provides a conceptual overview of the DynamoDB Encryption Client, including an introduction to its architecture (p. 5), details about how it protects DynamoDB table data (p. 2) and how it diﬀers from DynamoDB server-side encryption (p. 6), guidance on selecting critical components for your application (p. 12), and examples in each programming language (p. 32) to help you get started.

The DynamoDB Encryption Client has the following beneﬁts:

Designed especially for DynamoDB applications

You don’t need to be a cryptography expert to use the DynamoDB Encryption Client. The

implementations include helper methods that are designed to work with your existing DynamoDB applications.

After you create and conﬁgure the required components, the DynamoDB Encryption Client transparently encrypts and signs your table items when you add them to a table, and veriﬁes and decrypts them when you retrieve them.

The DynamoDB Encryption Client supports most Amazon DynamoDB features, including global tables. However, you might need to make some conﬁguration changes if you're using an older version of global tables. For details, see Issues with older version global tables (p. 55)..

Includes secure encryption and signing

The DynamoDB Encryption Client includes secure implementations that encrypt the attribute values in each table item using a unique encryption key, and then sign the item to protect it against unauthorized changes, such as adding or deleting attributes, or swapping encrypted values.

Uses cryptographic materials from any source

You can use the DynamoDB Encryption Client with encryption keys from any source, including your custom implementation or a cryptography service, such as AWS Key Management Service (AWS KMS) or AWS CloudHSM. The DynamoDB Encryption Client doesn't require an AWS account or any AWS service.

Programming language implementations are interoperable

The DynamoDB Encryption Client libraries are developed in open source projects on GitHub. They are currently available in Java and Python. All supported programming language implementations of the DynamoDB Encryption Client are interoperable. For example, you can encrypt data with the Java client and decrypt it with the Python client.

However, the DynamoDB Encryption Client is not compatible with the AWS Encryption SDK or the Amazon S3 Encryption Client. You cannot encrypt with one client-side library and decrypt with another.

(5)

Developed in open-source repositories

The Amazon DynamoDB Encryption Client is developed in open-source repositories on GitHub. You can use these repositories to view the code, read and submit issues, and ﬁnd information that is speciﬁc to your language implementation.

• DynamoDB Encryption Client for Java — aws-dynamodb-encryption-java

• DynamoDB Encryption Client for Python — aws-dynamodb-encryption-python

Support and maintenance

The DynamoDB Encryption Client uses the same maintenance policy that the AWS SDK and Tools use, including its versioning and life-cycle phases. As a best practice, we recommend that you use the latest available version of the DynamoDB Encryption Client for your programming language, and upgrade as new versions are released.

Each programming language implementation of the DynamoDB Encryption Client is developed in a separate open-source GitHub repository. The life-cycle and support phase of each version is likely to vary among repositories. For example, a given version of the DynamoDB Encryption Client might be in the general availability (full support) phase in one programming language, but the end-of-support phase in a diﬀerent programming language. We recommend that you use a fully supported version whenever possible and avoid versions that are no longer supported.

To ﬁnd the life-cycle phase of DynamoDB Encryption Client versions for your programming language, see the SUPPORT_POLICY.rst ﬁle in each DynamoDB Encryption Client repository.

• DynamoDB Encryption Client for Java — SUPPORT_POLICY.rst

• DynamoDB Encryption Client for Python — SUPPORT_POLICY.rst

For more information, see the AWS SDKs and Tools maintenance policy in the AWS SDKs and Tools Reference Guide.

Sending feedback

We welcome your feedback! If you have a question or comment, or an issue to report, please use the following resources.

• If you discover a potential security vulnerability in the DynamoDB Encryption Client, please notify AWS security. Do not create a public GitHub issue.

• To provide feedback on the DynamoDB Encryption Client, ﬁle an issue in the aws-dynamodb- encryption-java or aws-dynamodb-encryption-python GitHub repository.

• To provide feedback on this documentation, use the feedback link on any page. You can also ﬁle an issue or contribute to aws-dynamodb-encryption-docs, the open-source repository for this documentation on GitHub.

Which ﬁelds are encrypted and signed?

In DynamoDB, a table is a collection of items. Each item is a collection of attributes. Each attribute has a name and a value.

(6)

Encrypting attribute values

The DynamoDB Encryption Client encrypts the values of attributes. Then, it calculates a signature over the attributes. You can specify which attribute values to encrypt and which to include in the signature.

However, the DynamoDB Encryption Client is designed to be implemented in new, unpopulated

databases. You need to add the encryption features to your DynamoDB applications before you send any data to DynamoDB.

Encryption protects the conﬁdentiality of the attribute value. Signing provides integrity of all signed attributes and their relationship to each other, and provides authentication. It enables you to detect unauthorized changes to the item as a whole, including adding or deleting attributes, or substituting one encrypted value for another.

In an encrypted item, some data remains in plaintext, including the table name, all attribute names, the attribute values that you don't encrypt, and the names and values of the primary key (partition key and sort key) attributes. Do not store sensitive data in these ﬁelds.

Topics

• Encrypting attribute values (p. 3)

• Signing the item (p. 4)

• An encrypted and signed item (p. 4)

Encrypting attribute values

The DynamoDB Encryption Client encrypts the values (but not the names) of the attributes that you specify. To determine which attribute values are encrypted, use attribute actions (p. 9).

For example, this item includes example and test attributes.

'example': 'data', 'test': 'test-value', ...

If you encrypt the example attribute, but don't encrypt the test attribute, the results look like the following. The encrypted example attribute value is binary data, instead of a string.

'example': Binary(b"'b\x933\x9a+s\xf1\xd6a\xc5\xd5\x1aZ\xed\xd6\xce\xe9X\xf0T\xcb\x9fY\x9f

\xf3\xc9C\x83\r\xbb\\"), 'test': 'test-value' ...

The primary key attributes—partition key and sort key—of each item must remain in plaintext because DynamoDB uses them to ﬁnd the item in the table. They should be signed, but not encrypted.

Warning

Do not encrypt the primary key attributes. They must remain in plaintext so DynamoDB can ﬁnd the item without running a full table scan.

The helpers in each programming language identify the primary key attributes for you and ensure that their values are signed, but not encrypted. And, if you identify your primary key and then try to encrypt it, the client will throw an exception. If you need to encrypt the primary key for a special use case, use the lower-level item encryptor (p. 9) directly, but remember that DynamoDB will not be able to ﬁnd your item without running a full table scan.

The DynamoDB Encryption Client also does not encrypt or sign the material description

attribute (p. 9), which stores information that the DynamoDB Encryption Client needs to verify and decrypt the item.

(7)

Signing the item

After encrypting the speciﬁed attribute values, the DynamoDB Encryption Client calculates a digital signature over the names and values of attributes that you specify in the attribute actions (p. 9) object. The client saves the signature in an attribute that it adds to the item.

If you provide a table name, it's included in the signature. This allows you to detect that a signed item was moved to a diﬀerent table, perhaps maliciously, such as moving an employee record from the AllEmployees to TrustedEmployees table. The DynamoDB Encryption Client gets the table name from the DynamoDB encryption context (p. 10), where it is an optional ﬁeld.

Be sure to include the primary key in the signature. It's the default behavior when you use a helper. The signature captures the relationship between the primary key and other attributes in the item, and the signature validation veriﬁes that the relationship hasn't changed.

The material description attribute (p. 9) is not encrypted or signed.

An encrypted and signed item

When the DynamoDB Encryption Client encrypts and signs a table item, the result is a standard DynamoDB table item with encrypted attribute values.

The following ﬁgure shows a part of an example encrypted and signed table item.

The ﬁgure shows the following characteristics of table items that the DynamoDB Encryption Client encrypts and signs:

• All attribute names are in plaintext.

• The values of the primary key attributes are in plaintext. In this example, the partition key name is partition_attribute and the sort key name is sort_attribute.

• The values of any attributes that you tell the client not to encrypt remain in plaintext. In this example, the value of the test attribute is in plaintext.

• The values of encrypted attributes are binary data.

• The client adds a signature attribute (*amzn-ddb-map-sig*) to the item. Its value is the item signature.

(8)

How it works

• The client adds a material description attribute (p. 9) (*amzn-ddb-map-desc*) to the item. Its value describes how the attribute was encrypted and signed. The client uses this information to verify and decrypt the item. The material description attribute is not encrypted or signed.

How the DynamoDB Encryption Client works

The DynamoDB Encryption Client is designed speciﬁcally to protect the data that you store in

DynamoDB. The libraries include secure implementations that you can extend or use unchanged. And, most elements are represented by abstract elements so you can create and use compatible custom components.

Encrypting and signing table items

At the core of the DynamoDB Encryption Client is an item encryptor that encrypts, signs, veriﬁes, and decrypts table items. It takes in information about your table items and instructions about which items to encrypt and sign. It gets the encryption materials, and instructions on how to use them, from a cryptographic material provider (p. 8) that you select and conﬁgure.

The following diagram shows a high-level view of this process.

To encrypt and sign a table item, the DynamoDB Encryption Client needs:

• Information about the table. It gets information about the table from a DynamoDB encryption context (p. 10) that you supply. Some helpers get the required information from DynamoDB and create the DynamoDB encryption context for you.

Note

The DynamoDB encryption context in the DynamoDB Encryption Client is not related to the encryption context in AWS Key Management Service (AWS KMS) and the AWS Encryption SDK.

• Which attributes to encrypt and sign. It gets this information from the attribute actions (p. 9) that you supply.

• Encryption materials, including encryption and signing keys. It gets these from a cryptographic materials provider (p. 8) (CMP) that you select and conﬁgure.

• Instructions for encrypting and signing the item. The CMP adds instructions for using the encryption materials, including encryption and signing algorithms, to the actual material description (p. 9).

(9)

Client-side and server-side encryption

The item encryptor (p. 9) uses all of these elements to encrypt and sign the item. The item encryptor also adds two attributes to the item: a material description attribute (p. 9) that contains the

encryption and signing instructions (the actual material description), and an attribute that contains the signature. You can interact with the item encryptor directly, or use helper features that interact with the item encryptor for you to implement secure default behavior.

The result is a DynamoDB item containing encrypted and signed data.

Verifying and decrypting table items

These components also work together to verify and decrypt your item, as shown in the following diagram.

To verify and decrypt an item, the DynamoDB Encryption Client needs the same components,

components with the same conﬁguration, or components especially designed for decrypting the items, as follows:

• Information about the table from the DynamoDB encryption context (p. 10).

• Which attributes to verify and decrypt. It gets these from the attribute actions (p. 9).

• Decryption materials, including veriﬁcation and decryption keys, from the cryptographic materials provider (p. 8) (CMP) that you select and conﬁgure.

The encrypted item doesn't include any record of the CMP that was used to encrypt it. You must supply the same CMP, a CMP with the same conﬁguration, or a CMP that is designed to decrypt items.

• Information about how the item was encrypted and signed, including the encryption and signing algorithms. The client gets these from the material description attribute (p. 9) in the item.

The item encryptor (p. 9) uses all of these elements to verify and decrypt the item. It also removes the material description and signature attributes. The result is a plaintext DynamoDB item.

Client-side and server-side encryption

The DynamoDB Encryption Client supports client-side encryption, where you encrypt your table data before you send it to DynamoDB. However, DynamoDB provides a server-side encryption at rest feature

(10)

Client-side and server-side encryption

that transparently encrypts your table when it is persisted to disk and decrypts it when you access the table.

The tools that you choose depend on the sensitivity of your data and the security requirements of your application. You can use both the DynamoDB Encryption Client and encryption at rest. When you send encrypted and signed items to DynamoDB, DynamoDB doesn't recognize the items as being protected. It just detects typical table items with binary attribute values.

Server-side encryption at rest

DynamoDB supports encryption at rest, a server-side encryption feature in which DynamoDB

transparently encrypts your tables for you when the table is persisted to disk, and decrypts them when you access the table data.

With server-side encryption, your data is encrypted in transit over an HTTPS connection, decrypted at the DynamoDB endpoint, and then re-encrypted before being stored in DynamoDB.

• Encryption by default. DynamoDB transparently encrypts and decrypts all tables when they are written to disk. There is no option to enable or disable encryption at rest.

• DynamoDB creates and manages the cryptographic keys. The unique key for each table is protected by an AWS KMS key that never leaves AWS Key Management Service (AWS KMS) unencrypted. By default, DynamoDB uses an AWS owned key in the DynamoDB service account, but you can choose an AWS managed key or customer managed key in your account to protect some or all of your tables.

• All table data is encrypted on disk. When an encrypted table is saved to disk, DynamoDB encrypts all table data, including the primary key and local and global secondary indexes. If your table has a sort key, some of the sort keys that mark range boundaries are stored in plaintext in the table metadata.

• Objects related to tables are encrypted, too. Encryption at rest protects DynamoDB streams, global tables, and backups whenever they are written to durable media.

• Your items are decrypted when you access them. When you access the table, DynamoDB decrypts the part of the table that includes your target item, and returns the plaintext item to you.

DynamoDB Encryption Client

Client-side encryption provides end-to-end protection for your data, in transit and at rest, from its source to storage in DynamoDB. Your plaintext data is never exposed to any third party, including AWS. However, the DynamoDB Encryption Client is designed to be implemented in new, unpopulated databases. You need to add the encryption features to your DynamoDB applications before you send any data to DynamoDB.

• Your data is protected in transit and at rest. It is never exposed to any third party, including AWS.

• You can sign your table Items. You can direct the DynamoDB Encryption Client to calculate a signature over all or part of a table item, including the primary key attributes and the table name.

This signature allows you to detect unauthorized changes to the item as a whole, including adding or deleting attributes, or swapping attribute values.

• You choose how your cryptographic keys are generated and protected. You can create and manage your keys, or use a cryptographic service, such as AWS Key Management Service or AWS CloudHSM, to generate and protect your keys.

• You determine how your data is protected by selecting a cryptographic materials provider (p. 12) (CMP), or writing one of your own. The CMP determines the encryption strategy used, including when unique keys are generated, and the encryption and signing algorithms that are used.

• The DynamoDB Encryption Client doesn't encrypt the entire table. You can encrypt selected items in a table, or selected attribute values in some or all items. However, the DynamoDB Encryption Client does not encrypt an entire item. It does not encrypt attribute names, or the names or values of the

(11)

Concepts

primary key (partition key and sort key) attributes. For details about what is encrypted (and what is not), see Which ﬁelds are encrypted and signed? (p. 2).

AWS Encryption SDK

If you are encrypting data that you store in DynamoDB, we recommend the DynamoDB Encryption Client.

The AWS Encryption SDK is a client-side encryption library that helps you to encrypt and decrypt generic data. Although it can protect any type of data, it isn't designed to work with structured data, like database records. Unlike the DynamoDB Encryption Client, the AWS Encryption SDK cannot provide item-level integrity checking and it has no logic to recognize attributes or prevent encryption of primary keys.

If you use the AWS Encryption SDK to encrypt any element of your table, remember that it isn't

compatible with the DynamoDB Encryption Client. You cannot encrypt with one library and decrypt with the other.

Amazon DynamoDB Encryption Client concepts

This topic explains the concepts and terminology used in the Amazon DynamoDB Encryption Client.

To learn how the components of the DynamoDB Encryption Client interact, see How the DynamoDB Encryption Client works (p. 5).

Topics

• Cryptographic materials provider (CMP) (p. 8)

• Item encryptors (p. 9)

• Attribute actions (p. 9)

• Material description (p. 9)

• DynamoDB encryption context (p. 10)

• Provider store (p. 10)

Cryptographic materials provider (CMP)

When implementing the DynamoDB Encryption Client, one of your ﬁrst tasks is to select a cryptographic materials provider (p. 12) (CMP) (also known as an encryption materials provider). Your choice

determines much of the rest of the implementation.

A cryptographic materials provider (CMP) collects, assembles, and returns the cryptographic materials that the item encryptor (p. 9) uses to encrypt and sign your table items. The CMP determines the encryption algorithms to use and how to generate and protect encryption and signing keys.

The CMP interacts with the item encryptor. The item encryptor requests encryption or decryption materials from the CMP, and the CMP returns them to the item encryptor. Then, the item encryptor uses the cryptographic materials to encrypt and sign, or verify and decrypt, the item.

You specify the CMP when you conﬁgure the client. You can create a compatible custom CMP, or use one of the many CMPs in the library. Most CMPs are available for multiple programming languages.

(12)

Item encryptors

The item encryptor is a lower-level component that performs cryptographic operations for the DynamoDB Encryption Client. It requests cryptographic materials from a cryptographic materials provider (p. 8) (CMP), then uses the materials that the CMP returns to encrypt and sign, or verify and decrypt, your table item.

You can interact with the item encryptor directly or use the helpers that your library provides. For example, the DynamoDB Encryption Client for Java includes an AttributeEncryptor helper class that you can use with the DynamoDBMapper, instead of interacting directly with the DynamoDBEncryptor item encryptor. The Python library includes EncryptedTable, EncryptedClient, and

EncryptedResource helper classes that interact with the item encryptor for you.

Attribute actions

Attribute actions tell the item encryptor which actions to perform on each attribute of the item.

The attribute action values can be one of the following:

• Encrypt and sign – Encrypt the attribute value. Include the attribute (name and value) in the item signature.

• Sign only – Include the attribute in the item signature.

• Do nothing – Do not encrypt or sign the attribute.

For any attribute that can store sensitive data, use Encrypt and sign. For primary key attributes (partition key and sort key), use Sign only. The material description attribute (p. 9) and the signature attribute are not signed or encrypted. You don't need to specify attribute actions for these attributes.

Choose your attribute actions carefully. When in doubt, use Encrypt and sign. Once you have used the DynamoDB Encryption Client to protect your table items, you cannot change the action for an attribute without risking a signature validation error. For details, see Changing your data model (p. 50).

Warning

Do not encrypt the primary key attributes. They must remain in plaintext so DynamoDB can ﬁnd the item without running a full table scan.

If the DynamoDB encryption context (p. 10) identiﬁes your primary key attributes, the client will throw an error if you try to encrypt them.

The technique that you use to specify the attribute actions is diﬀerent for each programming language.

It might also be speciﬁc to helper classes that you use.

For details, see the documentation for your programming language.

• Python (p. 44)

• Java (p. 34)

Material description

The material description for an encrypted table item consists of information, such as encryption algorithms, about how the table item is encrypted and signed. The cryptographic materials

provider (p. 8) (CMP) records the material description as it assembles the cryptographic materials for encryption and signing. Later, when it needs to assemble cryptographic materials to verify and decrypt the item, it uses the material description as its guide.

(13)

DynamoDB encryption context

In the DynamoDB Encryption Client, the material description refers to three related elements:

Requested material description

Some cryptographic materials providers (p. 8) (CMPs) let you specify advanced options, such as an encryption algorithm. To indicate your choices, you add name-value pairs to the material description property of the DynamoDB encryption context (p. 10) in your request to encrypt a table item. This element is known as the requested material description. The valid values in the requested material description are deﬁned by the CMP that you choose.

NoteBecause the material description can override secure default values, we recommend that you omit the requested material description unless you have a compelling reason to use it.

Actual material description

The material description that the cryptographic materials providers (p. 8) (CMPs) return is known as the actual material description. It describes the actual values that the CMP used when it assembled the cryptographic materials. It usually consists of the requested material description, if any, with additions and changes.

Material description attribute

The client saves the actual material description in the material description attribute of the encrypted item. The material description attribute name is amzn-ddb-map-desc and its value is the actual material description. The client uses the values in the material description attribute to verify and decrypt the item.

DynamoDB encryption context

The DynamoDB encryption context supplies information about the table and item to the cryptographic materials provider (p. 8) (CMP). In advanced implementations, the DynamoDB encryption context can include a requested material description (p. 9).

When you encrypt table items, the DynamoDB encryption context is cryptographically bound to the encrypted attribute values. When you decrypt, if the DynamoDB encryption context is not an exact, case- sensitive match for the DynamoDB encryption context that was used to encrypt, the decrypt operation fails. If you interact with the item encryptor (p. 9) directly, you must provide a DynamoDB encryption context when you call an encrypt or decrypt method. Most helpers create the DynamoDB encryption context for you.

NoteThe DynamoDB encryption context in the DynamoDB Encryption Client is not related to the encryption context in AWS Key Management Service (AWS KMS) and the AWS Encryption SDK.

The DynamoDB encryption context can include the following ﬁelds. All ﬁelds and values are optional.

• Table name

• Partition key name

• Sort key name

• Attribute name-value pairs

• Requested material description (p. 9)

Provider store

A provider store is a component that returns cryptographic materials providers (p. 8) (CMPs). The

provider store can create the CMPs or get them from another source, such as another provider store. The

(14)

Provider store

provider store saves versions of the CMPs that it creates in persistent storage in which each stored CMP is identiﬁed by the material name of the requester and version number.

The Most Recent Provider (p. 21) in the DynamoDB Encryption Client gets its CMPs from a provider store, but you can use the provider store to supply CMPs to any component. Each Most Recent Provider is associated with one provider store, but a provider store can supply CMPs to many requesters across multiple hosts.

The provider store creates new versions of CMPs on demand, and returns new and existing versions. It also returns the latest version number for a given material name. This lets the requester know when the provider store has a new version of its CMP that it can request.

The DynamoDB Encryption Client includes a MetaStore (p. 24), which is a provider store that creates Wrapped CMPs with keys that are stored in DynamoDB and encrypted by using an internal DynamoDB Encryption Client.

Learn more:

• Provider store: Java, Python

• MetaStore: Java, Python

(15)

How to choose a cryptographic materials provider

One of the most important decisions you make when using the DynamoDB Encryption Client is selecting a cryptographic materials provider (p. 8) (CMP). The CMP assembles and returns cryptographic materials to the item encryptor. It also determines how encryption and signing keys are generated, whether new key materials are generated for each item or are reused, and the encryption and signing algorithms that are used.

You can choose a CMP from the implementations provided in the DynamoDB Encryption Client libraries or build a compatible custom CMP. Your CMP choice might also depend on the programming language (p. 32) that you use.

This topic describes the most common CMPs and oﬀers some advice to help you choose the best one for your application.

Direct KMS Materials Provider

The Direct KMS Materials Provider protects your table items under an AWS KMS key that never leaves AWS Key Management Service (AWS KMS) unencrypted. Your application doesn't have to generate or manage any cryptographic materials. Because it uses the AWS KMS key to generate unique encryption and signing keys for each item, this provider calls AWS KMS every time it encrypts or decrypts an item.

If you use AWS KMS and one AWS KMS call per transaction is practical for your application, this provider is a good choice.

For details, see Direct KMS Materials Provider (p. 13).

Wrapped Materials Provider (Wrapped CMP)

The Wrapped Materials Provider (Wrapped CMP) lets you generate and manage your wrapping and signing keys outside of the DynamoDB Encryption Client.

The Wrapped CMP generates a unique encryption key for each item. Then it uses wrapping (or unwrapping) and signing keys that you supply. As such, you determine how the wrapping and signing keys are generated and whether they are unique to each item or are reused. The Wrapped CMP is a secure alternative to the Direct KMS Provider (p. 13) for applications that don't use AWS KMS and can safely manage cryptographic materials.

For details, see Wrapped Materials Provider (p. 18).

Most Recent Provider

The Most Recent Provider is a cryptographic materials provider (p. 8) (CMP) that is designed to work with a provider store (p. 10). It gets CMPs from the provider store, and gets the cryptographic materials that it returns from the CMPs. The Most Recent Provider typically uses each CMP to satisfy multiple requests for cryptographic materials, but you can use the features of the provider store to control the extent to which materials are reused, determine how often its CMP is rotated, and even change the type of CMP that is used without changing the Most Recent Provider.

You can use the Most Recent Provider with any compatible provider store. The DynamoDB Encryption Client includes a MetaStore, which is a provider store that returns Wrapped CMPs.

The Most Recent Provider is a good choice for applications that need to minimize calls to their cryptographic source, and applications that can reuse some cryptographic materials without

(16)

Direct KMS Provider

violating their security requirements. For example, it allows you to protect your cryptographic materials under an AWS KMS key in AWS Key Management Service (AWS KMS) without calling AWS KMS every time you encrypt or decrypt an item.

For details, see Most Recent Provider (p. 21).

Static Materials Provider

The Static Materials Provider is designed for testing, proof-of-concept demonstrations, and legacy compatibility. It doesn't generate any unique cryptographic materials for each item. It returns the same encryption and signing keys that you supply, and those keys are used directly to encrypt, decrypt, and sign your table items.

NoteThe Asymmetric Static Provider in the Java library is not a static provider. It just supplies alternate constructors for the Wrapped CMP (p. 18). It is safe for production use, but you should use the Wrapped CMP directly whenever possible.

Topics

• Direct KMS Materials Provider (p. 13)

• Wrapped Materials Provider (p. 18)

• Most Recent Provider (p. 21)

• Static Materials Provider (p. 29)

Direct KMS Materials Provider

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 (p. 8) 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 (p. 21).

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 symmetric; 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 (p. 14).

NoteWhen 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 (p. 8) (CMPs) that the DynamoDB Encryption Client supports. For information about the other CMPs, see How to choose a cryptographic materials provider (p. 12).

For example code, see:

• Java: AwsKmsEncryptedItem

• Python: aws-kms-encrypted-table, aws-kms-encrypted-item

(17)

How to use it

Topics

• How to use it (p. 14)

• How it works (p. 15)

How to use it

To create a Direct KMS Provider, use the key ID parameter to specify a symmetric encryption AWS 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 identiﬁers, see Key identiﬁers 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 conﬁgure in the AWS SDK for Python (Boto3). For information about Region selection in Python, see Conﬁguration 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 conﬁgure 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 identiﬁer doesn't include an AWS Region, the DynamoDB Encryption Client gets the Region from the conﬁgured 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 diﬀerent 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.

NoteIf you are using the global tables version 2017.11.29, you must set attribute actions so the reserved replication ﬁelds are not encrypted or signed. For details, see Issues with older version global tables (p. 55).

(18)

How it works

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 conﬁgure 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 conﬁgures 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 identiﬁes 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 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 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.

(19)

How it works

• 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 (p. 9) 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 veriﬁcation and signing keys from the plaintext data key, and returns them to the item encryptor.

The item encryptor veriﬁes the item and, if veriﬁcation 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 (p. 9).

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)

(20)

How it works

• Signing key

• In actual material description (p. 9): 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 speciﬁed 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 (p. 10) 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 speciﬁed attributes and the signing key to sign them, using the algorithms speciﬁed 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 (p. 9).

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 proﬁle. The key ARN provides all of the values that AWS KMS needs.

• A copy of the DynamoDB encryption context (p. 10) that contains the contents of the material description attribute.

(21)

Wrapped Provider

• 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 speciﬁed 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 speciﬁed in the actual material description. The item encryptor removes the plaintext keys from memory as soon as possible.

Wrapped Materials Provider

The Wrapped Materials Provider (Wrapped CMP) lets you use wrapping and signing keys from any source with the DynamoDB Encryption Client. The Wrapped CMP does not depend on any AWS service.

However, you must generate and manage your wrapping and signing keys outside of the client, including providing the correct keys to verify and decrypt the item.

The Wrapped CMP generates a unique item encryption key for each item. It wraps the item encryption key with the wrapping key that you provide and saves the wrapped item encryption key in the material description attribute (p. 9) of the item. Because you supply the wrapping and signing keys, you

determine how the wrapping and signing keys are generated and whether they are unique to each item or are reused.

The Wrapped CMP is a secure implementation and a good choice for applications that can manage cryptographic materials.

The Wrapped CMP is one of several cryptographic materials providers (p. 8) (CMPs) that the DynamoDB Encryption Client supports. For information about the other CMPs, see How to choose a cryptographic materials provider (p. 12).

• Java: AsymmetricEncryptedItem

• Python: wrapped-rsa-encrypted-table, wrapped-symmetric-encrypted-table

(22)

How to use it

Topics

How to use it

To create a Wrapped CMP, specify a wrapping key (required on encrypt), an unwrapping key (required on decrypt), and a signing key. You must supply keys when you encrypt and decrypt items.

The wrapping, unwrapping, and signing keys can be symmetric keys or asymmetric key pairs.

Java

// This example uses asymmetric wrapping and signing key pairs final KeyPair wrappingKeys = ...

final KeyPair signingKeys = ...

final WrappedMaterialsProvider cmp =

new WrappedMaterialsProvider(wrappingKeys.getPublic(), wrappingKeys.getPrivate(), signingKeys);

Python

# This example uses symmetric wrapping and signing keys wrapping_key = ...

signing_key = ...

wrapped_cmp = WrappedCryptographicMaterialsProvider(

wrapping_key=wrapping_key, unwrapping_key=wrapping_key, signing_key=signing_key )

How it works

The Wrapped CMP generates a new item encryption key for every item. It uses the wrapping, unwrapping, and signing keys that you provide, as shown in the following diagram.

(23)

How it works

Get encryption materials

This section describes in detail the inputs, outputs, and processing of the Wrapped Materials Provider (Wrapped CMP) when it receives a request for encryption materials.

Input (from application)

• Wrapping key: An Advanced Encryption Standard (AES) symmetric key, or an RSA public key. Required if any attribute values are encrypted. Otherwise, it is optional and ignored.

• Unwrapping key: Optional and ignored.

• Signing key

Output (to the item encryptor):

• Plaintext item encryption key

• Signing key (unchanged)

• Actual material description (p. 9): These values are saved in the material description attribute (p. 9) that the client adds to the item.

• amzn-ddb-env-key: Base64-encoded wrapped item encryption key

• amzn-ddb-env-alg: Encryption algorithm used to encrypt the item. The default is AES-256-CBC.

• amzn-ddb-wrap-alg: The wrapping algorithm that the Wrapped CMP used to wrap the item encryption key. If the wrapping key is an AES key, the key is wrapped using unpadded AES-Keywrap as deﬁned in RFC 3394. If the wrapping key is an RSA key, the key is encrypted by using RSA OAEP with MGF1 padding.

Processing

When you encrypt an item, you pass in a wrapping key and a signing key. An unwrapping key is optional and ignored.

1. The Wrapped CMP generates a unique symmetric item encryption key for the table item.

2. It uses the wrapping key that you specify to wrap the item encryption key. Then, it removes it from memory as soon as possible.

3. It returns the plaintext item encryption key, the signing key that you supplied, and an actual material description (p. 9) that includes the wrapped item encryption key, and the encryption and wrapping algorithms.

4. The item encryptor uses the plaintext encryption key to encrypt the item. It uses the signing key that you supplied to sign the item. Then, it removes the plaintext keys from memory as soon as possible. It copies the ﬁelds in the actual material description, including the wrapped encryption key (amzn-ddb- env-key), to the material description attribute of the item.

Get decryption materials

This section describes in detail the inputs, outputs, and processing of the Wrapped Materials Provider (Wrapped CMP) when it receives a request for decryption materials.

Input (from application)

(24)

Most Recent Provider

• Wrapping key: Optional and ignored.

• Unwrapping key: The same Advanced Encryption Standard (AES) symmetric key or RSA private key that corresponds to the RSA public key used to encrypt. Required if any attribute values are encrypted.

Otherwise, it is optional and ignored.

• Signing key

• A copy of the DynamoDB encryption context (p. 10) that contains the contents of the material description attribute.

• Plaintext item encryption key

• Signing key (unchanged)

Processing

When you decrypt an item, you pass in an unwrapping key and a signing key. A wrapping key is optional and ignored.

1. The Wrapped CMP gets the wrapped item encryption key from the material description attribute of the item.

2. It uses the unwrapping key and algorithm to unwrap the item encryption key.

3. It returns the plaintext item encryption key, the signing key, and encryption and signing algorithms to the item encryptor.

4. The item encryptor uses the signing key to verify the item. If it succeeds, it uses the item encryption key to decrypt the item. Then, it removes the plaintext keys from memory as soon as possible.

Most Recent Provider

The Most Recent Provider is a cryptographic materials provider (p. 8) (CMP) that is designed to work with a provider store (p. 10). It gets CMPs from the provider store, and gets the cryptographic materials that it returns from the CMPs. It typically uses each CMP to satisfy multiple requests for cryptographic materials. But you can use the features of its provider store to control the extent to which materials are reused, determine how often its CMP is rotated, and even change the type of CMP that it uses without changing the Most Recent Provider.

NoteThe code associated with the MostRecentProvider symbol for the Most Recent Provider might store cryptographic materials in memory for the lifetime of the process. It might allow a caller to use keys that they're no longer authorized to use.

The MostRecentProvider symbol is deprecated in older supported versions of the DynamoDB Encryption Client and removed from version 2.0.0. It is replaced by the CachingMostRecentProvider symbol. For details, see Updates to the Most Recent Provider (p. 28).

The Most Recent Provider is a good choice for applications that need to minimize calls to the provider store and its cryptographic source, and applications that can reuse some cryptographic materials without violating their security requirements. For example, It allows you to protect your cryptographic materials under an AWS KMS key in AWS Key Management Service (AWS KMS) without calling AWS KMS every time you encrypt or decrypt an item.

(25)

How to use it

The provider store that you choose determines the type of CMPs that the Most Recent Provider uses and how often it gets a new CMP. You can use any compatible provider store with the Most Recent Provider, including custom provider stores that you design.

The DynamoDB Encryption Client includes a MetaStore that creates and returns Wrapped Materials Providers (p. 18) (Wrapped CMPs). The MetaStore saves multiple versions of the Wrapped CMPs that it generates in an internal DynamoDB table and protects them with client-side encryption by an internal instance of the DynamoDB Encryption Client.

You can conﬁgure the MetaStore to use any type of internal CMP to protect the materials in the table, including a Direct KMS Provider (p. 13) that generates cryptographic materials protected by your AWS KMS key, a Wrapped CMP that uses wrapping and signing keys that you supply, or a compatible custom CMP that you design.

• Java: MostRecentEncryptedItem

• Python: most_recent_provider_encrypted_table

Topics

• Updates to the Most Recent Provider (p. 28)

How to use it

To create a Most Recent Provider, you need to create and conﬁgure a provider store, and then create a Most Recent Provider that uses the provider store.

The following examples show how to create a Most Recent Provider that uses a MetaStore and protects the versions in its internal DynamoDB table with cryptographic materials from a Direct KMS Provider (p. 13). These examples use the CachingMostRecentProvider (p. 28) symbol.

Each Most Recent Provider has a name that identiﬁes its CMPs in the MetaStore table, a time-to- live (p. 25) (TTL) setting, and a cache size setting that determines how many entries the cache can hold. These examples set the cache size to 1000 entries and a TTL of 60 seconds.

Java

// Set the name for MetaStore's internal table final String keyTableName = 'metaStoreTable' // Set the Region and AWS KMS key

final String region = 'us-west-2' final String keyArn = 'arn:aws:kms:us-

west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' // Set the TTL and cache size

final long ttlInMillis = 60000;

final long cacheSize = 1000;

// Name that identifies the MetaStore's CMPs in the provider store final String materialName = 'testMRP'

// Create an internal DynamoDB client for the MetaStore final AmazonDynamoDB ddb =

AmazonDynamoDBClientBuilder.standard().withRegion(region).build();

(26)

How it works

// Create an internal Direct KMS Provider for the MetaStore

final DirectKmsMaterialProvider kmsProv = new DirectKmsMaterialProvider(kms, keyArn);

// Create an item encryptor for the MetaStore, // including the Direct KMS Provider

final DynamoDBEncryptor keyEncryptor = DynamoDBEncryptor.getInstance(kmsProv);

// Create the MetaStore

final MetaStore metaStore = new MetaStore(ddb, keyTableName, keyEncryptor);

//Create the Most Recent Provider

final CachingMostRecentProvider cmp = new CachingMostRecentProvider(metaStore, materialName, ttlInMillis, cacheSize);

Python

# Designate an AWS KMS key kms_key_id = 'arn:aws:kms:us-

west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'

# Set the name for MetaStore's internal table meta_table_name = 'metaStoreTable'

# Name that identifies the MetaStore's CMPs in the provider store material_name = 'testMRP'

# Create an internal DynamoDB table resource for the MetaStore meta_table = boto3.resource('dynamodb').Table(meta_table_name)

# Create an internal Direct KMS Provider for the MetaStore kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=kms_key_id) # Create the MetaStore with the Direct KMS Provider

meta_store = MetaStore(

table=meta_table,

materials_provider=kms_cmp )

# Create a Most Recent Provider using the MetaStore

# Sets the TTL (in seconds) and cache size (# entries) most_recent_cmp = MostRecentProvider(

provider_store=meta_store, material_name=material_name, version_ttl=60.0,

cache_size=1000 )

How it works

The Most Recent Provider gets CMPs from a provider store. Then, it uses the CMP to generate the cryptographic materials that it returns to the item encryptor.

About the Most Recent Provider

The Most Recent Provider gets a cryptographic materials provider (p. 8) (CMP) from a provider

store (p. 10). Then, it uses the CMP to generate the cryptographic materials it returns. Each Most Recent Provider is associated with one provider store, but a provider store can supply CMPs to multiple providers across multiple hosts.

(27)

How it works

The Most Recent Provider can work with any compatible CMP from any provider store. It requests encryption or decryption materials from the CMP and returns the output to the item encryptor. It does not perform any cryptographic operations.

To request a CMP from its provider store, the Most Recent Provider supplies its material name and the version of an existing CMP it wants to use. For encryption materials, the Most Recent Provider always requests the maximum ("most recent") version. For decryption materials, it requests the version of the CMP that was used to create the encryption materials, as shown in the following diagram.

The Most Recent Provider saves versions of the CMPs that the provider store returns in a local Least Recently Used (LRU) cache in memory. The cache enables the Most Recent Provider to get the CMPs that it needs without calling the provider store for every item. You can clear the cache on demand.

The Most Recent Provider uses a conﬁgurable time-to-live value (p. 25) that you can adjust based on the characteristics of your application.

About the MetaStore

You can use a Most Recent Provider with any provider store, including a compatible custom provider store. The DynamoDB Encryption Client includes a MetaStore, a secure implementation that you can conﬁgure and customize.

A MetaStore is a provider store (p. 10) that creates and returns Wrapped CMPs (p. 18) that are conﬁgured with the wrapping key, unwrapping key, and signing key that Wrapped CMPs require. A MetaStore is a secure option for a Most Recent Provider because Wrapped CMPs always generate unique item encryption keys for every item. Only the wrapping key that protects the item encryption key and the signing keys are reused.

The following diagram shows the components of the MetaStore and how it interacts with the Most Recent Provider.

(28)

How it works

The MetaStore generates the Wrapped CMPs, and then stores them (in encrypted form) in an internal DynamoDB table. The partition key is the name of the Most Recent Provider material; the sort key its version number. The materials in the table are protected by an internal DynamoDB Encryption Client, including an item encryptor and internal cryptographic materials provider (p. 8) (CMP).

You can use any type of internal CMP in your MetaStore, including the a Direct KMS Provider (p. 18), a Wrapped CMP with cryptographic materials that you provide, or a compatible custom CMP. If the internal CMP in your MetaStore is a Direct KMS Provider, your reusable wrapping and signing keys are protected under a AWS KMS key in AWS Key Management Service (AWS KMS). The MetaStore calls AWS KMS every time it adds a new CMP version to its internal table or gets a CMP version from its internal table.

Setting a time-to-live value

You can set a time-to-live (TTL) value for each Most Recent Provider that you create. In general, use the lowest TTL value that is practical for your application.

The use of the TTL value is changed in the CachingMostRecentProvider symbol for the Most Recent Provider.

Note

The MostRecentProvider symbol for the Most Recent Provider is deprecated in older supported versions of the DynamoDB Encryption Client and removed from version 2.0.0. It is replaced by the CachingMostRecentProvider symbol. We recommend that you update your code as soon as possible. For details, see Updates to the Most Recent Provider (p. 28).

CachingMostRecentProvider

The CachingMostRecentProvider uses the TTL value in two diﬀerent ways.

• The TTL determines how often the Most Recent Provider checks the provider store for a new version of the CMP. If a new version is available, the Most Recent Provider replaces its CMP and refreshes its cryptographic materials. Otherwise, it continues to use its current CMP and cryptographic materials.

• The TTL determines how long CMPs in the cache can be used. Before it uses a cached CMP for encryption, the Most Recent Provider evaluates its time in the cache. If the CMP cache time

(29)

How it works

exceeds the TTL, the CMP is evicted from the cache and the Most Recent Provider gets a new, latest-version CMP from its provider store.

MostRecentProvider

In the MostRecentProvider, the TTL determines how often the Most Recent Provider checks the provider store for a new version of the CMP. If a new version is available, the Most Recent Provider replaces its CMP and refreshes its cryptographic materials. Otherwise, it continues to use its current CMP and cryptographic materials.

The TTL does not determine how often a new CMP version is created. You create new CMP versions by rotating the cryptographic materials (p. 26).

An ideal TTL value varies with the application and its latency and availability goals. A lower TTL improves your security proﬁle by reducing the time that cryptographic materials are stored in memory. Also, a lower TTL refreshes critical information more frequently. For example, if your internal CMP is a Direct KMS Provider (p. 13), it veriﬁes more frequently that the caller is still authorized to use an AWS KMS key.

However, if the TTL is too brief, the frequent calls to the provider store can increase your costs and cause your provider store to throttle requests from your application and other applications that share your service account. You might also beneﬁt from coordinating the TTL with the rate at which you rotate cryptographic materials.

During testing, vary the TTL and cache size under different work loads until you find a configuration that works for your application and your security and performance standards.

Rotating cryptographic materials

When a Most Recent Provider needs encryption materials, it always uses the most recent version of its CMP that it knows about. The frequency that it checks for a newer version is determined by the time-to- live (p. 25) (TTL) value that you set when you conﬁgure the Most Recent Provider.

When the TTL expires, the Most Recent Provider checks the provider store for newer version of the CMP.

If one is available, the Most Recent Provider get it and replaces the CMP in its cache. It uses this CMP and its cryptographic materials until it discovers that provider store has a newer version.

To tell the provider store to create a new version of a CMP for a Most Recent Provider, call the provider store's Create New Provider operation with the material name of the Most Recent Provider. The provider store creates a new CMP and saves an encrypted copy in its internal storage with a greater version number. (It also returns a CMP, but you can discard it.) As a result, the next time the Most Recent Provider queries the provider store for the maximum version number of its CMPs, it gets the new greater version number, and uses it in subsequent requests to the store to see if a new version of the CMP has been created.

You can schedule your Create New Provider calls based on time, the number of items or attributes processed, or any other metric that makes sense for your application.

Get encryption materials

The Most Recent Provider uses the following process, shown in this diagram, to get the encryption materials that it returns to the item encryptor. The output depends on the type of CMP that the provider store returns. The Most Recent Provider can use any compatible provider store, including the MetaStore that is included in the DynamoDB Encryption Client.

(30)

How it works

When you create a Most Recent Provider by using the CachingMostRecentProvider

symbol (p. 28), you specify a provider store, a name for the Most Recent Provider, and a time-to- live (p. 25) (TTL) value. You can also optionally specify a cache size, which determines the maximum number of cryptographic materials that can exist in the cache.

When the item encryptor asks the Most Recent Provider for encryption materials, the Most Recent Provider begins by searching its cache for the latest version of its CMP.

• If it ﬁnds the latest version CMP in its cache and the CMP has not exceeded the TTL value, the Most Recent Provider uses the CMP to generate encryption materials. Then, it returns the encryption materials to the item encryptor. This operation does not require a call to the provider store.

• If the latest version of the CMP is not in its cache, or if it is in the cache but has exceeded its TTL value, the Most Recent Provider requests a CMP from its provider store. The request includes the Most Recent Provider material name and the maximum version number that it knows.

1. The provider store returns a CMP from its persistent storage. If the provider store is a MetaStore, it gets an encrypted Wrapped CMP from its internal DynamoDB table by using the Most Recent Provider material name as the partition key and the version number as the sort key. The MetaStore uses its internal item encryptor and internal CMP to decrypt the Wrapped CMP. Then, it returns the plaintext CMP to the Most Recent Provider . If the internal CMP is a Direct KMS Provider (p. 13), this step includes a call to the AWS Key Management Service (AWS KMS).

2. The CMP adds the amzn-ddb-meta-id ﬁeld to the actual material description (p. 9). Its value is the material name and version of the CMP in its internal table. The provider store returns the CMP to the Most Recent Provider.

3. The Most Recent Provider caches the CMP in memory.

4. The Most Recent Provider uses the CMP to generate encryption materials. Then, it returns the encryption materials to the item encryptor.

Amazon DynamoDB Encryption Client Developer Guide

Amazon DynamoDB Encryption Client

Developer Guide

Amazon DynamoDB Encryption Client: Developer Guide

Table of Contents

What is the Amazon DynamoDB Encryption Client?

Developed in open-source repositories

Support and maintenance

Sending feedback

Which ﬁelds are encrypted and signed?

Encrypting attribute values

Signing the item

An encrypted and signed item

How the DynamoDB Encryption Client works

Client-side and server-side encryption

Amazon DynamoDB Encryption Client concepts

Cryptographic materials provider (CMP)

Item encryptors

Attribute actions

Material description

DynamoDB encryption context

Provider store

How to choose a cryptographic materials provider

Direct KMS Materials Provider

How to use it

How it works

Get encryption materials

Get decryption materials

Wrapped Materials Provider

How to use it

How it works

Get encryption materials

Get decryption materials

Most Recent Provider

How to use it

How it works

About the Most Recent Provider

About the MetaStore

Setting a time-to-live value

Rotating cryptographic materials

Get encryption materials