Skip to content

Latest commit

 

History

History
467 lines (349 loc) · 27.4 KB

encrypt.md

File metadata and controls

467 lines (349 loc) · 27.4 KB

Encrypt

Version

0.5.0

Changelog

Implementations

Language Confirmed Compatible with Spec Version Minimum Version Confirmed Implementation
C 0.1.0-preview 0.1.0 session_encrypt.c
NodeJS 0.1.0-preview 0.1.0 encrypt.ts
Browser JS 0.1.0-preview 0.1.0 encrypt.ts
Python 0.1.0-preview 1.2.0 streaming_client.py
Java 0.1.0-preview 0.0.1 EncryptionHandler.java

Overview

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 caller plaintext MUST follow this specification for encryption.

Input

The following inputs to this behavior are REQUIRED:

The following inputs to this behavior MUST be OPTIONAL:

If the plaintext is of unknown length, the caller MAY also input a Plaintext Length Bound.

Implementations SHOULD ensure that a caller is not able to specify both a plaintext with known length and a Plaintext Length Bound by construction. If a caller is able to specify both an input plaintext with known length and a Plaintext Length Bound, the Plaintext Length Bound MUST NOT be used during the Encrypt operation and MUST be ignored.

Plaintext

The plaintext to encrypt. This MUST be a sequence of bytes.

This input MAY be streamed to this operation.

If an implementation requires holding the input entire plaintext in memory in order to perform this operation, that implementation SHOULD NOT provide an API that allows this input to be streamed.

Encryption Context

See encryption context.

The prefix aws-crypto- is reserved for internal use by the AWS Encryption SDK; see the the Default CMM spec for one such use. If the input encryption context contains any entries with a key beginning with this prefix, the encryption operation MUST fail.

CMM

A CMM that implements the CMM interface.

Keyring

A Keyring that implements the keyring interface.

Algorithm Suite

The algorithm suite that SHOULD be used for encryption. This algorithm suite MUST be supported for the ESDK.

Frame Length

The frame length to use for framed data. This value MUST be greater than 0 and MUST NOT exceed the value 2^32 - 1. This value MUST default to 4096 bytes.

Plaintext Length Bound

A bound on the length of plaintext with an unknown length to encrypt.

If this input is provided, this operation MUST NOT encrypt a plaintext with length greater than this value.

Output

This behavior MUST output the following if the behavior is successful:

The client SHOULD return as an output:

Encrypted Message

An encrypted form of the input plaintext , encrypted according to the behavior specified below. This MUST be a sequence of bytes and conform to the message format specification.

This operation MAY stream the encrypted message.

If an implementation requires holding the entire input plaintext in memory in order to perform this operation, that implementation SHOULD NOT provide an API that allows this output to be streamed.

Encryption Context

The encryption context that is used as additional authenticated data during the encryption of the input plaintext .

This output MAY be satisfied by outputting a parsed header containing this value.

Algorithm Suite

The algorithm suite that is used to encrypt the input plaintext .

This algorithm suite MUST be supported for the ESDK.

This output MAY be satisfied by outputting a parsed header containing this value.

Parsed Header

A collection of deserialized fields of the encrypted message's header.

Behavior

The Encrypt operation is divided into several distinct steps:

This operation MUST perform all the above steps unless otherwise specified, and it MUST perform them in the above order.

These steps calculate and serialize the components of the output encrypted message. Any data that is not specified within the message format MUST NOT be added to the output message.

If any of these steps fails, this operation MUST halt and indicate a failure to the caller.

Get the encryption materials

If an input algorithm suite is provided that is not supported by the commitment policy configured in the client encrypt MUST yield an error.

To construct the encrypted message, some fields MUST be constructed using information obtained from a set of valid encryption materials. This operation 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 caller supplied a keyring, this behavior MUST use a default CMM constructed using the caller-supplied keyring as input. The call to Get Encryption Materials on that CMM MUST be constructed as follows:

The algorithm suite used in all aspects of this operation MUST be the algorithm suite in the encryption materials returned from the Get Encryption Materials call. Note that the algorithm suite in the retrieved encryption materials MAY be different from the input algorithm suite. If this algorithm suite is not supported for the ESDK encrypt MUST yield an error. If this algorithm suite is not supported by the commitment policy configured in the client encrypt MUST yield an error. If the number of encrypted data keys on the encryption materials is greater than the maximum number of encrypted data keys configured in the client encrypt MUST yield an error.

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 frame length used in the procedures described below is the input frame length, if supplied, or the default if not.

Construct the header

Before encrypting input plaintext, this operation MUST serialize the message header body. The message format version MUST be associated with the algorithm suite.

If the message format version associated with the algorithm suite is 2.0 then the message header body MUST be serialized with the following specifics:

If the message format version associated with the algorithm suite is 1.0 then the message header body MUST be serialized with the following specifics:

After serializing the message header body, this operation MUST calculate an authentication tag over the message header body. The value of this MUST be the output of the authenticated encryption algorithm specified by the algorithm suite, with the following inputs:

With the authentication tag calculated, if the message format version associated with the algorithm suite is 2.0, this operation MUST serialize the message header authentication with the following specifics:

If the message format version associated with the algorithm suite is 1.0 this operation MUST serialize the message header authentication with the following specifics:

  • IV: MUST have the value of the IV used in the calculation above, padded to the IV length with 0.
  • Authentication Tag: MUST have the value of the authentication tag calculated above.

The serialized bytes MUST NOT be released until the entire message header has been serialized If this operation is streaming the encrypted message and the entire message header has been serialized, the serialized message header SHOULD be released.

The encrypted message output by this operation MUST have a message header equal to the message header calculated in this step.

If the algorithm suite contains a signature algorithm and this operation is streaming the encrypted message output to the caller, this operation MUST input the serialized header to the signature algorithm as soon as it is serialized, such that the serialized header isn't required to remain in memory to construct the signature.

Construct the body

The encrypted message output by this operation MUST have a message body equal to the message body calculated in this step.

If Plaintext Length Bound was specified on input and this operation determines at any time that the plaintext being encrypted has a length greater than this value, this operation MUST immediately fail.

Before the end of the input is indicated, this operation MUST process as much of the consumable bytes as possible by constructing regular frames.

When the end of the input is indicated, this operation MUST perform the following until all consumable plaintext bytes are processed:

  • If there are exactly enough consumable plaintext bytes to create one regular frame, such that creating a regular frame processes all consumable bytes, then this operation MUST construct either a final frame or regular frame with the remaining plaintext.
  • If there are enough input plaintext bytes consumable to create a new regular frame, such that creating a regular frame does not processes all consumable bytes, then this operation MUST construct a regular frame using the consumable plaintext bytes.
  • If there are not enough input consumable plaintext bytes to create a new regular frame, then this operation MUST construct a final frame

If an end to the input has been indicated, there are no more consumable plaintext bytes to process, and a final frame has not yet been constructed, this operation MUST construct an empty final frame.

Construct a frame

To construct a regular or final frame that represents the next frame in the encrypted message's body, this operation MUST calculate the encrypted content and an authentication tag using the authenticated encryption algorithm specified by the algorithm suite, with the following inputs:

  • The AAD is the serialized message body AAD, constructed as follows:
    • The message ID is the same as the message ID serialized in the header of this message.
    • The Body AAD Content depends on whether the thing being encrypted is a regular frame or final frame. Refer to Message Body AAD specification for more information.
    • The sequence number is the sequence number of the frame being encrypted. If this is the first frame sequentially, this value MUST be 1. Otherwise, this value MUST be 1 greater than the value of the sequence number of the previous frame.
    • The content length MUST have a value equal to the length of the plaintext being encrypted.
      • For a regular frame the length of this plaintext MUST equal the frame length.
      • For a final frame this MUST be the length of the remaining plaintext bytes which have not yet been encrypted, whose length MUST be equal to or less than the frame length.
  • The IV is the sequence number used in the message body AAD above, padded to the IV length.
  • The cipherkey is the derived data key
  • The plaintext is the next subsequence of consumable plaintext bytes that have not yet been encrypted.
    • For a regular frame the length of this plaintext subsequence MUST equal the frame length.
    • For a final frame this MUST be the remaining plaintext bytes which have not yet been encrypted, whose length MUST be equal to or less than the frame length.

This operation MUST serialize a regular frame or final frame with the following specifics:

  • Sequence Number: MUST be the sequence number of this frame, as determined above.
  • IV: MUST be the IV used when calculating the encrypted content above
  • Encrypted Content: MUST be the encrypted content calculated above.
  • Authentication Tag: MUST be the authentication tag output when calculating the encrypted content above.

The above serialized bytes MUST NOT be released until the entire frame has been serialized. If this operation is streaming the encrypted message and the entire frame has been serialized, the serialized frame SHOULD be released.

If the algorithm suite contains a signature algorithm and this operation is streaming the encrypted message output to the caller, this operation MUST input the serialized frame to the signature algorithm as soon as it is serialized, such that the serialized frame isn't required to remain in memory to construct the signature.

Construct the signature

If the algorithm suite contains a signature algorithm, this operation MUST calculate a signature over the message, and the output encrypted message MUST contain a message footer.

To calculate a signature, this operation MUST use the signature algorithm specified by the algorithm suite, with the following input:

Note that the message header and message body MAY have already been input during previous steps.

This operation MUST then serialize a message footer with the following specifics:

  • Signature Length: MUST be the length of the output of the calculation above.
  • Signature: MUST be the output of the calculation above.

The above serialized bytes MUST NOT be released until the entire message footer has been serialized. Once the entire message footer has been serialized, this operation MUST release any previously unreleased serialized bytes from previous steps and MUST release the message footer.

The encrypted message output by this operation MUST have a message footer equal to the message footer calculated in this step.

Appendix

Un-Framed Message Body Encryption

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:

Encryption Context not stored in the message

The encryption context to only authenticate is backwards compatible with older messages because the encryption context serialization specification will serialize an empty encryption context as 0 bytes.