# What is the AWS Database Encryption SDK?
****
| |
| --- |
| Our client-side encryption library was renamed to the AWS Database Encryption SDK. This developer guide still provides information on the [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). |
The AWS Database Encryption SDK is a set of software libraries that enable you to include client-side encryption in your database design. The AWS Database Encryption SDK provides record-level encryption solutions. You specify which fields are encrypted and which fields are included in the signatures that ensure the authenticity of your data. 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 AWS Database Encryption SDK is provided free of charge under the Apache 2.0 license.
This developer guide provides a conceptual overview of the AWS Database Encryption SDK, including an [introduction to its architecture](concepts.md), details about [how it protects your data](how-it-works.md), how it differs from [server-side encryption](client-server-side.md), and guidance on [selecting critical components for your application](configure.md) to help you get started.
The AWS Database Encryption SDK supports Amazon DynamoDB with *attribute*-level encryption.
The AWS Database Encryption SDK has the following benefits:
**Designed especially for database applications**
You don’t need to be a cryptography expert to use the AWS Database Encryption SDK. The implementations include helper methods that are designed to work with your existing applications.
After you create and configure the required components, the encryption client transparently encrypts and signs your records when you add them to a database, and verifies and decrypts them when you retrieve them.
**Includes secure encryption and signing**
The AWS Database Encryption SDK includes secure implementations that encrypt the field values in each record using a unique data encryption key, and then sign the record to protect it against unauthorized changes, such as adding or deleting fields, or swapping encrypted values.
**Uses cryptographic materials from any source**
The AWS Database Encryption SDK uses [keyrings](concepts.md#keyring-concept) to generate, encrypt, and decrypt the unique data encryption key that protects your record. Keyrings determine the [wrapping keys](concepts.md#wrapping-key) that encrypt that data key.
You can use wrapping keys from any source, including cryptography services, such as [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) (AWS KMS) or [AWS CloudHSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/). The AWS Database Encryption SDK doesn't require an AWS account or any AWS service.
**Support for cryptographic materials caching**
The [AWS KMS Hierarchical keyring](use-hierarchical-keyring.md) is a cryptographic materials caching solution that reduces the number of AWS KMS calls by using AWS KMS protected *branch keys* persisted in an Amazon DynamoDB table, and then locally caching branch key materials used in encrypt and decrypt operations. It allows you to protect your cryptographic materials under a symmetric encryption KMS key without calling AWS KMS every time you encrypt or decrypt a record. The AWS KMS Hierarchical keyring is a good choice for applications that need to minimize calls to AWS KMS.
**Searchable encryption**
You can design databases that can search encrypted records without decrypting the entire database. Depending on your threat model and query requirements, you can use [searchable encryption](searchable-encryption.md) to perform exact match searches or more customized complex queries on your encrypted database.
**Support for multitenant database schemas**
The AWS Database Encryption SDK enables you to protect data stored in databases with a shared schema by isolating each tenant with distinct encryption materials. If you have multiple users performing encrypt operations within your database, use one of the AWS KMS keyrings to provide each user with a distinct key to use in their cryptographic operations. For more information, see [Working with multitenant databases](configure.md#config-multitenant-databases).
**Support for seamless schema updates**
When you configure the AWS Database Encryption SDK, you provide [cryptographic actions](concepts.md#crypt-actions) that tell the client which fields to encrypt and sign, which fields to sign (but not encrypt), and which to ignore. After you have used the AWS Database Encryption SDK to protect your records, you can still [make changes to your data model](ddb-update-data-model.md). You can update your cryptographic actions, such as adding or removing encrypted fields, in a single deployment.
## Developed in open-source repositories
The AWS Database Encryption SDK is developed in open-source repositories on GitHub. You can use these repositories to view the code, read and submit issues, and find information that is specific to your implementation.
**The AWS Database Encryption SDK for DynamoDB**
+ The [aws-database-encryption-sdk-dynamodb](https://github.com/aws/aws-database-encryption-sdk-dynamodb/) repository on GitHub supports the latest versions of the AWS Database Encryption SDK for DynamoDB in Java, .NET, and Rust.
The AWS Database Encryption SDK for DynamoDB is a product of [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md), a verification-aware language in which you write specifications, the code to implement them, and the proofs to test them. The result is a library that implements the features of the AWS Database Encryption SDK for DynamoDB in a framework that assures functional correctness.
## Support and maintenance
The AWS Database Encryption SDK uses the same [maintenance policy](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html) that the AWS SDK and Tools use, including its versioning and lifecycle phases. As a best practice, we recommend that you use the latest available version of the AWS Database Encryption SDK for your database implementation, and upgrade as new versions are released.
For more information, see the [AWS SDKs and Tools maintenance policy](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html) in the AWS SDKs and Tools Reference Guide.
## Sending feedback
We welcome your feedback\$1 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 AWS Database Encryption SDK, please [notify AWS security](https://aws.amazon.com/security/vulnerability-reporting/). Do not create a public GitHub issue.
To provide feedback on this documentation, use the feedback link on any page.
# AWS Database Encryption SDK concepts
****
| |
| --- |
| Our client-side encryption library was renamed to the AWS Database Encryption SDK. This developer guide still provides information on the [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). |
This topic explains the concepts and terminology used in the AWS Database Encryption SDK.
To learn how the components of the AWS Database Encryption SDK interact, see [How the AWS Database Encryption SDK works](how-it-works.md).
To learn more about the AWS Database Encryption SDK, see the following topics.
+ Learn how the AWS Database Encryption SDK uses [envelope encryption](#envelope-encryption) to protect your data.
+ Learn about the elements of envelope encryption: the [data keys](#data-key) that protect your records and the [wrapping keys](#wrapping-key) that protect your data keys.
+ Learn about the [keyrings](#keyring-concept) that determine which wrapping keys you use.
+ Learn about the [encryption context](#encryption-context) that adds integrity to your encryption process.
+ Learn about the [material description](#material-description) that the encryption methods add to your record.
+ Learn about the [cryptographic actions](#crypt-actions) that tell the AWS Database Encryption SDK what fields to encrypt and sign.
**Topics**
+ [
## Envelope encryption
](#envelope-encryption)
+ [
## Data key
](#data-key)
+ [
## Wrapping key
](#wrapping-key)
+ [
## Keyrings
](#keyring-concept)
+ [
## Cryptographic actions
](#crypt-actions)
+ [
## Material description
](#material-description)
+ [
## Encryption context
](#encryption-context)
+ [
## Cryptographic materials manager
](#crypt-materials-manager)
+ [
## Symmetric and asymmetric encryption
](#symmetric-key-encryption)
+ [
## Key commitment
](#key-commitment)
+ [
## Digital signatures
](#digital-sigs)
## Envelope encryption
The security of your encrypted data depends in part on protecting the data key that can decrypt it. One accepted best practice for protecting the data key is to encrypt it. To do this, you need another encryption key, known as a *key-encryption key* or [wrapping key](#wrapping-key). The practice of using a wrapping key to encrypt data keys is known as *envelope encryption*.
**Protecting data keys**
The AWS Database Encryption SDK encrypts each field with a unique data key. Then it encrypts each data key under the wrapping key you specify. It stores the encrypted data keys in the [material description](#material-description).
To specify your wrapping key, you use a [keyring](#keyring-concept).
![\[Envelope encryption with the AWS Database Encryption SDK\]](http://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/images/dbesdk-envelope.png)
**Encrypting the same data under multiple wrapping keys**
You can encrypt the data key with multiple wrapping keys. You might want to provide different wrapping keys for different users, or wrapping keys of different types, or in different locations. Each of the wrapping keys encrypts the same data key. The AWS Database Encryption SDK stores all of the encrypted data keys alongside the encrypted fields in the [material description](#material-description).
To decrypt the data, you need to provide at least one wrapping key that can decrypt the encrypted data keys.
**Combining the strengths of multiple algorithms**
To encrypt your data, by default, the AWS Database Encryption SDK uses an [algorithm suite](supported-algorithms.md) with AES-GCM symmetric encryption, an HMAC-based key derivation function (HKDF), and [ECDSA signing](#digital-sigs). To encrypt the data key, you can specify a [symmetric or asymmetric encryption algorithm](#symmetric-key-encryption) appropriate to your wrapping key.
In general, symmetric key encryption algorithms are faster and produce smaller ciphertexts than asymmetric or *public key encryption*. But public key algorithms provide inherent separation of roles. To combine the strengths of each, you can encrypt the data key with public key encryption.
We recommend using one of the AWS KMS keyrings whenever possible. When you use the [AWS KMS keyring](use-kms-keyring.md), you can choose to combine the strengths of multiple algorithms by specifying an asymmetric RSA AWS KMS key as your wrapping key. You can also use a symmetric encryption KMS key.
## Data key
A *data key* is an encryption key that the AWS Database Encryption SDK uses to encrypt the fields in a record that are marked `ENCRYPT_AND_SIGN` in the [cryptographic actions](#crypt-actions). Each data key is a byte array that conforms to the requirements for cryptographic keys. The AWS Database Encryption SDK uses a unique data key to encrypt each attribute.
You don't need to specify, generate, implement, extend, protect, or use data keys. The AWS Database Encryption SDK does that work for you when you call the encrypt and decrypt operations.
To protect your data keys, the AWS Database Encryption SDK encrypts them under one or more *key-encryption keys* known as [wrapping keys](#wrapping-key). After the AWS Database Encryption SDK uses your plaintext data keys to encrypt your data, it removes them from memory as soon as possible. Then stores the encrypted data key in the [material description](#material-description). For details, see [How the AWS Database Encryption SDK works](how-it-works.md).
**Tip**
In the AWS Database Encryption SDK, we distinguish *data keys* from *data encryption keys*. As a best practice, all of the supported [algorithm suites](supported-algorithms.md) use a [key derivation function](https://en.wikipedia.org/wiki/Key_derivation_function). The key derivation function takes a data key as input and returns the data encryption keys that are actually used to encrypt your records. For this reason, we often say that data is encrypted "under" a data key rather than "by" the data key.
Each encrypted data key includes metadata, including the identifier of the wrapping key that encrypted it. This metadata makes it possible for the AWS Database Encryption SDK to identify valid wrapping keys when decrypting.
## Wrapping key
A *wrapping key* is a key-encryption key that the AWS Database Encryption SDK uses to encrypt the [data key](#data-key) that encrypts your records. Each data key can be encrypted under one or more wrapping keys. You determine which wrapping keys are used to protect your data when you configure a [keyring](#keyring-concept).
![\[Encrypt one data key with multiple wrapping keys\]](http://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/images/dbesdk-wrapping-key.png)
The AWS Database Encryption SDK supports several commonly used wrapping keys, such as [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) (AWS KMS) symmetric encryption KMS keys (including [multi-Region AWS KMS keys](use-kms-keyring.md#config-mrks)) and asymmetric [RSA KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/asymmetric-key-specs.html#key-spec-rsa), raw AES-GCM (Advanced Encryption Standard/Galois Counter Mode) keys, and raw RSA keys. We recommend using KMS keys whenever possible. To decide which wrapping key you should use, see [Selecting wrapping keys](configure.md#config-keys).
When you use envelope encryption, you need to protect your wrapping keys from unauthorized access. You can do this in any of the following ways:
+ Use a service designed for this purpose, such as [AWS Key Management Service (AWS KMS)](https://aws.amazon.com/kms/).
+ Use a [hardware security module (HSM)](https://en.wikipedia.org/wiki/Hardware_security_module) such as those offered by [AWS CloudHSM](https://aws.amazon.com/cloudhsm/).
+ Use other key management tools and services.
If you don't have a key management system, we recommend AWS KMS. The AWS Database Encryption SDK integrates with AWS KMS to help you protect and use your wrapping keys.
## Keyrings
To specify the wrapping keys you use for encryption and decryption, you use a keyring. You can use the keyrings that the AWS Database Encryption SDK provides or design your own implementations.
A *keyring* generates, encrypts, and decrypts data keys. It also generates the MAC keys used to calculate the Hash-Based Message Authentication Codes (HMACs) in the signature. When you define a keyring, you can specify the [wrapping keys](#wrapping-key) that encrypt your data keys. Most keyrings specify at least one wrapping key or a service that provides and protects wrapping keys. When encrypting, the AWS Database Encryption SDK uses all of the wrapping keys specified in the keyring to encrypt the data key. For help with choosing and using the keyrings that the AWS Database Encryption SDK defines, see [Using keyrings](keyrings.md).
## Cryptographic actions
*Cryptographic actions* tell the encryptor which actions to perform on each field in a record.
The cryptographic action values can be one of the following:
+ **Encrypt and sign** – Encrypt the field. Include the encrypted field in the signature.
+ **Sign only** – Include the field in the signature.
+ **Sign and include in encryption context** – Include the field in the signature and [encryption context](#encryption-context).
By default, the partition and sort keys are the only attribute included in the encryption context. You might consider defining additional fields as `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` so that the branch key ID supplier for your [AWS KMS Hierarchical keyring](use-hierarchical-keyring.md) can identify which branch key is required for decryption from the encryption context. For more information, see [branch key ID supplier](use-hierarchical-keyring.md#branch-key-id-supplier).
**Note**
To use the `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` cryptographic action, you must use version 3.3 or later of the AWS Database Encryption SDK. Deploy the new version to all readers before [updating your data model](ddb-update-data-model.md) to include `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
+ **Do nothing** – Do not encrypt or include the field in the signature.
For any field that can store sensitive data, use **Encrypt and sign**. For primary key values (for example, a partition key and sort key in a DynamoDB table), use **Sign only** or **Sign and include in encryption context**. If you specify any **Sign and include in encryption context** attributes, then the partition and sort attributes must also be **Sign and include in encryption context**. You do not need to specify cryptographic actions for the [material description](#material-description). The AWS Database Encryption SDK automatically signs the field that the material description is stored in.
Choose your cryptographic actions carefully. When in doubt, use **Encrypt and sign**. After you have used the AWS Database Encryption SDK to protect your records, you cannot change an existing `ENCRYPT_AND_SIGN`, `SIGN_ONLY`, or `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` field to `DO_NOTHING`, or change the cryptographic action assigned to an existing `DO_NOTHING` field. However, you can still [make other changes to your data model](ddb-update-data-model.md). For example, you can add or remove encrypted fields, in a single deployment.
## Material description
The material description serves as the header for an encrypted record. When you encrypt and sign fields with the AWS Database Encryption SDK, the encryptor records the material description as it assembles the cryptographic materials and stores the material description in a new field (`aws_dbe_head`) that the encryptor adds to your record.
The material description is a portable [formatted data structure](reference.md#material-description-format) that contains encrypted copies of the data keys and other information, such as encryption algorithms, [encryption context](#encryption-context), and encryption and signing instructions. The encryptor 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 a field, it uses the material description as its guide.
Storing the encrypted data keys alongside the encrypted field streamlines the decryption operation and frees you from having to store and manage encrypted data keys independently of the data that they encrypt.
For technical information about the material description, see [Material description format](reference.md#material-description-format).
## Encryption context
To improve the security of your cryptographic operations, the AWS Database Encryption SDK includes an encryption context in all requests to encrypt and sign a record.
An *encryption context* is a set of name-value pairs that contain arbitrary, non-secret additional authenticated data. The AWS Database Encryption SDK includes the logical name for your database and primary key values (for example, a partition key and sort key in a DynamoDB table) in the encryption context. When you encrypt and sign a field, the encryption context is cryptographically bound to the encrypted record so that the same encryption context is required to decrypt the field.
If you use an AWS KMS keyring, the AWS Database Encryption SDK also uses the encryption context to provide additional authenticated data (AAD) in the calls the keyring makes to AWS KMS.
Whenever you use the [default algorithm suite](supported-algorithms.md#recommended-algorithms), the [cryptographic materials manager](#crypt-materials-manager) (CMM) adds a name-value pair to the encryption context that consists of a reserved name, `aws-crypto-public-key`, and a value that represents the public verification key. The public verification key is stored in the [material description](#material-description).
## Cryptographic materials manager
The cryptographic materials manager (CMM) assembles the cryptographic materials that are used to encrypt, decrypt, and sign your data. Whenever you use the [default algorithm suite](supported-algorithms.md#recommended-algorithms), the *cryptographic materials* include plaintext and encrypted data keys, symmetric signing keys, and an asymmetric signing key. You never interact with the CMM directly. The encryption and decryption methods handle it for you.
Because the CMM acts as a liaison between the AWS Database Encryption SDK and a keyring, it is an ideal point for customization and extension, such as support for policy enforcement. You can explicitly specify a CMM, but it's not required. When you specify a keyring, the AWS Database Encryption SDK creates a default CMM for you. The default CMM gets the encryption or decryption materials from the keyring that you specify. This might involve a call to a cryptographic service, such as [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) (AWS KMS).
## Symmetric and asymmetric encryption
*Symmetric encryption* uses the same key to encrypt and decrypt data.
*Asymmetric encryption* uses a mathematically related data key pair. One key in the pair encrypts the data; only the other key in the pair can decrypt the data.
The AWS Database Encryption SDK uses [envelope encryption](#envelope-encryption). It encrypts your data with a symmetric data key. It encrypts the symmetric data key with one or more symmetric or asymmetric wrapping keys. It adds a [material description](#material-description) to the record that includes at least one encrypted copy of the data key.
**Encrypting your data (symmetric encryption)**
To encrypt your data, the AWS Database Encryption SDK uses a symmetric [data key](#data-key) and an [algorithm suite](supported-algorithms.md) that includes a symmetric encryption algorithm. To decrypt the data, the AWS Database Encryption SDK uses the same data key and the same algorithm suite.
**Encrypting your data key (symmetric or asymmetric encryption)**
The [keyring](#keyring-concept) that you supply to an encrypt and decrypt operation determines how the symmetric data key is encrypted and decrypted. You can choose a keyring that uses symmetric encryption, such as an AWS KMS keyring with a symmetric encryption KMS key, or one that uses asymmetric encryption, such as an AWS KMS keyring with an asymmetric RSA KMS key.
## Key commitment
The AWS Database Encryption SDK supports *key commitment* (sometimes known as *robustness*), a security property that ensures that each ciphertext can be decrypted only to a single plaintext. To do this, key commitment ensures that only the data key that encrypted your record will be used to decrypt it. The AWS Database Encryption SDK includes key commitment for all encryption and decryption operations.
Most modern symmetric ciphers (including AES) encrypt plaintext under a single secret key, like the [unique data key](#data-key) that the AWS Database Encryption SDK uses to encrypt each plaintext field marked `ENCRYPT_AND_SIGN` in a record. Decrypting this record with the same data key returns a plaintext that is identical to the original. Decrypting with a different key will usually fail. Although difficult, it's technically possible to decrypt a ciphertext under two different keys. In rare cases, it is feasible to find a key that can partially decrypt ciphertext into a different, but still intelligible, plaintext.
The AWS Database Encryption SDK always encrypts each attribute under one unique data key. It might encrypt that data key under multiple wrapping keys, but the wrapping keys always encrypt the same data key. Nonetheless, a sophisticated, manually crafted encrypted record might actually contain different data keys, each encrypted by a different wrapping key. For example, if one user decrypts the encrypted record it returns 0x0 (false) while another user decrypting the same encrypted record gets 0x1 (true).
To prevent this scenario, the AWS Database Encryption SDK includes key commitment when encrypting and decrypting. The encrypt method cryptographically binds the unique data key that produced the ciphertext to the *key commitment*, a Hash-Based Message Authentication Code (HMAC) calculated over the material description using a derivation of the data key. Then it stores the key commitment in the [material description](#material-description). When it decrypts a record with key commitment, the AWS Database Encryption SDK verifies that the data key is the only key for that encrypted record. If data key verification fails, the decrypt operation fails.
## Digital signatures
The AWS Database Encryption SDK encrypts your data using an authenticated encryption algorithm, AES-GCM, and the decryption process verifies the integrity and authenticity of an encrypted message without using a digital signature. But because AES-GCM uses symmetric keys, anyone who can decrypt the data key used to decrypt the ciphertext could also manually create a new encrypted ciphertext, causing a potential security concern. For instance, if you use an AWS KMS key as a wrapping key, a user with `kms:Decrypt` permissions could create encrypted ciphertexts without calling `kms:Encrypt`.
To avoid this issue, the [default algorithm suite](supported-algorithms.md#recommended-algorithms) adds an Elliptic Curve Digital Signature Algorithm (ECDSA) signature to encrypted records. The default algorithm suite encrypts the fields in your record marked `ENCRYPT_AND_SIGN` using an authenticated encryption algorithm, AES-GCM. Then, it calculates both Hash-Based Message Authentication Codes (HMACs) and asymmetric ECDSA signatures over the fields in your record marked `ENCRYPT_AND_SIGN`, `SIGN_ONLY`, and `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. The decryption process uses the signatures to verify that an authorized user encrypted the record.
When the default algorithm suite is used, the AWS Database Encryption SDK generates a temporary private key and public key pair for each encrypted record. The AWS Database Encryption SDK stores the public key in the [material description](#material-description) and discards the private key. This ensures that no one can create another signature that verifies with the public key. The algorithm binds the public key to the encrypted data key as additional authenticated data in the material description, preventing users who can only decrypt fields from altering the public key or affecting signature verification.
The AWS Database Encryption SDK always includes HMAC verification. ECDSA digital signatures are enabled by default, but not required. If the users encrypting data and the users decrypting data are equally trusted, you might consider using an algorithm suite that does not include digital signatures to improve your performance. For more information on selecting alternative algorithm suites, see [Choosing an algorithm suite](ddb-java-using.md#config-algorithm).
**Note**
If a keyring doesn't delineate between encryptors and decryptors, digital signatures provide no cryptographic value.
[AWS KMS keyrings](use-kms-keyring.md), including the asymmetric RSA AWS KMS keyring, can delineate between encryptors and decryptors based on AWS KMS key policies and IAM policies.
Due to their cryptographic nature, the following keyrings cannot delineate between encryptors and decryptors:
+ AWS KMS Hierarchical keyring
+ AWS KMS ECDH keyring
+ Raw AES keyring
+ Raw RSA keyring
+ Raw ECDH keyring
# How the AWS Database Encryption SDK works
****
| |
| --- |
| Our client-side encryption library was renamed to the AWS Database Encryption SDK. This developer guide still provides information on the [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). |
The AWS Database Encryption SDK provides client-side encryption libraries that are designed specifically to protect the data that you store in databases. The libraries include secure implementations that you can extend or use unchanged. For more information about defining and using custom components, see the GitHub repository for your database implementation.
The workflows in this section explain how the AWS Database Encryption SDK encrypts and signs and decrypts and verifies the data in your database. These workflows describe the basic process using abstract elements and the default features. For details about how the AWS Database Encryption SDK works with your database implementation, see the *What is encrypted* topic for your database.
The AWS Database Encryption SDK uses [envelope encryption](concepts.md#envelope-encryption) to protect your data. Each record is encrypted under a unique [data key](concepts.md#data-key). The data key is used to derive a unique *data encryption key* for each field marked `ENCRYPT_AND_SIGN` in your cryptographic actions. Then, a copy of data key is encrypted by the wrapping keys you specify. To decrypt the encrypted record, the AWS Database Encryption SDK uses the wrapping keys you specify to decrypt at least one encrypted data key. Then it can decrypt the ciphertext and return a plaintext entry.
For more information about the terms used in the AWS Database Encryption SDK, see [AWS Database Encryption SDK concepts](concepts.md).
## Encrypt and sign
At its core, the AWS Database Encryption SDK is a record encryptor that encrypts, signs, verifies, and decrypts the records in your database. It takes in information about your records and instructions about which fields to encrypt and sign. It gets the encryption materials, and instructions on how to use them, from a [cryptographic materials manager](concepts.md#crypt-materials-manager) configured from the wrapping key you specify.
The following walkthrough describes how the AWS Database Encryption SDK encrypts and signs your data entries.
1. The cryptographic materials manager provides the AWS Database Encryption SDK with unique data encryption keys: one plaintext [data key](concepts.md#data-key), a copy of the data key encrypted by the specified [wrapping key](concepts.md#wrapping-key), and a MAC key.
**Note**
You can encrypt the data key under multiple wrapping keys. Each of the wrapping keys encrypt a separate copy of the data key. The AWS Database Encryption SDK stores all of the encrypted data keys in the [material description](concepts.md#material-description). The AWS Database Encryption SDK adds a new field (`aws_dbe_head`) to the record that stores the material description.
A MAC key is derived for each encrypted copy of the data key. The MAC keys are not stored in the material description. Instead, the decrypt method uses the wrapping keys to derive the MAC keys again.
1. The encryption method encrypts each field marked as `ENCRYPT_AND_SIGN` in the [cryptographic actions](concepts.md#crypt-actions) you specified.
1. The encryption method derives a `commitKey` from the data key and uses it to generate a [key commitment value](concepts.md#key-commitment), and then discards the data key.
1. The encryption method adds a [material description](concepts.md#material-description) to the record. The material description contains the encrypted data keys and the other information about the encrypted record. For a complete list of the information included in the material description, see [Material description format](reference.md#material-description-format).
1. The encryption method uses the MAC keys returned in **Step 1** to calculate Hash-Based Message Authentication Code (HMAC) values over the canonicalization of the material description, [encryption context](concepts.md#encryption-context), and each field marked `ENCRYPT_AND_SIGN`, `SIGN_ONLY`, or `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` in the cryptographic actions. The HMAC values are stored in a new field (`aws_dbe_foot`) that the encryption method adds to the record.
1. The encryption method calculates an [ECDSA signature](concepts.md#digital-sigs) over the canonicalization of the material description, encryption context, and each field marked `ENCRYPT_AND_SIGN`, `SIGN_ONLY`, or `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` and stores the ECDSA signatures in the `aws_dbe_foot` field.
**Note**
ECDSA signatures are enabled by default, but are not required.
1. The encryption method stores the encrypted and signed record in your database
## Decrypt and verify
1. The cryptographic materials manager (CMM) provides the decryption method with the decryption materials stored in the material description, including the plaintext [data key](concepts.md#data-key) and the associated MAC key.
1. The CMM decrypts the encrypted data key with the [wrapping keys](concepts.md#wrapping-key) in the specified keyring and returns the plaintext data key.
1. The decryption method compares and verifies the key commitment value in the material description.
1. The decryption method verifies the signatures in the signature field.
It identifies which fields are marked `ENCRYPT_AND_SIGN`, `SIGN_ONLY`, or `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` from the list of [allowed unauthenticated fields](ddb-java-using.md#allowed-unauth) that you defined. The decryption method uses the MAC key returned in **Step 1** to recalculate and compare HMAC values for the fields marked `ENCRYPT_AND_SIGN`, `SIGN_ONLY`, or `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Then, it verifies the [ECDSA signatures](concepts.md#digital-sigs) using the public key stored in the [encryption context](concepts.md#encryption-context).
1. The decryption method uses the plaintext data key to decrypt each value marked `ENCRYPT_AND_SIGN`. The AWS Database Encryption SDK then discards the plaintext data key.
1. The decryption method returns the plaintext record.
# Supported algorithm suites in the AWS Database Encryption SDK
****
| |
| --- |
| Our client-side encryption library was renamed to the AWS Database Encryption SDK. This developer guide still provides information on the [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). |
An *algorithm suite* is a collection of cryptographic algorithms and related values. Cryptographic systems use the algorithm implementation to generate the ciphertext.
The AWS Database Encryption SDK uses an algorithm suite to encrypt and sign the fields in your database. All supported algorithm suites use the Advanced Encryption Standard (AES) algorithm with Galois/Counter Mode (GCM), known as AES-GCM, to encrypt raw data. The AWS Database Encryption SDK supports 256-bit encryption keys. The length of the authentication tag is always 16 bytes.
**AWS Database Encryption SDK Algorithm Suites**
| Algorithm | Encryption algorithm | Data key length (in bits) | Key derivation algorithm | Symmetric signature algorithm | Asymmetric signature algorithm | Key commitment |
| --- | --- | --- | --- | --- | --- | --- |
| Default | AES-GCM | 256 | HKDF with SHA-512 | HMAC-SHA-384 | ECDSA with P-384 and SHA-384 | HKDF with SHA-512 |
| AES-GCM without ECDSA digital signatures | AES-GCM | 256 | HKDF with SHA-512 | HMAC-SHA-384 | None | HKDF with SHA-512 |
**Encryption algorithm**
The name and mode of the encryption algorithm used. Algorithm suites in the AWS Database Encryption SDK use the Advanced Encryption Standard (AES) algorithm with Galois/Counter Mode (GCM).
**Data key length**
The length of the [data key](concepts.md#data-key) in bits. The AWS Database Encryption SDK supports 256-bit data keys. The data key is used as input to an HMAC-based extract-and-expand key derivation function (HKDF). The output of the HKDF is used as the data encryption key in the encryption algorithm.
**Key derivation algorithm**
The HMAC-based extract-and-expand key derivation function (HKDF) used to derive the data encryption key. The AWS Database Encryption SDK uses the HKDF defined in [RFC 5869](https://tools.ietf.org/html/rfc5869).
+ The hash function used is SHA-512
+ For the extract step:
+ No salt is used. Per the RFC, the salt is set to a string of zeros.
+ The input keying material is the data key from the [keyring](concepts.md#keyring-concept).
+ For the expand step:
+ The input pseudorandom key is the output from the extract step.
+ The key label is the UTF-8-encoded bytes of the `DERIVEKEY` string in big endian byte order.
+ The input info is a concatenation of the algorithm ID and the key label (in that order).
+ The length of the output keying material is the **Data key length**. This output is used as the data encryption key in the encryption algorithm.
**Symmetric signature algorithm**
The Hash-Based Message Authentication Code (HMAC) algorithm used to generate a symmetric signature. All supported algorithm suites include HMAC verification.
The AWS Database Encryption SDK serializes the material description and all fields marked `ENCRYPT_AND_SIGN`, `SIGN_ONLY`, or `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Then, it uses HMAC with a cryptographic hash function algorithm (SHA-384) to sign the canonicalization.
The symmetric HMAC signature is stored in a new field (`aws_dbe_foot`) that the AWS Database Encryption SDK adds to the record.
**Asymmetric signature algorithm**
The signature algorithm used to generate an asymmetric digital signature.
The AWS Database Encryption SDK serializes the material description and all fields marked `ENCRYPT_AND_SIGN`, `SIGN_ONLY`, or `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Then, it uses the Elliptic Curve Digital Signature Algorithm (ECDSA) with the following specifics to sign the canonicalization:
+ The elliptic curve used is the P-384, as defined in [Digital Signature Standard (DSS) (FIPS PUB 186-4)](http://doi.org/10.6028/NIST.FIPS.186-4).
+ The hash function used is SHA-384.
The asymmetric ECDSA signature is stored with the symmetric HMAC signature in the `aws_dbe_foot` field.
ECDSA digital signatures are included by default, but not required.
**Key commitment**
The HMAC-based extract-and-expand key derivation function (HKDF) used to derive the commit key.
+ The hash function used is SHA-512
+ For the extract step:
+ No salt is used. Per the RFC, the salt is set to a string of zeros.
+ The input keying material is the data key from the [keyring](concepts.md#keyring-concept).
+ For the expand step:
+ The input pseudorandom key is the output from the extract step.
+ The input info is the UTF-8-encoded bytes of the `COMMITKEY` string in big endian byte order.
+ The length of the output keying material is 256 bits. This output is used as the commit key.
The commit key calculates the [record commitment](reference.md#format-commitment), a distinct 256-bit Hash-Based Message Authentication Code (HMAC) hash, over the [material description](reference.md#material-description-format). For a technical explanation of adding key commitment to an algorithm suite, see [Key Committing AEADs](https://eprint.iacr.org/2020/1153) in Cryptology ePrint Archive.
## Default algorithm suite
By default, the AWS Database Encryption SDK uses an algorithm suite with AES-GCM, an HMAC-based extract-and-expand key derivation function (HKDF), HMAC verification, ECDSA digital signatures, key commitment, and a 256-bit encryption key.
The default algorithm suite includes HMAC verification (symmetric signatures) and [ECDSA digital signatures](concepts.md#digital-sigs) (asymmetric signatures). These signatures are stored in a new field (`aws_dbe_foot`) that the AWS Database Encryption SDK adds to the record. ECDSA digital signatures are particularly useful when the authorization policy allows one set of users to encrypt data and a different set of users to decrypt data.
The default algorithm suite also derives a [key commitment](concepts.md#key-commitment) – an HMAC hash that ties the data key to the record. The key commitment value is an HMAC calculated from the material description and commit key. The key commitment value is then stored in the material description. Key commitment ensures that each ciphertext decrypts to only one plaintext. They do this by validating the data key used as input to the encryption algorithm. When encrypting, the algorithm suite derives a key commitment HMAC. Before decrypting, they validate that the data key produces the same key commitment HMAC. If it does not, the decrypt call fails.
## AES-GCM without ECDSA digital signatures
Although the default algorithm suite is likely suitable for most applications, you can choose an alternate algorithm suite. For example, some trust models would be satisfied by an algorithm suite without ECDSA digital signatures. Use this suite only when the users who encrypt data and the users who decrypt data are equally trusted.
All AWS Database Encryption SDK algorithm suites include HMAC verification (symmetric signatures). The only difference, is that the AES-GCM algorithm suite without ECDSA digital signature lacks the asymmetric signature that provides an additional layer of authenticity and non-repudiation.
For example, if you have multiple wrapping keys in your keyring, `wrappingKeyA`, `wrappingKeyB`, and `wrappingKeyC`, and you decrypt a record using `wrappingKeyA`, the HMAC symmetric signature verifies that the record was encrypted by a user with access to `wrappingKeyA`. If you used the default algorithm suite, the HMACs provide the same verification of `wrappingKeyA`, and additionally use the ECDSA digital signature to ensure the record was encrypted by a user with encrypt permissions for `wrappingKeyA`.
To select the AES-GCM algorithm suite without digital signatures, include the following snippet in your encryption configuration.
------
#### [ Java ]
The following snippet specifies the AES-GCM algorithm suite without ECDSA digital signatures. For more information, see [Encryption configuration in the AWS Database Encryption SDK for DynamoDB](ddb-java-using.md#ddb-config-encrypt).
```
.algorithmSuiteId(
DBEAlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384)
```
------
#### [ C\$1 / .NET ]
The following snippet specifies the AES-GCM algorithm suite without ECDSA digital signatures. For more information, see [Encryption configuration in the AWS Database Encryption SDK for DynamoDB](ddb-net-using.md#ddb-net-config-encrypt).
```
AlgorithmSuiteId = DBEAlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384
```
------
#### [ Rust ]
The following snippet specifies the AES-GCM algorithm suite without ECDSA digital signatures. For more information, see [Encryption configuration in the AWS Database Encryption SDK for DynamoDB](ddb-rust-using.md#ddb-rust-config-encrypt).
```
.algorithm_suite_id(
DbeAlgorithmSuiteId::AlgAes256GcmHkdfSha512CommitKeyEcdsaP384SymsigHmacSha384,
)
```
------