AwsEncryptionSdk.Format.EncryptionContext (AWS Encryption SDK v0.7.0)

View Source

Encryption context serialization and validation.

The encryption context is a key-value mapping of arbitrary, non-secret, UTF-8 encoded strings used as Additional Authenticated Data (AAD).

Serialization Format

Per structures.md:

  • Empty context: empty byte sequence (0 bytes)
  • Non-empty context:
    <<count::16-big, entry1::binary, entry2::binary, ...>>
  • Each entry:
    <<key_len::16-big, key::binary, value_len::16-big, value::binary>>
  • Entries MUST be sorted ascending by UTF-8 encoded key bytes

Reserved Keys

The prefix aws-crypto- is reserved for internal SDK use. User-provided encryption context MUST NOT contain keys with this prefix.

Summary

Types

t()

Encryption context map

Functions

deserialize(arg1)

Deserializes an encryption context from binary format.

serialize(context)

Serializes an encryption context to binary format.

validate(context)

Validates that user-provided encryption context does not contain reserved keys.

Types

t()

@type t() :: %{required(String.t()) => String.t()}

Encryption context map

Functions

deserialize(arg1)

@spec deserialize(binary()) :: {:ok, t(), binary()} | {:error, term()}

Deserializes an encryption context from binary format.

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

Examples

iex> AwsEncryptionSdk.Format.EncryptionContext.deserialize(<<>>)
{:ok, %{}, <<>>}

serialize(context)

@spec serialize(t()) :: binary()

Serializes an encryption context to binary format.

Empty maps produce an empty binary. Non-empty maps produce a count-prefixed sequence of key-value entries, sorted by key.

Examples

iex> AwsEncryptionSdk.Format.EncryptionContext.serialize(%{})
<<>>

iex> AwsEncryptionSdk.Format.EncryptionContext.serialize(%{"a" => "1"})
<<0, 1, 0, 1, ?a, 0, 1, ?1>>

validate(context)

@spec validate(t()) :: :ok | {:error, {:reserved_keys, [String.t()]}}

Validates that user-provided encryption context does not contain reserved keys.

Returns :ok if valid, or {:error, {:reserved_keys, keys}} if reserved keys found.

Examples

iex> AwsEncryptionSdk.Format.EncryptionContext.validate(%{"user-key" => "value"})
:ok

iex> AwsEncryptionSdk.Format.EncryptionContext.validate(%{"aws-crypto-public-key" => "value"})
{:error, {:reserved_keys, ["aws-crypto-public-key"]}}