aws_encryption_sdk.internal.crypto.iv

Helper functions used for generating deterministic initialization vectors (IVs).

Deterministic IVs are used to reduce the probability of IV/message-key pair collisions when caching data keys.

Prior to introducing caching, a statement could safely be made that every encrypt call resulted in a new data key which would only be used with a single message. With the introduction of caching, this statement by definition becomes false.

This is a problem because there are cryptographic limits on the number of times AES can be safely invoked using the same key (or using keys derived from the same key) and a random IV. In framed messages, this manifests as the total number of frames which can be safely encrypted under the same data key across all messages for which the data key is reused.

By using a random IV for each frame, we actually decrease the number of frames which can be safely encrypted under the same data key. Rather than attempting to track the number of frames across messages, we decided to move to a deterministic IV constructed in such a way that it is guaranteed to never conflict within the same message. This means that we can consider only the likelihood of KDF collisions, which raises the limit sufficiently that we can assume that every message contains the maximum 2^32 invocations (2^32 - 1 frames + header auth).

Each IV is constructed from two big-endian byte arrays concatenated in the following order:

  1. 64 bytes : 0 (reserved space for possible future use)

  2. 32 bytes : frame sequence number (0 for the header auth calculation)

Functions

frame_iv(algorithm, sequence_number)

Builds the deterministic IV for a body frame.

header_auth_iv(algorithm)

Builds the deterministic IV for header authentication.

non_framed_body_iv(algorithm)

Builds the deterministic IV for a non-framed body.

aws_encryption_sdk.internal.crypto.iv.frame_iv(algorithm, sequence_number)

Builds the deterministic IV for a body frame.

Parameters
  • algorithm (aws_encryption_sdk.identifiers.Algorithm) – Algorithm for which to build IV

  • sequence_number (int) – Frame sequence number

Returns

Generated IV

Return type

bytes

Raises

ActionNotAllowedError – if sequence number of out bounds

aws_encryption_sdk.internal.crypto.iv.non_framed_body_iv(algorithm)

Builds the deterministic IV for a non-framed body.

Parameters

algorithm (aws_encryption_sdk.identifiers.Algorithm) – Algorithm for which to build IV

Returns

Generated IV

Return type

bytes

aws_encryption_sdk.internal.crypto.iv.header_auth_iv(algorithm)

Builds the deterministic IV for header authentication.

Parameters

algorithm (aws_encryption_sdk.identifiers.Algorithm) – Algorithm for which to build IV

Returns

Generated IV

Return type

bytes