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

The header stores the materials' encryption context minus every key in the materials' required encryption context keys: those pairs are only authenticated (as the tail of the header-authentication AAD, see compute_header_auth_tag/4), never stored. Messages written before 1.1.0 stored them as well; AwsEncryptionSdk.Cmm.RequiredEncryptionContext still reads that form.

@spec compute_header_auth_tag(AwsEncryptionSdk.Format.Header.t(), binary()) ::
  {:ok, AwsEncryptionSdk.Format.Header.t()}

Deprecated: the compute_header_auth_tag/2 arity takes the required pairs from the header's stored encryption context, which no longer holds them. Use compute_header_auth_tag/4, which takes the full encryption context and the required keys. Kept, not removed; removal waits for a major release.

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

Deprecated: the compute_header_auth_tag/3 arity takes the required pairs from the header's stored encryption context, which no longer holds them. Use compute_header_auth_tag/4, which takes the full encryption context and the required keys. Kept, not removed; removal waits for a major release.

@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 (may be [])

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.

@spec verify_header_auth_tag(AwsEncryptionSdk.Format.Header.t(), binary()) ::
  :ok | {:error, term()}

Deprecated: the verify_header_auth_tag/2 arity takes the required pairs from the header's stored encryption context, which no longer holds them. Use verify_header_auth_tag/4, which takes the full encryption context and the required keys. Kept, not removed; removal waits for a major release.

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

Deprecated: the verify_header_auth_tag/3 arity takes the required pairs from the header's stored encryption context, which no longer holds them. Use verify_header_auth_tag/4, which takes the full encryption context and the required keys. Kept, not removed; removal waits for a major release.

@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 (may be [])

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.