AwsEncryptionSdk.Format.Body (AWS Encryption SDK v1.0.0)

View Source

Message 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

Types

final_frame()

Final frame structure

frame()

Any frame type

non_framed()

Non-framed body structure

regular_frame()

Regular frame structure

Functions

deserialize_all_frames(data, frame_length)

Deserializes all frames from a framed body.

deserialize_frame(arg1, frame_length)

Deserializes a frame (regular or final).

deserialize_non_framed(arg1)

Deserializes a non-framed body.

serialize_final_frame(sequence_number, iv, ciphertext, auth_tag)

Serializes a final frame.

serialize_non_framed(iv, ciphertext, auth_tag)

Serializes a non-framed body.

serialize_regular_frame(sequence_number, iv, ciphertext, auth_tag)

Serializes a regular frame.

Types

final_frame()

@type final_frame() :: %{
  sequence_number: pos_integer(),
  iv: binary(),
  ciphertext: binary(),
  auth_tag: binary(),
  final: true
}

Final frame structure

frame()

@type frame() :: regular_frame() | final_frame()

Any frame type

non_framed()

@type non_framed() :: %{iv: binary(), ciphertext: binary(), auth_tag: binary()}

Non-framed body structure

regular_frame()

@type regular_frame() :: %{
  sequence_number: pos_integer(),
  iv: binary(),
  ciphertext: binary(),
  auth_tag: binary()
}

Regular frame structure

Functions

deserialize_all_frames(data, frame_length)

@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.

deserialize_frame(arg1, frame_length)

@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.

deserialize_non_framed(arg1)

@spec deserialize_non_framed(binary()) ::
  {:ok, non_framed(), binary()} | {:error, term()}

Deserializes a non-framed body.

Returns {:ok, body_map, rest} on success.

serialize_final_frame(sequence_number, iv, ciphertext, auth_tag)

@spec serialize_final_frame(pos_integer(), binary(), binary(), binary()) :: binary()

Serializes a final frame.

Parameters

  • sequence_number - Frame sequence number
  • iv - 12-byte initialization vector
  • ciphertext - Encrypted content (may be shorter than frame_length)
  • auth_tag - 16-byte authentication tag

serialize_non_framed(iv, ciphertext, auth_tag)

@spec serialize_non_framed(binary(), binary(), binary()) ::
  {:ok, binary()} | {:error, :content_too_large}

Serializes a non-framed body.

Parameters

  • iv - 12-byte initialization vector
  • ciphertext - Encrypted content
  • auth_tag - 16-byte authentication tag

Returns

{:ok, binary} on success, {:error, reason} if content exceeds 64 GiB limit.

serialize_regular_frame(sequence_number, iv, ciphertext, auth_tag)

@spec serialize_regular_frame(pos_integer(), binary(), binary(), binary()) :: binary()

Serializes a regular frame.

Parameters

  • sequence_number - Frame sequence (1, 2, 3, ...)
  • iv - 12-byte initialization vector
  • ciphertext - Encrypted content (must be exactly frame_length bytes)
  • auth_tag - 16-byte authentication tag