# AWS Encryption SDK reference | | | --- | | 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](programming-languages.md). For the specification that defines the elements of a proper AWS Encryption SDK implementation, see the [AWS Encryption SDK Specification](https://github.com/awslabs/aws-encryption-sdk-specification/) in GitHub. | The AWS Encryption SDK uses the [supported algorithms](supported-algorithms.md) to return a single data structure or *message* that contains encrypted data and the corresponding encrypted data keys. The following topics explain the algorithms and the data structure. Use this information to build libraries that can read and write ciphertexts that are compatible with this SDK. **Topics** + [Message format reference](message-format.md) + [Message format examples](message-format-examples.md) + [Body AAD reference](body-aad-reference.md) + [Algorithms reference](algorithms-reference.md) + [Initialization vector reference](IV-reference.md) + [ # AWS KMS Hierarchical keyring technical details ](hierarchical-keyring-details.md) # AWS Encryption SDK message format reference | | | --- | | 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](programming-languages.md). For the specification that defines the elements of a proper AWS Encryption SDK implementation, see the [AWS Encryption SDK Specification](https://github.com/awslabs/aws-encryption-sdk-specification/) in GitHub. | The encryption operations in the AWS Encryption SDK return a single data structure or [encrypted message](concepts.md#message) that contains the encrypted data (ciphertext) and all encrypted data keys. To understand this data structure, or to build libraries that read and write it, you need to understand the message format. The message format consists of at least two parts: a *header* and a *body*. In some cases, the message format consists of a third part, a *footer*. The message format defines an ordered sequence of bytes in network byte order, also called big-endian format. The message format begins with the header, followed by the body, followed by the footer (when there is one). The [algorithms suites](algorithms-reference.md) supported by the AWS Encryption SDK use one of two message format versions. Algorithm suites without [key commitment](concepts.md#key-commitment) use message format version 1. Algorithm suites with key commitment use message format version 2. **Topics** + [ ## Header structure ](#header-structure) + [ ## Body structure ](#body-structure) + [ ## Footer structure ](#footer-structure) ## Header structure The message header contains the encrypted data key and information about how the message body is formed. The following table describes the fields that form the header in message format versions 1 and 2. The bytes are appended in the order shown. The **Not present** value indicates that the field doesn't exist in that version of the message format. **Bold text** indicates values that are different in each version. **Note** You might need to scroll horizontally or vertically to see all of the data in this table. **Header Structure** | Field | Message format version 1Length (bytes) | Message format version 2Length (bytes) | | --- | --- | --- | | [Version](#header-version) | 1 | 1 | | [Type](#header-type) | 1 | Not present | | [Algorithm ID](#header-algorithm-id) | 2 | 2 | | [Message ID](#header-message-id) | 16 | 32 | | [AAD Length](#header-aad-length) | 2When the [encryption context](concepts.md#encryption-context) is empty, the value of the 2-byte AAD Length field is 0. | 2When the [encryption context](concepts.md#encryption-context) is empty, the value of the 2-byte AAD Length field is 0. | | [AAD](#header-aad) | Variable. The length of this field appears in the previous 2 bytes (AAD Length field). When the [encryption context](concepts.md#encryption-context) is empty, there is no AAD field in the header. | Variable. The length of this field appears in the previous 2 bytes (AAD Length field). When the [encryption context](concepts.md#encryption-context) is empty, there is no AAD field in the header. | | [Encrypted Data Key Count](#header-data-key-count) | 2 | 2 | | [Encrypted Data Key(s)](#header-data-keys) | Variable. Determined by the number of encrypted data keys and the length of each. | Variable. Determined by the number of encrypted data keys and the length of each. | | [Content Type](#header-content-type) | 1 | 1 | | [Reserved](#header-reserved) | 4 | Not present | | [IV Length](#header-iv-length) | 1 | Not present | | [Frame Length](#header-frame-length) | 4 | 4 | | [Algorithm Suite Data](#algorithm-suite-data) | Not present | Variable. Determined by the [algorithm](algorithms-reference.md) that generated the message. | | [Header Authentication](#header-authentication) | Variable. Determined by the [algorithm](algorithms-reference.md) that generated the message. | Variable. Determined by the [algorithm](algorithms-reference.md) that generated the message. | **Version** The version of this message format. The version is either 1 or 2 encoded as the byte `01` or `02` in hexadecimal notation **Type** The type of this message format. The type indicates the kind of structure. The only supported type is described as *customer authenticated encrypted data*. Its type value is 128, encoded as byte `80` in hexadecimal notation. This field is not present in message format version 2. **Algorithm ID** An identifier for the algorithm used. It is a 2-byte value interpreted as a 16-bit unsigned integer. For more information about the algorithms, see [AWS Encryption SDK algorithms reference](algorithms-reference.md). **Message ID** A randomly generated value that identifies the message. The Message ID: + Uniquely identifies the encrypted message. + Weakly binds the message header to the message body. + Provides a mechanism to securely reuse a data key with multiple encrypted messages. + Protects against accidental reuse of a data key or the wearing out of keys in the AWS Encryption SDK. This value is 128 bits in message format version 1 and 256 bits in version 2. **AAD Length** The length of the additional authenticated data (AAD). It is a 2-byte value interpreted as a 16-bit unsigned integer that specifies the number of bytes that contain the AAD. When the [encryption context](concepts.md#encryption-context) is empty, the value of the AAD Length field is 0. **AAD** The additional authenticated data. The AAD is an encoding of the [encryption context](concepts.md#encryption-context), an array of key-value pairs where each key and value is a string of UTF-8 encoded characters. The encryption context is converted to a sequence of bytes and used for the AAD value. When the encryption context is empty, there is no AAD field in the header. When the [algorithms with signing](algorithms-reference.md) are used, the encryption context must contain the key-value pair `{'aws-crypto-public-key', Qtxt}`. Qtxt represents the elliptic curve point Q compressed according to [SEC 1 version 2.0](http://www.secg.org/sec1-v2.pdf) and then base64-encoded. The encryption context can contain additional values, but the maximum length of the constructed AAD is 2^16 - 1 bytes. The following table describes the fields that form the AAD. Key-value pairs are sorted, by key, in ascending order according to UTF-8 character code. The bytes are appended in the order shown. **AAD Structure** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/message-format.html) **Key-Value Pair Count** The number of key-value pairs in the AAD. It is a 2-byte value interpreted as a 16-bit unsigned integer that specifies the number of key-value pairs in the AAD. The maximum number of key-value pairs in the AAD is 2^16 - 1. When there is no encryption context or the encryption context is empty, this field is not present in the AAD structure. **Key Length** The length of the key for the key-value pair. It is a 2-byte value interpreted as a 16-bit unsigned integer that specifies the number of bytes that contain the key. **Key** The key for the key-value pair. It is a sequence of UTF-8 encoded bytes. **Value Length** The length of the value for the key-value pair. It is a 2-byte value interpreted as a 16-bit unsigned integer that specifies the number of bytes that contain the value. **Value** The value for the key-value pair. It is a sequence of UTF-8 encoded bytes. **Encrypted Data Key Count** The number of encrypted data keys. It is a 2-byte value interpreted as a 16-bit unsigned integer that specifies the number of encrypted data keys. The maximum number of encrypted data keys in each message is 65,535 (2^16 - 1). **Encrypted Data Key(s)** 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** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/message-format.html) **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 AWS KMS is the master key provider or 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 encryption key encrypted by the key provider. **Content Type** The type of encrypted data, either nonframed or framed. Whenever possible, use framed data. The AWS Encryption SDK supports nonframed data only for legacy use. Some language implementations of the AWS Encryption SDK can still generate nonframed ciphertext. All supported language implementations can decrypt framed and nonframed ciphertext. Framed data is divided into equal-length parts; each part is encrypted separately. Framed content is type 2, encoded as the byte `02` in hexadecimal notation. Nonframed data is not divided; it is a single encrypted blob. Non-framed content is type 1, encoded as the byte `01` in hexadecimal notation. **Reserved** A reserved sequence of 4 bytes. This value must be 0. It is encoded as the bytes `00 00 00 00` in hexadecimal notation (that is, a 4-byte sequence of a 32-bit integer value equal to 0). This field is not present in message format version 2. **IV Length** The length of the initialization vector (IV). It is a 1-byte value interpreted as an 8-bit unsigned integer that specifies the number of bytes that contain the IV. This value is determined by the IV bytes value of the [algorithm](algorithms-reference.md) that generated the message. This field is not present in message format version 2, which only supports algorithm suites that use deterministic IV values in the message header. **Frame Length** The length of each frame of framed data. It is a 4-byte value interpreted as a 32-bit unsigned integer that specifies the number of bytes in each frame. When the data is nonframed, that is, when the value of the `Content Type` field is 1, this value must be 0. Whenever possible, use framed data. The AWS Encryption SDK supports nonframed data only for legacy use. Some language implementations of the AWS Encryption SDK can still generate nonframed ciphertext. All supported language implementations can decrypt framed and nonframed ciphertext. **Algorithm Suite Data** Supplementary data needed by the [algorithm](algorithms-reference.md) that generated the message. The length and contents are determined by the algorithm. Its length might be 0. This field is not present in message format version 1. **Header Authentication** The header authentication is determined by the [algorithm](algorithms-reference.md) that generated the message. The header authentication is calculated over the entire header. It consists of an IV and an authentication tag. The bytes are appended in the order shown. **Header Authentication Structure** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/message-format.html) **IV** The initialization vector (IV) used to calculate the header authentication tag. This field is not present in the header of message format version 2. Message format version 2 only supports algorithm suites that use deterministic IV values in the message header. **Authentication Tag** The authentication value for the header. It is used to authenticate the entire contents of the header. ## Body structure The message body contains the encrypted data, called the *ciphertext*. The structure of the body depends on the content type (nonframed or framed). The following sections describe the format of the message body for each content type. The message body structure is the same in message format versions 1 and 2. **Topics** + [ ### Non-framed data ](#body-no-framing) + [ ### Framed data ](#body-framing) ### Non-framed data Non-framed data is encrypted in a single blob with a unique IV and [body AAD](body-aad-reference.md). **Note** Whenever possible, use framed data. The AWS Encryption SDK supports nonframed data only for legacy use. Some language implementations of the AWS Encryption SDK can still generate nonframed ciphertext. All supported language implementations can decrypt framed and nonframed ciphertext. The following table describes the fields that form nonframed data. The bytes are appended in the order shown. **Non-Framed Body Structure** | Field | Length, in bytes | | --- | --- | | [IV](#body-unframed-iv) | Variable. Equal to the value specified in the [IV Length](#header-iv-length) byte of the header. | | [Encrypted Content Length](#body-unframed-content-length) | 8 | | [Encrypted Content](#body-unframed-content) | Variable. Equal to the value specified in the previous 8 bytes (Encrypted Content Length). | | [Authentication Tag](#body-unframed-tag) | Variable. Determined by the [algorithm implementation](algorithms-reference.md) used. | **IV** The initialization vector (IV) to use with the [encryption algorithm](algorithms-reference.md). **Encrypted Content Length** The length of the encrypted content, or *ciphertext*. It is an 8-byte value interpreted as a 64-bit unsigned integer that specifies the number of bytes that contain the encrypted content. Technically, the maximum allowed value is 2^63 - 1, or 8 exbibytes (8 EiB). However, in practice the maximum value is 2^36 - 32, or 64 gibibytes (64 GiB), due to restrictions imposed by the [implemented algorithms](algorithms-reference.md). The Java implementation of this SDK further restricts this value to 2^31 - 1, or 2 gibibytes (2 GiB), due to restrictions in the language. **Encrypted Content** The encrypted content (ciphertext) as returned by the [encryption algorithm](algorithms-reference.md). **Authentication Tag** The authentication value for the body. It is used to authenticate the message body. ### Framed data In framed data, the plaintext data is divided into equal-length parts called *frames*. The AWS Encryption SDK encrypts each frame separately with a unique IV and [body AAD](body-aad-reference.md). **Note** Whenever possible, use framed data. The AWS Encryption SDK supports nonframed data only for legacy use. Some language implementations of the AWS Encryption SDK can still generate nonframed ciphertext. All supported language implementations can decrypt framed and nonframed ciphertext. The [frame length](#header-frame-length), which is the length of the [encrypted content](#body-framed-regular-content) in the frame, can be different for each message. The maximum number of bytes in a frame is 2^32 - 1. The maximum number of frames in a message is 2^32 - 1. There are two types of frames: *regular* and *final*. Every message must consist of or include a final frame. All regular frames in a message have the same frame length. The final frame can have a different frame length. The composition of frames in framed data varies with the length of the encrypted content. + **Equal to the frame length** — When the encrypted content length is the same as the frame length of the regular frames, the message can consist of a regular frame that contains the data, followed by a final frame of zero (0) length. Or, the message can consist only of a final frame that contains the data. In this case, the final frame has the same frame length as the regular frames. + **Multiple of the frame length** — When the encrypted content length is an exact multiple of the frame length of the regular frames, the message can end in a regular frame that contains the data, followed by a final frame of zero (0) length. Or, the message can end in a final frame that contains the data. In this case, the final frame has the same frame length as the regular frames. + **Not a multiple of the frame length** — When the encrypted content length is not an exact multiple of the frame length of the regular frames, the final frame contains the remaining data. The frame length of the final frame is less than the frame length of the regular frames. + **Less than the frame length** — When the encrypted content length is less than the frame length of the regular frames, the message consists of a final frame that contains all of the data. The frame length of the final frame is less than the frame length of the regular frames. The following tables describe the fields that form the frames. The bytes are appended in the order shown. **Framed Body Structure, Regular Frame** | Field | Length, in bytes | | --- | --- | | [Sequence Number](#body-framed-regular-sequence-number) | 4 | | [IV](#body-framed-regular-iv) | Variable. Equal to the value specified in the [IV Length](#header-iv-length) byte of the header. | | [Encrypted Content](#body-framed-regular-content) | Variable. Equal to the value specified in the [Frame Length](#header-frame-length) of the header. | | [Authentication Tag](#body-framed-regular-tag) | Variable. Determined by the algorithm used, as specified in the [Algorithm ID](#header-algorithm-id) of the header. | **Sequence Number** The frame sequence number. It is an incremental counter number for the frame. It is a 4-byte value interpreted as a 32-bit unsigned integer. Framed data must start at sequence number 1. Subsequent frames must be in order and must contain an increment of 1 of the previous frame. Otherwise, the decryption process stops and reports an error. **IV** The initialization vector (IV) for the frame. The SDK uses a deterministic method to construct a different IV for each frame in the message. Its length is specified by the [algorithm suite](algorithms-reference.md) used. **Encrypted Content** The encrypted content (ciphertext) for the frame, as returned by the [encryption algorithm](algorithms-reference.md). **Authentication Tag** The authentication value for the frame. It is used to authenticate the entire frame. **Framed Body Structure, Final Frame** | Field | Length, in bytes | | --- | --- | | [Sequence Number End](#body-framed-final-sequence-number-end) | 4 | | [Sequence Number](#body-framed-final-sequence-number) | 4 | | [IV](#body-framed-final-iv) | Variable. Equal to the value specified in the [IV Length](#header-iv-length) byte of the header. | | [Encrypted Content Length](#body-framed-final-content-length) | 4 | | [Encrypted Content](#body-framed-final-content) | Variable. Equal to the value specified in the previous 4 bytes (Encrypted Content Length). | | [Authentication Tag](#body-framed-final-tag) | Variable. Determined by the algorithm used, as specified in the [Algorithm ID](#header-algorithm-id) of the header. | **Sequence Number End** An indicator for the final frame. The value is encoded as the 4 bytes `FF FF FF FF` in hexadecimal notation. **Sequence Number** The frame sequence number. It is an incremental counter number for the frame. It is a 4-byte value interpreted as a 32-bit unsigned integer. Framed data must start at sequence number 1. Subsequent frames must be in order and must contain an increment of 1 of the previous frame. Otherwise, the decryption process stops and reports an error. **IV** The initialization vector (IV) for the frame. The SDK uses a deterministic method to construct a different IV for each frame in the message. The length of the IV length is specified by the [algorithm suite](algorithms-reference.md). **Encrypted Content Length** The length of the encrypted content. It is a 4-byte value interpreted as a 32-bit unsigned integer that specifies the number of bytes that contain the encrypted content for the frame. **Encrypted Content** The encrypted content (ciphertext) for the frame, as returned by the [encryption algorithm](algorithms-reference.md). **Authentication Tag** The authentication value for the frame. It is used to authenticate the entire frame. ## Footer structure When the [algorithms with signing](algorithms-reference.md) are used, the message format contains a footer. The message footer contains a [digital signature](concepts.md#digital-sigs) calculated over the message header and body. The following table describes the fields that form the footer. The bytes are appended in the order shown. The message footer structure is the same in message format versions 1 and 2. **Footer Structure** | Field | Length, in bytes | | --- | --- | | [Signature Length](#footer-signature-length) | 2 | | [Signature](#footer-signature) | Variable. Equal to the value specified in the previous 2 bytes (Signature Length). | **Signature Length** The length of the signature. It is a 2-byte value interpreted as a 16-bit unsigned integer that specifies the number of bytes that contain the signature. **Signature** The signature. # AWS Encryption SDK message format examples | | | --- | | 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](programming-languages.md). For the specification that defines the elements of a proper AWS Encryption SDK implementation, see the [AWS Encryption SDK Specification](https://github.com/awslabs/aws-encryption-sdk-specification/) in GitHub. | The following topics show examples of the AWS Encryption SDK message format. Each example shows the raw bytes, in hexadecimal notation, followed by a description of what those bytes represent. **Topics** + [ ## Framed data (message format version 1) ](#example-framed) + [ ## Framed data (message format version 2) ](#example-framed-2) + [ ## Non-framed data (message format version 1) ](#example-nonframed) ## Framed data (message format version 1) The following example shows the message format for framed data in [message format version 1](message-format.md). ``` +--------+ | Header | +--------+ 01 Version (1.0) 80 Type (128, customer authenticated encrypted data) 0378 Algorithm ID (see Algorithms reference) 6E7C0FBD 4DF4A999 717C22A2 DDFE1A27 Message ID (random 128-bit value) 008E AAD Length (142) 0004 AAD Key-Value Pair Count (4) 0005 AAD Key-Value Pair 1, Key Length (5) 30746869 73 AAD Key-Value Pair 1, Key ("0This") 0002 AAD Key-Value Pair 1, Value Length (2) 6973 AAD Key-Value Pair 1, Value ("is") 0003 AAD Key-Value Pair 2, Key Length (3) 31616E AAD Key-Value Pair 2, Key ("1an") 000A AAD Key-Value Pair 2, Value Length (10) 656E6372 79774690 6F6E AAD Key-Value Pair 2, Value ("encryption") 0008 AAD Key-Value Pair 3, Key Length (8) 32636F6E 74657874 AAD Key-Value Pair 3, Key ("2context") 0007 AAD Key-Value Pair 3, Value Length (7) 6578616D 706C65 AAD Key-Value Pair 3, Value ("example") 0015 AAD Key-Value Pair 4, Key Length (21) 6177732D 63727970 746F2D70 75626C69 AAD Key-Value Pair 4, Key ("aws-crypto-public-key") 632D6B65 79 0044 AAD Key-Value Pair 4, Value Length (68) 416A4173 7569326F 7430364C 4B77715A AAD Key-Value Pair 4, Value ("AjAsui2ot06LKwqZXDJnU/Aqc2vD+0OkpOZ1cc8Tg2qd7rs5aLTg7lvfUEW/86+/5w==") 58444A6E 552F4171 63327644 2B304F6B 704F5A31 63633854 67327164 37727335 614C5467 376C7666 5545572F 38362B2F 35773D3D 0002 EncryptedDataKeyCount (2) 0007 Encrypted Data Key 1, Key Provider ID Length (7) 6177732D 6B6D73 Encrypted Data Key 1, Key Provider ID ("aws-kms") 004B Encrypted Data Key 1, Key Provider Information Length (75) 61726E3A 6177733A 6B6D733A 75732D77 Encrypted Data Key 1, Key Provider Information ("arn:aws:kms:us-west-2:111122223333:key/715c0818-5825-4245-a755-138a6d9a11e6") 6573742D 323A3131 31313232 32323333 33333A6B 65792F37 31356330 3831382D 35383235 2D343234 352D6137 35352D31 33386136 64396131 316536 00A7 Encrypted Data Key 1, Encrypted Data Key Length (167) 01010200 7857A1C1 F7370545 4ECA7C83 Encrypted Data Key 1, Encrypted Data Key 956C4702 23DCE8D7 16C59679 973E3CED 02A4EF29 7F000000 7E307C06 092A8648 86F70D01 0706A06F 306D0201 00306806 092A8648 86F70D01 0701301E 06096086 48016503 04012E30 11040C3F F02C897B 7A12EB19 8BF2D802 0110803B 24003D1F A5474FBC 392360B5 CB9997E0 6A17DE4C A6BD7332 6BF86DAB 60D8CCB8 8295DBE9 4707E356 ADA3735A 7C52D778 B3135A47 9F224BF9 E67E87 0007 Encrypted Data Key 2, Key Provider ID Length (7) 6177732D 6B6D73 Encrypted Data Key 2, Key Provider ID ("aws-kms") 004E Encrypted Data Key 2, Key Provider Information Length (78) 61726E3A 6177733A 6B6D733A 63612D63 Encrypted Data Key 2, Key Provider Information ("arn:aws:kms:ca-central-1:111122223333:key/9b13ca4b-afcc-46a8-aa47-be3435b423ff") 656E7472 616C2D31 3A313131 31323232 32333333 333A6B65 792F3962 31336361 34622D61 6663632D 34366138 2D616134 372D6265 33343335 62343233 6666 00A7 Encrypted Data Key 2, Encrypted Data Key Length (167) 01010200 78FAFFFB D6DE06AF AC72F79B Encrypted Data Key 2, Encrypted Data Key 0E57BD87 3F60F4E6 FD196144 5A002C94 AF787150 69000000 7E307C06 092A8648 86F70D01 0706A06F 306D0201 00306806 092A8648 86F70D01 0701301E 06096086 48016503 04012E30 11040C36 CD985E12 D218B674 5BBC6102 0110803B 0320E3CD E470AA27 DEAB660B 3E0CE8E0 8B1A89E4 57DCC69B AAB1294F 21202C01 9A50D323 72EBAAFD E24E3ED8 7168E0FA DB40508F 556FBD58 9E621C 02 Content Type (2, framed data) 00000000 Reserved 0C IV Length (12) 00000100 Frame Length (256) 4ECBD5C0 9899CA65 923D2347 IV 0B896144 0CA27950 CA571201 4DA58029 Authentication Tag +------+ | Body | +------+ 00000001 Frame 1, Sequence Number (1) 6BD3FE9C ADBCB213 5B89E8F1 Frame 1, IV 1F6471E0 A51AF310 10FA9EF6 F0C76EDF Frame 1, Encrypted Content F5AFA33C 7D2E8C6C 9C5D5175 A212AF8E FBD9A0C3 C6E3FB59 C125DBF2 89AC7939 BDEE43A8 0F00F49E ACBBD8B2 1C785089 A90DB923 699A1495 C3B31B50 0A48A830 201E3AD9 1EA6DA14 7F6496DB 6BC104A4 DEB7F372 375ECB28 9BF84B6D 2863889F CB80A167 9C361C4B 5EC07438 7A4822B4 A7D9D2CC 5150D414 AF75F509 FCE118BD 6D1E798B AEBA4CDB AD009E5F 1A571B77 0041BC78 3E5F2F41 8AF157FD 461E959A BB732F27 D83DC36D CC9EBC05 00D87803 57F2BB80 066971C2 DEEA062F 4F36255D E866C042 E1382369 12E9926B BA40E2FC A820055F FB47E428 41876F14 3B6261D9 5262DB34 59F5D37E 76E46522 E8213640 04EE3CC5 379732B5 F56751FA 8E5F26AD Frame 1, Authentication Tag 00000002 Frame 2, Sequence Number (2) F1140984 FF25F943 959BE514 Frame 2, IV 216C7C6A 2234F395 F0D2D9B9 304670BF Frame 2, Encrypted Content A1042608 8A8BCB3F B58CF384 D72EC004 A41455B4 9A78BAC9 36E54E68 2709B7BD A884C1E1 705FF696 E540D297 446A8285 23DFEE28 E74B225A 732F2C0C 27C6BDA2 7597C901 65EF3502 546575D4 6D5EBF22 1FF787AB 2E38FD77 125D129C 43D44B96 778D7CEE 3C36625F FF3A985C 76F7D320 ED70B1F3 79729B47 E7D9B5FC 02FCE9F5 C8760D55 7779520A 81D54F9B EC45219D 95941F7E 5CBAEAC8 CEC13B62 1464757D AC65B6EF 08262D74 44670624 A3657F7F 2A57F1FD E7060503 AC37E197 2F297A84 DF1172C2 FA63CF54 E6E2B9B6 A86F582B 3B16F868 1BBC5E4D 0B6919B3 08D5ABCF FECDC4A4 8577F08B 99D766A1 E5545670 A61F0A3B A3E45A84 4D151493 63ECA38F Frame 2, Authentication Tag FFFFFFFF Final Frame, Sequence Number End 00000003 Final Frame, Sequence Number (3) 35F74F11 25410F01 DD9E04BF Final Frame, IV 0000008E Final Frame, Encrypted Content Length (142) F7A53D37 2F467237 6FBD0B57 D1DFE830 Final Frame, Encrypted Content B965AD1F A910AA5F 5EFFFFF4 BC7D431C BA9FA7C4 B25AF82E 64A04E3A A0915526 88859500 7096FABB 3ACAD32A 75CFED0C 4A4E52A3 8E41484D 270B7A0F ED61810C 3A043180 DF25E5C5 3676E449 0986557F C051AD55 A437F6BC 139E9E55 6199FD60 6ADC017D BA41CDA4 C9F17A83 3823F9EC B66B6A5A 80FDB433 8A48D6A4 21CB 811234FD 8D589683 51F6F39A 040B3E3B Final Frame, Authentication Tag +--------+ | Footer | +--------+ 0066 Signature Length (102) 30640230 085C1D3C 63424E15 B2244448 Signature 639AED00 F7624854 F8CF2203 D7198A28 758B309F 5EFD9D5D 2E07AD0B 467B8317 5208B133 02301DF7 2DFC877A 66838028 3C6A7D5E 4F8B894E 83D98E7C E350F424 7E06808D 0FE79002 E24422B9 98A0D130 A13762FF 844D ``` ## Framed data (message format version 2) The following example shows the message format for framed data in [message format version 2](message-format.md). ``` +--------+ | Header | +--------+ 02 Version (2.0) 0578 Algorithm ID (see Algorithms reference) 122747eb 21dfe39b 38631c61 7fad7340 cc621a30 32a11cc3 216d0204 fd148459 Message ID (random 256-bit value) 008e AAD Length (142) 0004 AAD Key-Value Pair Count (4) 0005 AAD Key-Value Pair 1, Key Length (5) 30546869 73 AAD Key-Value Pair 1, Key ("0This") 0002 AAD Key-Value Pair 1, Value Length (2) 6973 AAD Key-Value Pair 1, Value ("is") 0003 AAD Key-Value Pair 2, Key Length (3) 31616e AAD Key-Value Pair 2, Key ("1an") 000a AAD Key-Value Pair 2, Value Length (10) 656e6372 79707469 6f6e AAD Key-Value Pair 2, Value ("encryption") 0008 AAD Key-Value Pair 3, Key Length (8) 32636f6e 74657874 AAD Key-Value Pair 3, Key ("2context") 0007 AAD Key-Value Pair 3, Value Length (7) 6578616d 706c65 AAD Key-Value Pair 3, Value ("example") 0015 AAD Key-Value Pair 4, Key Length (21) 6177732d 63727970 746f2d70 75626c69 AAD Key-Value Pair 4, Key ("aws-crypto-public-key") 632d6b65 79 0044 AAD Key-Value Pair 4, Value Length (68) 41746733 72703845 41345161 36706669 AAD Key-Value Pair 4, Value ("QXRnM3JwOEVBNFFhNnBmaTk3MUlTNTk3NHpOMnlZWE5vSmtwRHFPc0dIYkVaVDRqME5OMlFkRStmbTFVY01WdThnPT0=") 39373149 53353937 347a4e32 7959584e 6f4a6b70 44714f73 47486245 5a54346a 304e4e32 5164452b 666d3155 634d5675 38673d3d 0001 Encrypted Data Key Count (1) 0007 Encrypted Data Key 1, Key Provider ID Length (7) 6177732d 6b6d73 Encrypted Data Key 1, Key Provider ID ("aws-kms") 004b Encrypted Data Key 1, Key Provider Information Length (75) 61726e3a 6177733a 6b6d733a 75732d77 Encrypted Data Key 1, Key Provider Information ("arn:aws:kms:us-west-2:658956600833:key/b3537ef1-d8dc-4780-9f5a-55776cbb2f7f") 6573742d 323a3635 38393536 36303038 33333a6b 65792f62 33353337 6566312d 64386463 2d343738 302d3966 35612d35 35373736 63626232 663766 00a7 Encrypted Data Key 1, Encrypted Data Key Length (167) 01010100 7840f38c 275e3109 7416c107 Encrypted Data Key 1, Encrypted Data Key 29515057 1964ada3 ef1c21e9 4c8ba0bd bc9d0fb4 14000000 7e307c06 092a8648 86f70d01 0706a06f 306d0201 00306806 092a8648 86f70d01 0701301e 06096086 48016503 04012e30 11040c39 32d75294 06063803 f8460802 0110803b 2a46bc23 413196d2 903bf1d7 3ed98fc8 a94ac6ed e00ee216 74ec1349 12777577 7fa052a5 ba62e9e4 f2ac8df6 bcb1758f 2ce0fb21 cc9ee5c9 7203bb 02 Content Type (2, framed data) 00001000 Frame Length (4096) 05cd035b 29d5499d 4587570b 87502afe Algorithm Suite Data (key commitment) 634f7b2c c3df2aa9 88a10105 4a2c7687 76cb339f 2536741f 59a1c202 4f2594ab Authentication Tag +------+ | Body | +------+ ffffffff Final Frame, Sequence Number End 00000001 Final Frame, Sequence Number (1) 00000000 00000000 00000001 Final Frame, IV 00000009 Final Frame, Encrypted Content Length (9) fa6e39c6 02927399 3e Final Frame, Encrypted Content f683a564 405d68db eeb0656c d57c9eb0 Final Frame, Authentication Tag +--------+ | Footer | +--------+ 0067 Signature Length (103) 30650230 2a1647ad 98867925 c1712e8f Signature ade70b3f 2a2bc3b8 50eb91ef 56cfdd18 967d91d8 42d92baf 357bba48 f636c7a0 869cade2 023100aa ae12d08f 8a0afe85 e5054803 110c9ed8 11b2e08a c4a052a9 074217ea 3b01b660 534ac921 bf091d12 3657e2b0 9368bd ``` ## Non-framed data (message format version 1) The following example shows the message format for nonframed data. **Note** Whenever possible, use framed data. The AWS Encryption SDK supports nonframed data only for legacy use. Some language implementations of the AWS Encryption SDK can still generate nonframed ciphertext. All supported language implementations can decrypt framed and nonframed ciphertext. ``` +--------+ | Header | +--------+ 01 Version (1.0) 80 Type (128, customer authenticated encrypted data) 0378 Algorithm ID (see Algorithms reference) B8929B01 753D4A45 C0217F39 404F70FF Message ID (random 128-bit value) 008E AAD Length (142) 0004 AAD Key-Value Pair Count (4) 0005 AAD Key-Value Pair 1, Key Length (5) 30746869 73 AAD Key-Value Pair 1, Key ("0This") 0002 AAD Key-Value Pair 1, Value Length (2) 6973 AAD Key-Value Pair 1, Value ("is") 0003 AAD Key-Value Pair 2, Key Length (3) 31616E AAD Key-Value Pair 2, Key ("1an") 000A AAD Key-Value Pair 2, Value Length (10) 656E6372 79774690 6F6E AAD Key-Value Pair 2, Value ("encryption") 0008 AAD Key-Value Pair 3, Key Length (8) 32636F6E 74657874 AAD Key-Value Pair 3, Key ("2context") 0007 AAD Key-Value Pair 3, Value Length (7) 6578616D 706C65 AAD Key-Value Pair 3, Value ("example") 0015 AAD Key-Value Pair 4, Key Length (21) 6177732D 63727970 746F2D70 75626C69 AAD Key-Value Pair 4, Key ("aws-crypto-public-key") 632D6B65 79 0044 AAD Key-Value Pair 4, Value Length (68) 41734738 67473949 6E4C5075 3136594B AAD Key-Value Pair 4, Value ("AsG8gG9InLPu16YKlqXTOD+nykG8YqHAhqecj8aXfD2e5B4gtVE73dZkyClA+rAMOQ==") 6C715854 4F442B6E 796B4738 59714841 68716563 6A386158 66443265 35423467 74564537 33645A6B 79436C41 2B72414D 4F513D3D 0002 Encrypted Data Key Count (2) 0007 Encrypted Data Key 1, Key Provider ID Length (7) 6177732D 6B6D73 Encrypted Data Key 1, Key Provider ID ("aws-kms") 004B Encrypted Data Key 1, Key Provider Information Length (75) 61726E3A 6177733A 6B6D733A 75732D77 Encrypted Data Key 1, Key Provider Information ("arn:aws:kms:us-west-2:111122223333:key/715c0818-5825-4245-a755-138a6d9a11e6") 6573742D 323A3131 31313232 32323333 33333A6B 65792F37 31356330 3831382D 35383235 2D343234 352D6137 35352D31 33386136 64396131 316536 00A7 Encrypted Data Key 1, Encrypted Data Key Length (167) 01010200 7857A1C1 F7370545 4ECA7C83 Encrypted Data Key 1, Encrypted Data Key 956C4702 23DCE8D7 16C59679 973E3CED 02A4EF29 7F000000 7E307C06 092A8648 86F70D01 0706A06F 306D0201 00306806 092A8648 86F70D01 0701301E 06096086 48016503 04012E30 11040C28 4116449A 0F2A0383 659EF802 0110803B B23A8133 3A33605C 48840656 C38BCB1F 9CCE7369 E9A33EBE 33F46461 0591FECA 947262F3 418E1151 21311A75 E575ECC5 61A286E0 3E2DEBD5 CB005D 0007 Encrypted Data Key 2, Key Provider ID Length (7) 6177732D 6B6D73 Encrypted Data Key 2, Key Provider ID ("aws-kms") 004E Encrypted Data Key 2, Key Provider Information Length (78) 61726E3A 6177733A 6B6D733A 63612D63 Encrypted Data Key 2, Key Provider Information ("arn:aws:kms:ca-central-1:111122223333:key/9b13ca4b-afcc-46a8-aa47-be3435b423ff") 656E7472 616C2D31 3A313131 31323232 32333333 333A6B65 792F3962 31336361 34622D61 6663632D 34366138 2D616134 372D6265 33343335 62343233 6666 00A7 Encrypted Data Key 2, Encrypted Data Key Length (167) 01010200 78FAFFFB D6DE06AF AC72F79B Encrypted Data Key 2, Encrypted Data Key 0E57BD87 3F60F4E6 FD196144 5A002C94 AF787150 69000000 7E307C06 092A8648 86F70D01 0706A06F 306D0201 00306806 092A8648 86F70D01 0701301E 06096086 48016503 04012E30 11040CB2 A820D0CC 76616EF2 A6B30D02 0110803B 8073D0F1 FDD01BD9 B0979082 099FDBFC F7B13548 3CC686D7 F3CF7C7A CCC52639 122A1495 71F18A46 80E2C43F A34C0E58 11D05114 2A363C2A E11397 01 Content Type (1, nonframed data) 00000000 Reserved 0C IV Length (12) 00000000 Frame Length (0, nonframed data) 734C1BBE 032F7025 84CDA9D0 IV 2C82BB23 4CBF4AAB 8F5C6002 622E886C Authentication Tag +------+ | Body | +------+ D39DD3E5 915E0201 77A4AB11 IV 00000000 0000028E Encrypted Content Length (654) E8B6F955 B5F22FE4 FD890224 4E1D5155 Encrypted Content 5871BA4C 93F78436 1085E4F8 D61ECE28 59455BD8 D76479DF C28D2E0B BDB3D5D3 E4159DFE C8A944B6 685643FC EA24122B 6766ECD5 E3F54653 DF205D30 0081D2D8 55FCDA5B 9F5318BC F4265B06 2FE7C741 C7D75BCC 10F05EA5 0E2F2F40 47A60344 ECE10AA7 559AF633 9DE2C21B 12AC8087 95FE9C58 C65329D1 377C4CD7 EA103EC1 31E4F48A 9B1CC047 EE5A0719 704211E5 B48A2068 8060DF60 B492A737 21B0DB21 C9B21A10 371E6179 78FAFB0B BAAEC3F4 9D86E334 701E1442 EA5DA288 64485077 54C0C231 AD43571A B9071925 609A4E59 B8178484 7EB73A4F AAE46B26 F5B374B8 12B0000C 8429F504 936B2492 AAF47E94 A5BA804F 7F190927 5D2DF651 B59D4C2F A15D0551 DAEBA4AF 2060D0D5 CB1DA4E6 5E2034DB 4D19E7CD EEA6CF7E 549C86AC 46B2C979 AB84EE12 202FD6DF E7E3C09F C2394012 AF20A97E 369BCBDA 62459D3E C6FFB914 FEFD4DE5 88F5AFE1 98488557 1BABBAE4 BE55325E 4FB7E602 C1C04BEE F3CB6B86 71666C06 6BF74E1B 0F881F31 B731839B CF711F6A 84CA95F5 958D3B44 E3862DF6 338E02B5 C345CFF8 A31D54F3 6920AA76 0BF8E903 552C5A04 917CCD11 D4E5DF5C 491EE86B 20C33FE1 5D21F0AD 6932E67C C64B3A26 B8988B25 CFA33E2B 63490741 3AB79D60 D8AEFBE9 2F48E25A 978A019C FE49EE0A 0E96BF0D D6074DDB 66DFF333 0E10226F 0A1B219C BE54E4C2 2C15100C 6A2AA3F1 88251874 FDC94F6B 9247EF61 3E7B7E0D 29F3AD89 FA14A29C 76E08E9B 9ADCDF8C C886D4FD A69F6CB4 E24FDE26 3044C856 BF08F051 1ADAD329 C4A46A1E B5AB72FE 096041F1 F3F3571B 2EAFD9CB B9EB8B83 AE05885A 8F2D2793 1E3305D9 0C9E2294 E8AD7E3B 8E4DEC96 6276C5F1 A3B7E51E 422D365D E4C0259C 50715406 822D1682 80B0F2E5 5C94 65B2E942 24BEEA6E A513F918 CCEC1DE3 Authentication Tag +--------+ | Footer | +--------+ 0067 Signature Length (103) 30650230 7229DDF5 B86A5B64 54E4D627 Signature CBE194F1 1CC0F8CF D27B7F8B F50658C0 BE84B355 3CED1721 A0BE2A1B 8E3F449E 1BEB8281 023100B2 0CB323EF 58A4ACE3 1559963B 889F72C3 B15D1700 5FB26E61 331F3614 BC407CEE B86A66FA CBF74D9E 34CB7E4B 363A38 ``` # 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](programming-languages.md). For the specification that defines the elements of a proper AWS Encryption SDK implementation, see the [AWS Encryption SDK Specification](https://github.com/awslabs/aws-encryption-sdk-specification/) in GitHub. | You must provide additional authenticated data (AAD) to the [AES-GCM algorithm](algorithms-reference.md) for each cryptographic operation. This is true for both framed and nonframed [body data](message-format.md#body-structure). 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](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf). 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](#body-aad-message-id) | 16 | | [Body AAD Content](#body-aad-content) | Variable. See Body AAD Content in the following list. | | [Sequence Number](#body-aad-sequence-number) | 4 | | [Content Length](#body-aad-content-length) | 8 | **Message ID** The same [Message ID](message-format.md#header-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](message-format.md#body-no-framing), use the value `AWSKMSEncryptionClient Single Block`. For regular frames in [framed data](message-format.md#body-framing), use the value `AWSKMSEncryptionClient Frame`. For the final frame in [framed data](message-format.md#body-framing), use the value `AWSKMSEncryptionClient Final Frame`. **Sequence Number** A 4-byte value interpreted as a 32-bit unsigned integer. For [framed data](message-format.md#body-framing), this is the frame sequence number. For [nonframed data](message-format.md#body-no-framing), 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. # AWS Encryption SDK algorithms reference | | | --- | | 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](programming-languages.md). For the specification that defines the elements of a proper AWS Encryption SDK implementation, see the [AWS Encryption SDK Specification](https://github.com/awslabs/aws-encryption-sdk-specification/) in GitHub. | If you are building your own library that can read and write ciphertexts that are compatible with the AWS Encryption SDK, you'll need to understand how the AWS Encryption SDK implements the supported algorithm suites to encrypt raw data. The AWS Encryption SDK supports the following algorithm suites. All AES-GCM algorithm suites have a 12-byte [initialization vector](IV-reference.md) and a 16-byte AES-GCM authentication tag. The default algorithm suite varies with the AWS Encryption SDK version and the selected key commitment policy. For details, see [Commitment policy and algorithm suite](troubleshooting-migration.md#configuration-conflict_1). **AWS Encryption SDK Algorithm Suites** | Algorithm ID | Message format version | Encryption algorithm | Data key length (bits) | Key derivation algorithm | Signature algorithm | Key commitment algorithm | Algorithm suite data length (bytes) | | --- | --- | --- | --- | --- | --- | --- | --- | | 05 78 | 0x02 | AES-GCM | 256 | HKDF with SHA-512 | ECDSA with P-384 and SHA-384 | HKDF with SHA-512 | 32 (key commitment) | | 04 78 | 0x02 | AES-GCM | 256 | HKDF with SHA-512 | None | HKDF with SHA-512 | 32 (key commitment) | | 03 78 | 0x01 | AES-GCM | 256 | HKDF with SHA-384 | ECDSA with P-384 and SHA-384 | None | N/A | | 03 46 | 0x01 | AES-GCM | 192 | HKDF with SHA-384 | ECDSA with P-384 and SHA-384 | None | N/A | | 02 14 | 0x01 | AES-GCM | 128 | HKDF with SHA-256 | ECDSA with P-256 and SHA-256 | None | N/A | | 01 78 | 0x01 | AES-GCM | 256 | HKDF with SHA-256 | None | None | N/A | | 01 46 | 0x01 | AES-GCM | 192 | HKDF with SHA-256 | None | None | N/A | | 01 14 | 0x01 | AES-GCM | 128 | HKDF with SHA-256 | None | None | N/A | | 00 78 | 0x01 | AES-GCM | 256 | None | None | None | N/A | | 00 46 | 0x01 | AES-GCM | 192 | None | None | None | N/A | | 00 14 | 0x01 | AES-GCM | 128 | None | None | None | N/A | **Algorithm ID** A 2-byte hexadecimal value that uniquely identifies an algorithm implementation. This value is stored in the [message header](message-format.md#header-structure) of the ciphertext. **Message format version** The version of the message format. Algorithm suites with key commitment use message format version 2 (0x02). Algorithm suites without key commitment use message format version 1 (0x01). **Algorithm suite data length** The length in bytes of data specific to the algorithm suite. This field is supported only in message format version 2 (0x02). In message format version 2 (0x02), this data appears in the `Algorithm suite data` field of the message header. Algorithm suites that support [key commitment](concepts.md#key-commitment) use 32 bytes for the key commitment string. For more information, see **Key commitment algorithm** in this list. **Data key length** The length of the [data key](concepts.md#DEK) in bits. The AWS Encryption SDK supports 256-bit, 192-bit, and 128-bit keys. The data key is generated by a [keyring](concepts.md#keyring) or master key. In some implementations, this 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. For more information, see **Key derivation algorithm** in this list. **Encryption algorithm** The name and mode of the encryption algorithm used. Algorithm suites in the AWS Encryption SDK use the Advanced Encryption Standard (AES) encryption algorithm with Galois/Counter Mode (GCM). **Key commitment algorithm** The algorithm used to calculate the key commitment string. The output is stored in the `Algorithm suite data` field of the message header and is used to validate the data key for key commitment. 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. **Key derivation algorithm** The HMAC-based extract-and-expand key derivation function (HKDF) used to derive the data encryption key. The AWS Encryption SDK uses the HKDF defined in [RFC 5869](https://tools.ietf.org/html/rfc5869). **Algorithm suites without key commitment** (algorithm ID `01xx` – `03xx`) + The hash function used is either SHA-384 or SHA-256, depending on the algorithm suite. + For the extract step: + No salt is used. Per the RFC, the salt is set to a string of zeros. The string length is equal to the length of the hash function output, which is 48 bytes for SHA-384 and 32 bytes for SHA-256. + The input keying material is the data key from the keyring or master key provider. + For the expand step: + The input pseudorandom key is the output from the extract step. + The input info is a concatenation of the algorithm ID and message ID (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. **Algorithm suites with key commitment** (algorithm ID `04xx` and `05xx`) + The hash function used is SHA-512. + For the extract step: + The salt is a 256-bit cryptographic random value. In [message format version 2](message-format.md) (0x02), this value is stored in the `MessageID` field. + The initial keying material is the data key from the keyring or master key provider. + 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. **Message format version** The version of the message format used with the algorithm suite. For details, see [Message format reference](message-format.md). **Signature algorithm** The signature algorithm that is used to generate a [digital signature](concepts.md#digital-sigs) over the ciphertext header and body. The AWS Encryption SDK uses the Elliptic Curve Digital Signature Algorithm (ECDSA) with the following specifics: + The elliptic curve used is either the P-384 or P-256 curve, as specified by the algorithm ID. These curves are 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 (with the P-384 curve) or SHA-256 (with the P-256 curve). # AWS Encryption SDK initialization vector reference | | | --- | | 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](programming-languages.md). For the specification that defines the elements of a proper AWS Encryption SDK implementation, see the [AWS Encryption SDK Specification](https://github.com/awslabs/aws-encryption-sdk-specification/) in GitHub. | The AWS Encryption SDK supplies the [initialization vectors](https://en.wikipedia.org/wiki/Initialization_vector) (IVs) that are required by all supported [algorithm suites](algorithms-reference.md). The SDK uses frame sequence numbers to construct an IV so that no two frames in the same message can have the same IV. Each 96-bit (12-byte) IV is constructed from two big-endian byte arrays concatenated in the following order: + 64 bits: 0 (reserved for future use) + 32 bits: Frame sequence number. For the header authentication tag, this value is all zeroes. Before the introduction of [data key caching](data-key-caching.md), the AWS Encryption SDK always used a new data key to encrypt each message, and it generated all IVs randomly. Randomly generated IVs were cryptographically safe because data keys were never reused. When the SDK introduced data key caching, which intentionally reuses data keys, we changed the way the SDK generates IVs. Using deterministic IVs that cannot repeat within a message significantly increases the number of invocations that can safely be executed under a single data key. In addition, data keys that are cached always use an algorithm suite with a [key derivation function](https://en.wikipedia.org/wiki/Key_derivation_function). Using a deterministic IV with a pseudo-random key derivation function to derive encryption keys from a data key allows the AWS Encryption SDK to encrypt 2^32 messages without exceeding cryptographic bounds. # AWS KMS Hierarchical keyring technical details The [AWS KMS Hierarchical keyring](use-hierarchical-keyring.md) uses a unqiue data key to encrypt each message and encrypts each data key with a unique wrapping key derived from an active branch key. It uses a [key derivation](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-108r1.pdf) 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](https://en.wikipedia.org/wiki/UTF-8) 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. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/hierarchical-keyring-details.html)