AwsEncryptionSdk.Crypto.HeaderAuth (AWS Encryption SDK v1.0.0)

View Source

Header authentication operations shared between encryption and decryption.

Handles header construction and authentication tag computation/verification for both streaming and non-streaming operations.

Summary

Functions

build_header(materials, message_id, frame_length, commitment_key)

Builds a header struct (without auth tag) from encryption materials.

compute_header_auth_tag(header, derived_key, full_ec_or_required_keys \\ [], required_ec_keys_opt \\ nil)

Computes the header authentication tag.

verify_header_auth_tag(header, derived_key, full_ec_or_required_keys \\ [], required_ec_keys_opt \\ nil)

Verifies the header authentication tag.

Functions

build_header(materials, message_id, frame_length, commitment_key)

@spec build_header(
  AwsEncryptionSdk.Materials.EncryptionMaterials.t(),
  binary(),
  pos_integer(),
  binary() | nil
) :: {:ok, AwsEncryptionSdk.Format.Header.t()}

Builds a header struct (without auth tag) from encryption materials.

Returns a header with a placeholder auth tag that must be computed separately.

compute_header_auth_tag(header, derived_key, full_ec_or_required_keys \\ [], required_ec_keys_opt \\ nil)

@spec compute_header_auth_tag(
  AwsEncryptionSdk.Format.Header.t(),
  binary(),
  map() | [String.t()],
  [String.t()] | nil
) :: {:ok, AwsEncryptionSdk.Format.Header.t()}

Computes the header authentication tag.

Returns a new header with the computed authentication tag.

Parameters

  • header - The message header
  • derived_key - The derived data encryption key
  • full_encryption_context - The complete encryption context (stored + required keys)
  • required_ec_keys - List of required encryption context keys (defaults to empty list)

Per the spec, the AAD is: header_body || required_encryption_context_bytes where required_encryption_context_bytes is the serialization of only the encryption context keys in the required_ec_keys list from the full EC.

verify_header_auth_tag(header, derived_key, full_ec_or_required_keys \\ [], required_ec_keys_opt \\ nil)

@spec verify_header_auth_tag(
  AwsEncryptionSdk.Format.Header.t(),
  binary(),
  map() | [String.t()],
  [String.t()] | nil
) :: :ok | {:error, term()}

Verifies the header authentication tag.

Returns :ok if verification succeeds, {:error, reason} otherwise.

Parameters

  • header - The message header
  • derived_key - The derived data encryption key
  • full_encryption_context - The complete encryption context (stored + required keys)
  • required_ec_keys - List of required encryption context keys (defaults to empty list)

Per the spec, the AAD is: header_body || required_encryption_context_bytes where required_encryption_context_bytes is the serialization of only the encryption context keys in the required_ec_keys list from the full EC.