Reference - AWS Database Encryption SDK
Material description formatAWS KMS Hierarchical keyring technical details

Reference

Our client-side encryption library was renamed to the AWS Database Encryption SDK. This developer guide still provides information on the DynamoDB Encryption Client.

The following topics provide technical details for the AWS Database Encryption SDK.

Material description format

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 that contains the encrypted data key and information about how the record was encrypted and signed. The following table describes the values that form the material description. The bytes are appended in the order shown.

Value Length in bytes
Version 1
Signatures Enabled 1
Record ID 32
Encrypt Legend Variable
Encryption Context Length 2
Encryption Context Variable
Encrypted Data Key Count 1
Encrypted Data Keys Variable
Record Commitment 1
Version

The version of this aws_dbe_head field's format.

Signatures Enabled

Encodes whether ECDSA digital signatures are enabled for this record.

Byte value Meaning
0x01 ECDSA digital signatures enabled (default)
0x00 ECDSA digital signatures disabled
Record ID

A randomly generated 256-bit value that identifies the record. The Record ID:

  • Uniquely identifies the encrypted record.

  • Binds the material description to the encrypted record.

Encrypt Legend

A serialized description of which authenticated fields were encrypted. The Encrypt Legend is used to determine what fields the decryption method should attempt to decrypt.

Byte value Meaning
0x65 ENCRYPT_AND_SIGN
0x73 SIGN_ONLY

The Encrypt Legend is serialized as follows:

  1. Lexicographically by the byte sequence that represents their canonical path.

  2. For each field, in order, append one of the byte values specified above to indicate whether that field should be encrypted.

Encryption Context Length

The length of the encryption context. It is a 2-byte value interpreted as a 16-bit unsigned integer. The maximum length is 65,535 bytes.

Encryption Context

A set of name-value pairs that contain arbitrary, non-secret additional authenticated data.

When ECDSA digital signatures are enabled, the encryption context contains the key-value pair {"aws-crypto-footer-ecdsa-key": Qtxt}. Qtxt represents the elliptic curve point Q compressed according to SEC 1 version 2.0 and then base64-encoded.

Encrypted Data Key Count

The number of encrypted data keys. It is a 1-byte value interpreted as a 8-bit unsigned integer that specifies the number of encrypted data keys. The maximum number of encrypted data keys in each record is 255.

Encrypted Data Keys

A sequence of encrypted data keys. The length of the sequence is determined by the number of encrypted data keys and the length of each. The sequence contains at least one encrypted data key.

The following table describes the fields that form each encrypted data key. The bytes are appended in the order shown.

Encrypted Data Key Structure
Field Length in bytes
Key Provider ID Length 2
Key Provider ID Variable. Equal to the value specified in the previous 2 bytes (Key Provider ID Length).
Key Provider Information Length 2
Key Provider Information Variable. Equal to the value specified in the previous 2 bytes (Key Provider Information Length).
Encrypted Data Key Length 2
Encrypted Data Key Variable. Equal to the value specified in the previous 2 bytes (Encrypted Data Key Length).
Key Provider ID Length

The length of the key provider identifier. It is a 2-byte value interpreted as a 16-bit unsigned integer that specifies the number of bytes that contain the key provider ID.

Key Provider ID

The key provider identifier. It is used to indicate the provider of the encrypted data key and intended to be extensible.

Key Provider Information Length

The length of the key provider information. It is a 2-byte value interpreted as a 16-bit unsigned integer that specifies the number of bytes that contain the key provider information.

Key Provider Information

The key provider information. It is determined by the key provider.

When you are using an AWS KMS keyring, this value contains the Amazon Resource Name (ARN) of the AWS KMS key.

Encrypted Data Key Length

The length of the encrypted data key. It is a 2-byte value interpreted as a 16-bit unsigned integer that specifies the number of bytes that contain the encrypted data key.

Encrypted Data Key

The encrypted data key. It is the data key encrypted by the key provider.

Record Commitment

A distinct 256-bit Hash-Based Message Authentication Code (HMAC) hash calculated over all preceding material description bytes using the commit key.

Show moreShow less

AWS KMS Hierarchical keyring technical details

The AWS KMS Hierarchical keyring uses a unqiue data key to encrypt each field and encrypts each data key with a unique wrapping key derived from an active branch key. It uses a key derivation in counter mode with a pseudorandom function with HMAC SHA-256 to derive the 32 byte wrapping key with the following inputs.

  • A 16 byte random salt

  • The active branch key

  • The UTF-8 encoded value for the key provider identifier "aws-kms-hierarchy"

The Hierarchical keyring uses the derived wrapping key to encrypt a copy of the plaintext data key using AES-GCM-256 with a 16 byte authentication tag and the following inputs.

  • The derived wrapping key is used as the AES-GCM cipher key

  • The data key is used as the AES-GCM message

  • A 12 byte random initialization vector (IV) is used as the AES-GCM IV

  • Additional authenticated data (AAD) containing the following serialized values.

    Value Length in bytes Interpreted as
    "aws-kms-hierarchy" 17 UTF-8 encoded
    The branch key identifier Variable UTF-8 encoded
    The branch key version 16 UTF-8 encoded
    Encryption context Variable UTF-8 encoded key value pairs