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. |
An algorithm suite is a collection of cryptographic algorithms and related values. Cryptographic systems use the algorithm implementation to generate the ciphertext message.
The AWS Database Encryption SDK uses an algorithm suite to encrypt and sign the fields in your database. The AWS Database Encryption SDK supports two algorithm suites. All of the supported suites use Advanced Encryption Standard (AES) as the primary algorithm, and combine it with other algorithms and values.
Default algorithm suite
The AWS Database Encryption SDK algorithm suite uses the Advanced Encryption Standard (AES) algorithm in 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.
By default, the AWS Database Encryption SDK uses an algorithm suite with AES-GCM with an HMAC-based
extract-and-expand key derivation function (HKDF
The AWS Database Encryption SDK uses an algorithm suite that derives an AES-GCM data key by supplying a 256-bit data encryption key to the HMAC-based extract-and-expand key derivation function (HKDF). It also derives a MAC key for the data key. The AWS Database Encryption SDK uses this data key to derive a unique data encryption key to encrypt each field. Then, the AWS Database Encryption SDK uses the MAC key to calculate a Hash-Based Message Authentication Code (HMAC) for each encrypted copy of the data key and adds an Elliptic Curve Digital Signature Algorithm (ECDSA) signature to the record. This algorithm suite also derives a key commitment – an HMAC that ties the data key to the record. The key commitment value is an HMAC calculated from the material description and commitment key, which is derived through HKDF using a procedure similar to deriving the data encryption key. The key commitment value is then stored in the material description.
Encryption algorithm | Data encryption key length (in bits) | Symmetric signature algorithm | Asymmetric signature algorithm | Key commitment |
---|---|---|---|---|
AES-GCM | 256 | HMAC-SHA-384 | ECDSA over P384 | HKDF with SHA-512 |
This algorithm suite serializes the material
description and all fields marked ENCRYPT_AND_SIGN
,
SIGN_ONLY
, and SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT
in the cryptographic
actions, and then uses HMAC with a cryptographic hash function algorithm
(SHA-512) to sign the canonicalization. Then it calculates an ECDSA digital signature.
The HMACs and ECDSA signatures are stored in a new field (aws_dbe_foot
) that the AWS Database Encryption SDK adds to the record. 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.
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, these algorithm suites derive 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 digital signatures
Although the default algorithm suite is likely to be suitable for most applications, you can choose an alternate algorithm suite. For example, some trust models would be satisfied by an algorithm suite without digital signatures. Use this suite only when the users who encrypt data and those who decrypt data are equally trusted.
All AWS Database Encryption SDK algorithm suites support HMAC-SHA-384 symmetric signing. The only difference, is that the AES-GCM algorithm suite without digital signatures lacks the ECDSA 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-SHA-384 symmetric
signature verifies that the record was encrypted by a user with access to
wrappingKeyA
. If you used the default algorithms, the HMACs provide the
same verification of wrappingKeyA
, and additionally use the ECDSA 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, specify it in your encryption configuration.