0.6.0
-
0.6.0
- Update keystore structure and add encryption context options
-
0.5.0
- Rename Hierarchical Materials to Branch Key Materials.
- Add Beacon Key Materials
-
0.4.0
- Add symmetric signature keys to materials
- Add Hierarchical Materials.
-
0.3.0
- Clarify handling of the
aws-crypto-public-keyencryption context key.
- Clarify handling of the
-
0.2.1
-
0.2.0
-
0.1.0-preview
- Initial record
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
This document includes the specifications for common structures referenced throughout the AWS Encryption SDK specification. These structures define a group of related fields that MUST hold certain properties. Wherever these structures are referenced in this specification, implementations MUST ensure that all properties of a structure's fields are upheld.
Note that this specification does not specify how these structures should be represented or passed throughout the AWS Encryption SDK framework. While these structures will usually be represented as objects, lower level languages MAY represent these fields in a less strictly defined way as long as all field properties are still upheld.
Structures defined in this document:
- Encrypted Data Key
- Encryption Context
- Encryption Materials
- Decryption Materials
- Branch Key Materials
- Beacon Key Materials
An encrypted data key is comprised of the following fields:
Note: "Encrypted" is a misnomer here, as the process by which a key provider may obtain the plaintext data key from the ciphertext and vice versa does not have to be an encryption and decryption cipher. This specification uses the terms "encrypt" and "decrypt" for simplicity, but the actual process by which a key provider obtains the plaintext data key from the ciphertext and vice versa MAY be any reversible operation, though we expect that most will use encryption.
The key provider ID value for the keyring that wrote this encrypted data key.
The key provider info value for the keyring that wrote this encrypted data key.
An opaque value from which an appropriate key provider can obtain the plaintext data key.
Some key provider MUST be capable of deterministically obtaining the plaintext key from the ciphertext.
Most commonly this is an encrypted form of the plaintext data key. Alternatively, it could be the public input to a KDF that derives the plaintext data key or an identifier into a key store that will return the plaintext data key.
The encryption context is a key-value mapping of arbitrary, non-secret, UTF-8 encoded strings. It is used during encryption and decryption to provide additional authenticated data (AAD).
Users SHOULD use the encryption context to store:
- Non-secret data that MUST remain associated with the message ciphertext.
- Data that is useful in logging and tracking, such as data about the file type, purpose, or ownership.
Users MUST NOT use the encryption context to store secret data.
If the encryption context is empty, its serialization MUST be an empty byte sequence.
If the encryption context is not empty, its serialization MUST take the following form:
| Field | Length (bytes) | Interpreted as |
|---|---|---|
| Key Value Pair Count | 2 | UInt16 |
| Key Value Pair Entries | Variable. Determined by the count and length of each key-value pair. | Key Value Pair Entries |
The number of key-value pairs within the Key Value Pair Entries field. The value of this field MUST be greater than 0.
A sequence of one or more key-value pair entries.
This sequence MUST NOT contain duplicate entries.
These entries MUST be sorted, by key, in ascending order according to the UTF-8 encoded binary value.
The following table describes the fields that form each key value pair entry. The bytes are appended in the order shown.
| Field | Length (bytes) | Interpreted as |
|---|---|---|
| Key Length | 2 | UInt16 |
| Key | Variable. Equal to the value specified in the previous 2 bytes (Key Length). | UTF-8 encoded bytes |
| Value Length | 2 | UInt16 |
| Value | Variable. Equal to the value specified in the previous 2 bytes (Value Length). | UTF-8 encoded bytes |
| Language | Confirmed Compatible with Spec Version | Minimum Version Confirmed | Implementation |
|---|---|---|---|
| C | 0.1.0-preview | 0.1.0 | materials.h |
| Javascript | 0.1.0-preview | 0.1.0 | cryptographic_material.ts |
| Python | 0.1.0-preview | n/a | materials_managers |
| Java | 0.1.0-preview | n/a | EncryptionMaterials.java |
Encryption materials are a structure containing materials needed for encryption. This structure MUST include the following fields:
This structure MAY include any of the following fields:
The algorithm suite to be used for encryption.
A list of the encrypted data keys that correspond to the plaintext data key.
The ciphertext of each encrypted data key in this list MUST be an opaque form of the plaintext data key from this set of encryption materials.
If the plaintext data key is not included in this set of encryption materials, this list MUST be empty.
The encryption context associated with this encryption.
If an encryption material contains a signing key,
the encryption context SHOULD include the reserved key aws-crypto-public-key.
The mapped value from the reserved key aws-crypto-public-key SHOULD be the signature verification key
corresponding to the signing key stored on the encryption material.
If an encryption material does not contains a signing key,
the encryption context SHOULD NOT include the reserved key aws-crypto-public-key.
A data key to be used as input for encryption.
The plaintext data key MUST:
- Fit the specification for the key derivation algorithm included in this decryption material's algorithm suite.
- Consist of cryptographically secure (pseudo-)random bits.
- Be kept secret.
The plaintext data key SHOULD be stored as immutable data.
The plaintext data key SHOULD offer an interface to zero the plaintext data key.
The key to be used as the signing key for asymmetric signature verification during encryption.
The signing key MUST fit the specification described by the asymmetric signature algorithm included in this encryption material's algorithm suite. If the algorithm suite does not contain an asymmetric signing algorithm, the signing key MUST NOT be present.
The value of this key MUST be kept secret.
Communicates to higher level encrypt APIs
of supported formats
how to split the encryption context
into elements that are authenticated and stored
from elements that are only authenticated and not stored.
Keys in this set should not be stored
with ciphertext protected by these materials.
These keys are required to be reproduced on decrypt.
Every key in Required Encryption Context Keys MUST be a key in the encryption context.
A list of symmetric signing keys, such that each key in this list corresponds to the encrypted data key in the encrypted data key list at the same index. These keys are used to generate symmetric signatures during encryption.
If the algorithm suite does not contain a symmetric signing algorithm, this list MUST NOT be included in the materials. If the algorithm suite does contain a symmetric signing algorithm, this list MUST have length equal to the encrypted data key list.
The symmetric signature keys MUST adhere to the specification for symmetric signature algorithms included in this encryption material's algorithm suite.
The value of keys in this list MUST be kept secret.
| Language | Confirmed Compatible with Spec Version | Minimum Version Confirmed | Implementation |
|---|---|---|---|
| C | 0.1.0-preview | 0.1.0 | materials.h |
| Javascript | 0.1.0-preview | 0.1.0 | cryptographic_material.ts |
| Python | 0.1.0-preview | n/a | materials_managers |
| Java | 0.1.0-preview | n/a | DecryptionMaterials.java |
Decryption materials are a structure containing materials needed for decryption. This structure MUST include the following fields:
This structure MAY include any of the following fields:
The algorithm suite to be used for decryption.
The encryption context associated with this decryption.
If a decryption materials contains a verification key,
the encryption context SHOULD include the reserved key aws-crypto-public-key.
The mapped value from the reserved key aws-crypto-public-key
SHOULD be the signature verification key stored on the decryption materials.
If a decryption materials does not contain a verification key,
the encryption context SHOULD NOT include the reserved key aws-crypto-public-key.
The data key to be used as input for decryption.
The plaintext data key MUST:
- Fit the specification for the encryption algorithm included in this decryption material's algorithm suite.
- Consist of cryptographically secure (pseudo-)random bits.
- Be kept secret.
The plaintext data key SHOULD be stored as immutable data.
The plaintext data key SHOULD offer an interface to zero the plaintext data key.
The key to be used as the verification key for asymmetric signature verification during decryption.
The verification key MUST fit the specification for the asymmetric signature algorithm included in this decryption material's algorithm suite.
A set of strings to communicate to higher level decrypt APIs
of supported formats
how to split the encryption context
into elements that are authenticated and stored
from elements that are only authenticated
and not stored in the encrypted message.
Keys in this set should not have been stored
with the ciphertext protected by these materials.
These keys should have been reproduced by the caller on decrypt.
Every key in Required Encryption Context Keys MUST be a key in the encryption context.
The key to be used to validate a symmetric signature during decryption.
If the algorithm suite does not contain a symmetric signing algorithm, the symmetric signing key MUST NOT be included in the materials.
If the algorithm suite does contain a symmetric signing algorithm, the symmetric signing key MUST also be included in the materials if and only if the materials also include a plaintext data key.
If included, the symmetric signature key MUST fit the specification for the symmetric signature algorithm included in this decryption material's algorithm suite.
This value MUST be kept secret.
| Language | Confirmed Compatible with Spec Version | Minimum Version Confirmed | Implementation |
|---|
Branch Key materials are a structure containing materials that are used to establish a key hierarchy in order to reuse a data key that wraps other data keys. This structure MUST include all of the following fields:
Data keys that are reused to derive unique data keys for envelope encryption.
This data key MUST only be generated through
AWS KMS using the GenerateDataKeyWithoutPlaintext API.
This key MUST be 32 bytes long.
The UTF8 Encoded value of the ID of the corresponding branch key. The plaintext value of which is stored in the branch key store.
The UTF8 Encoded value of the version of the corresponding branch key. The plaintext value of which is stored in the branch key store. This value MUST be a version 4 UUID.
The custom encryption context associated with this branch key.
| Language | Confirmed Compatible with Spec Version | Minimum Version Confirmed | Implementation |
|---|
Beacon Key materials are a structure containing materials that are used in structured encryption. They contain HMAC keys derived from a Beacon Key stored in the Keystore
This structure MUST include the following fields:
This structure MAY include the following fields:
The Beacon Key that is stored in the Keystore.
The beacon key is optional, because the beacon key is used to derive HMAC Keys. Once this has been complete, the beacon key can be discarded.
The custom encryption context associated with this beacon key.
The Beacon key id that was used to obtain the beacon key from a Keystore
A key-value mapping of arbitrary strings to bytes. Where the string is the name of the beacon and the bytes are the HMAC Key derived from the beacon key concatenated with the UTF8 Encoding of the beacon name.