AWS Encryption SDK
Developer Guide

Body Additional Authenticated Data (AAD) Reference for the AWS Encryption SDK

The information on this page is a reference for building your own encryption library that is compatible with the AWS Encryption SDK. If you are not building your own compatible encryption library, you likely do not need this information.

To use the AWS Encryption SDK in one of the supported programming languages, see Programming Languages.

You must provide additional authenticated data (AAD) to the AES-GCM algorithm for each cryptographic operation. This is true for both framed and nonframed body data. For more information about AAD and how it is used in Galois/Counter Mode (GCM), see Recommendations for Block Cipher Modes of Operations: Galois/Counter Mode (GCM) and GMAC.

The following table describes the fields that form the body AAD. The bytes are appended in the order shown.

Body AAD Structure

Field Length, in bytes
Message ID 16
Body AAD Content Variable. See Body AAD Content in the following list.
Sequence Number 4
Content Length 8
Message ID

The same Message ID value set in the message header.

Body AAD Content

A UTF-8 encoded value determined by the type of body data used.

For nonframed data, use the value AWSKMSEncryptionClient Single Block.

For regular frames in framed data, use the value AWSKMSEncryptionClient Frame.

For the final frame in framed data, use the value AWSKMSEncryptionClient Final Frame.

Sequence Number

A 4-byte value interpreted as a 32-bit unsigned integer.

For framed data, this is the frame sequence number.

For nonframed data, use the value 1, encoded as the 4 bytes 00 00 00 01 in hexadecimal notation.

Content Length

The length, in bytes, of the plaintext data provided to the algorithm for encryption. It is an 8-byte value interpreted as a 64-bit unsigned integer.