Menu
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.

Regardless of which type of body data is used to form the message body (non-framed or framed), you must provide additional authenticated data (AAD) to the AES-GCM algorithm for each cryptographic operation. For more information about AAD, see the definition section in the Galois/Counter Mode of Operation (GCM) specification.

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 non-framed 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 non-framed 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.