0.1.0-preview
This document describes the behavior by which a plaintext is encrypted and serialized into a message.
Any client provided by the AWS Encryption SDK that performs encryption of user plaintext MUST follow this specification for encryption.
The following inputs to this behavior are REQUIRED:
- Plaintext
- either a Cryptographic Materials Manager (CMM) or a Keyring
The following as inputs to this behavior are OPTIONAL:
The plaintext to encrypt.
See encryption context.
The encryption context MUST NOT contain an entry with a reserved key value.
A CMM that implements the CMM interface.
A Keyring that implements the keyring interface.
The frame length to use for framed data. This value MUST NOT exceed the value 2^32 - 1.
A bound on the length of the plaintext to encrypt.
This behavior MUST output the following if the behavior is successful:
This behavior MAY output the following:
To construct the outputs, some fields MUST be constructed using information obtained from a set of valid encryption materials. This behavior MUST obtain this set of encryption materials by calling Get Encryption Materials on a CMM. The CMM used MUST be the input CMM, if supplied. If instead the user supplied a keyring, this behavior MUST use a default CMM, constructed using the user supplied keyring as input. The call to Get Encryption Materials MUST include the input encryption context, if supplied. If the length is known on the input plaintext, this call MUST also include that value
The algorithm suite used in all aspects of this behavior MUST be the algorithm suite in the encryption materials returned from the Get Encryption Materials call.
The data key used as input for all encryption described below is a data key derived from the plaintext data key included in the encryption materials. The algorithm used to derive a data key from the plaintext data key MUST be the key derivation algorithm included in the algorithm suite defined above. This document refers to the output of the key derivation algorithm as the derived data key. Note that if the key derivation algorithm is the identity KDF, then the derived data key is the same as the plaintext data key.
The output message MUST be bytes, as specified by the message format.
The message header is serialized with the following specifics:
- Version: MUST have a value corresponding to 1.0
- Type: MUST have a value corresponding to Customer Authenticated Encrypted Data
- Algorithm Suite ID: MUST be the algorithm suite used in this behavior
- AAD: MUST be the serialization of the encryption context in the encryption materials
- Encrypted Data Keys: MUST be the serialization of the encrypted data keys in the encryption materials
- Content Type: MUST be 02
- IV Length: MUST match the IV length specified by the algorithm suite
- Frame Length: MUST be the same value as the input frame length, if included.
- IV: MUST have a value of 0, padded to the IV length.
- Authentication Tag: MUST be the output of the
authenticated encryption algorithm
specified by the algorithm suite, with the following inputs:
- The AAD is the serialized message header body
- The IV is the IV specified above
- The cipherkey is the derived data key
- The plaintext is an empty byte array
Each frame of the message body is serialized with the following specifics:
- IV: MUST be the sequence number used in the message body AAD for this frame.
- Encrypted Content: MUST be the output of the authenticated encryption algorithm
specified by the algorithm suite, with the following inputs:
- The AAD is the serialized message body AAD
- The IV is the IV specified for this frame above.
- The cipherkey is the derived data key
- The plaintext contains part of the input plaintext this frame is encrypting.
- Authentication Tag: MUST be the authentication tag outputted by the above encryption.
If the algorithm suite contains a signature algorithm, the output message MUST contain a message footer. The footer is serialized with the following specifics:
- Signature: MUST be the output of the signature algorithm
specified by the algorithm suite, with the following input:
- the signature key is the signing key in the encryption materials
- the input to sign is the concatenation of the serialization of the message header and message body
Any data that is not specified within the message format MUST NOT be added to the output message.
The keyring trace obtained from the encryption materials.
[TODO]
TODO: Implementations SHOULD support working with a finite amount of working memory for arbitrarly large plaintext. If size is not known, how do we set the bounds?
Implementations of the AWS Encryption SDK MUST NOT encrypt using the Non-Framed content type. However, this behavior was supported in the past.
If a message has the non-framed content type, the message body was serialized with the following specifics:
- IV: MUST be the sequence number used in the message body AAD.
- Encrypted Content: MUST be the output of the authenticated encryption algorithm
specified by the algorithm suite, with the following inputs:
- The AAD is the serialized message body AAD
- The IV is the IV specified above.
- The cipherkey is the derived data key
- The plaintext is the input plaintext
- Authentication Tag: MUST be the authentication tag outputted by the above encryption.