Amazon DynamoDB Encryption Client concepts
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.
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.
Topics
Cryptographic materials provider (CMP)
When implementing the DynamoDB Encryption Client, one of your first tasks is to select a cryptographic materials provider (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 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 configure 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.
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 (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 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.
Warning
Do not encrypt the primary key attributes. They must remain in plaintext so DynamoDB can find the item without running a full table scan.
If the DynamoDB encryption context identifies 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 different for each programming language. It might also be specific to helper classes that you use.
For details, see the documentation for your programming language.
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 (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.
In the DynamoDB Encryption Client, the material description refers to three related elements:
- Requested material description
-
Some cryptographic materials providers (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 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 defined by the CMP that you choose.
Note
Because 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 (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-descand 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 (CMP). In advanced implementations, the DynamoDB encryption context can include a requested material description.
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 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.
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.
The DynamoDB encryption context can include the following fields. All fields and values are optional.
-
Table name
-
Partition key name
-
Sort key name
-
Attribute name-value pairs
Provider store
A provider store is a component that returns cryptographic materials providers (CMPs). The provider store can create the CMPs or get them from another source, such as another provider store. The provider store saves versions of the CMPs that it creates in persistent storage in which each stored CMP is identified by the material name of the requester and version number.
The Most Recent Provider 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, 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:
