0.1.0-preview
This document describes the behavior of decrypting the encrypted message previously received from an encrypt call to the AWS Encryption SDK. The AWS Encryption SDK provides a client to decrypt the inputted encrypted message, and returns as the output the plaintext.
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 RFC2119.
The client MUST require the following as inputs to this behavior:
The client MUST require exactly one of the following type of inputs:
The client SHOULD also provide a way to limit memory usage, such that you can decrypt an arbitrary long ciphertext using limited memory.
The encrypted message to decrypt.
The encrypted message inputted MUST be in the message format specified by the AWS Encryption SDK.
The encrypted message contains the list of encrypted data keys,
encryption context, if provided during encryption,
encrypted content and
algorithm suite ID among other metadata.
Each key in the encrypted data key list is an encrypted version of the single plaintext data key that was used to encrypt the plaintext.
The encryption context is the additional authenticated data that was used during encryption.
The algorithm suite ID refers to the algorithm suite used to encrypt the message and is required to decrypt the encrypted message.
A CMM that implements the CMM interface.
This CMM MUST obtain the decryption materials required for decryption.
A Keyring that implements the keyring interface.
If the Keyring is provided as the input, the client MUST construct a default CMM that uses this keyring, to obtain the decryption materials that is required for decryption.
This default CMM MUST obtain the decryption materials required for decryption.
The client MUST return as output to this behavior:
The decrypted data.
To obtain the decrypted data, a set of valid decryption materials is required.
This behavior MUST obtain this set of decryption materials, by calling Decrypt Materials on a CMM.
The CMM used MUST be the input CMM, if supplied. If a CMM is not supplied as the input, the decrypt behavior MUST construct a default CMM from the keyring inputted.
The call to CMM's Decrypt Materials behavior MUST include as the input the encryption context, if provided, the encrypted data keys and the algorithm suite ID, obtained from parsing the message header of the encrypted message inputted.
The decryption materials returned by the call to the CMM's Decrypt Materials behaviour MUST contain a valid
plaintext data key,
algorithm suite and an
encryption context, if an encryption context was used during encryption.
Note: This encryption context MUST be the same encryption context that was used during encryption otherwise the decrypt operation will fail.
The decrypt behavior MUST then use this plaintext data key, algorithm suite and encryption context, if included, to decrypt the encrypted content and obtain the plaintext to be returned. The encrypted content to be decrypted is obtained by parsing the message body of the encrypted message inputted.
Note: If the message is framed, the encrypted content to decrypt is stored across multiple frames.
If the message is non framed, the encrypted content to decrypt is stored as a single blob.
Decrypt MUST use the encryption algorithm obtained from the algorithm suite.
The cipher key used for decryption is the derived key outputted by the KDF algorithm
specified by the algorithm suite.
The input to the KDF algorithm is the plaintext data key.
The AAD used in decryption is the Message Body AAD, constructed as follows:
- Message ID: This value is the same as the message ID in the parsed message header.
- Body AAD Content: This value depends on whether the encrypted content being decrypted is within a regular frame , a final frame or is non framed. Refer to Message Body AAD specification for more information.
- Sequence Number: This value is the sequence number of the frame being decrypted, if the message contains framed data. If the message contains non framed data, then this value is 1.
- Content Length: TODO
If the algorithm suite has a signature algorithm, decrypt MUST verify the message footer using the specified signature algorithm, by using the verification key obtained from the decryption 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?]