AwsEncryptionSdk.Format.Body (AWS Encryption SDK v1.2.2)
View SourceMessage body serialization and deserialization.
Supports both framed and non-framed body formats.
Non-Framed Format
| Field | Size |
|-----------------|-----------|
| IV | 12 bytes |
| Content Length | 8 bytes | Uint64
| Ciphertext | Variable |
| Auth Tag | 16 bytes |Framed Format
Regular frames:
| Field | Size |
|-----------------|-----------|
| Sequence Number | 4 bytes | Uint32 (1, 2, 3, ...)
| IV | 12 bytes |
| Ciphertext | frame_length bytes |
| Auth Tag | 16 bytes |Final frame:
| Field | Size |
|-----------------|-----------|
| Seq Number End | 4 bytes | 0xFFFFFFFF
| Sequence Number | 4 bytes | Actual sequence number
| IV | 12 bytes |
| Content Length | 4 bytes | Uint32
| Ciphertext | Variable |
| Auth Tag | 16 bytes |Summary
Functions
Checks a message's frame count against the specification's limit of 2^32 - 1 frames.
Deserializes all frames from a framed body.
Deserializes a frame (regular or final).
Deserializes a non-framed body.
Returns the number of frames a framed body holds for plaintext_length
bytes split into frames of frame_length bytes.
Serializes a final frame.
Serializes a non-framed body.
Serializes a regular frame.
Types
@type final_frame() :: %{ sequence_number: pos_integer(), iv: binary(), ciphertext: binary(), auth_tag: binary(), final: true }
Final frame structure
@type frame() :: regular_frame() | final_frame()
Any frame type
Non-framed body structure
@type regular_frame() :: %{ sequence_number: pos_integer(), iv: binary(), ciphertext: binary(), auth_tag: binary() }
Regular frame structure
Functions
@spec check_frame_count(pos_integer()) :: :ok | {:error, :max_frames_exceeded}
Checks a message's frame count against the specification's limit of 2^32 - 1 frames.
Returns :ok when a message of frame_count frames may be written, and
{:error, :max_frames_exceeded} when it would exceed the limit.
@spec deserialize_all_frames(binary(), pos_integer()) :: {:ok, [frame()], binary()} | {:error, term()}
Deserializes all frames from a framed body.
Returns {:ok, frames, rest} where frames is a list ordered by sequence number.
@spec deserialize_frame(binary(), pos_integer()) :: {:ok, frame(), binary()} | {:error, term()}
Deserializes a frame (regular or final).
Returns {:ok, frame_map, rest} where frame_map includes :final key for final frames.
@spec deserialize_non_framed(binary()) :: {:ok, non_framed(), binary()} | {:error, term()}
Deserializes a non-framed body.
Returns {:ok, body_map, rest} on success.
@spec frame_count(non_neg_integer(), pos_integer()) :: pos_integer()
Returns the number of frames a framed body holds for plaintext_length
bytes split into frames of frame_length bytes.
Every full frame but the last is a regular frame, and the remainder (or the
last full frame) is the final frame: an empty plaintext is one empty final
frame, and a plaintext of exactly n * frame_length bytes is n frames.
@spec serialize_final_frame(pos_integer(), binary(), binary(), binary()) :: binary()
Serializes a final frame.
Parameters
sequence_number- Frame sequence number, the message's frame count (at most 2^32 - 1)iv- 12-byte initialization vectorciphertext- Encrypted content (may be shorter than frame_length)auth_tag- 16-byte authentication tag
@spec serialize_non_framed(binary(), binary(), binary()) :: {:ok, binary()} | {:error, :content_too_large}
Serializes a non-framed body.
Parameters
iv- 12-byte initialization vectorciphertext- Encrypted contentauth_tag- 16-byte authentication tag
Returns
{:ok, binary} on success, {:error, reason} if content exceeds 64 GiB limit.
@spec serialize_regular_frame(pos_integer(), binary(), binary(), binary()) :: binary()
Serializes a regular frame.
Parameters
sequence_number- Frame sequence (1, 2, 3, ...), below 2^32 - 1: a final frame follows every regular frameiv- 12-byte initialization vectorciphertext- Encrypted content (must be exactly frame_length bytes)auth_tag- 16-byte authentication tag