@spec canonical_keys() :: [String.t()]

The six canonical host-facing keys, in the order ADR-0004 decision 2 tables them.

iex> Encryptor.Context.canonical_keys()
["tenant_ref", "table", "column", "blob", "purpose", "app"]

@spec compose(Encryptor.Vault.Config.t(), term(), keyword()) ::
  {:ok, context()} | {:error, Encryptor.Error.t()}

Composes the four layers into the context a message will carry.

config supplies the static layer and the profile. per_call is the caller's :encryption_context. The two upper layers arrive as options, because both are the vault's own and neither is ever a caller's to pass:

• :supplied - keys the vault derives from the call's own arguments, which today is tenant_ref on a :tenant vault. Defaults to %{}.
• :reserved - encryptor-* pairs this package sets on its own messages, which is how Encryptor.Envelope marks a wrapped key. Defaults to %{}.
• :operation - what to record on a failure. Defaults to :encrypt.

A caller key that collides with either upper layer is refused rather than overridden, which is the whole reason they are separate arguments and not a pre-merged map.

iex> config = %Encryptor.Vault.Config{
...>   vault: MyApp.Vault,
...>   context_profile: :single,
...>   static_encryption_context: %{"app" => "my_app"}
...> }
iex> Encryptor.Context.compose(config, %{"table" => "customers"})
{:ok, %{"app" => "my_app", "table" => "customers"}}

iex> config = %Encryptor.Vault.Config{
...>   vault: MyApp.Vault,
...>   context_profile: :tenant,
...>   static_encryption_context: %{}
...> }
iex> {:error, error} = Encryptor.Context.compose(config, %{"tenant_ref" => "mine"})
iex> error.reason
{:reserved_context_key, "tenant_ref"}

@spec max_bytes() :: pos_integer()

The most bytes a composed context may serialize to.

iex> Encryptor.Context.max_bytes()
4096

@spec max_pairs() :: pos_integer()

The most pairs a composed context may carry.

iex> Encryptor.Context.max_pairs()
32

@spec reserved_key?(String.t(), Encryptor.Vault.Config.profile()) :: boolean()

Whether a key is refused from a caller or from static configuration on a vault of this profile.

Both reserved prefixes are refused on either profile. The tenant pair is profile-sensitive: tenant_ref is the vault's on a :tenant vault and meaningless on a :single one, so it is refused on both; tenant_id is refused only where a tenant exists to be named twice.

iex> Encryptor.Context.reserved_key?("aws-crypto-public-key", :single)
true

iex> Encryptor.Context.reserved_key?("tenant_ref", :single)
true

iex> Encryptor.Context.reserved_key?("tenant_id", :tenant)
true

iex> Encryptor.Context.reserved_key?("tenant_id", :single)
false

iex> Encryptor.Context.reserved_key?("table", :tenant)
false

@spec reserved_prefixes() :: [String.t()]

The prefixes no host key may start with.

aws-crypto- is the engine's, and the engine is of two minds about it: Format.EncryptionContext.validate/1 refuses the whole prefix, while Cmm.Behaviour.validate_encryption_context_for_encrypt/1 refuses exactly "aws-crypto-public-key", the one key it uses today. This package refuses the prefix, on the stricter of the two readings, because a later engine version may put another reserved key under it and a host that has been writing one is then unable to encrypt.

iex> Encryptor.Context.reserved_prefixes()
["aws-crypto-", "encryptor-"]

@spec serialized_size(pairs()) :: non_neg_integer()

The size the engine serializes a context to, in bytes.

A non-empty context is a 16-bit pair count followed by one entry per pair, each a 16-bit length prefix and the bytes of the key then the same for the value. An empty context serializes to nothing at all - not to a zero-valued count - which is Format.EncryptionContext.serialize/1's own first clause and the reason this is not simply 2 + entries.

Computed arithmetically rather than by calling the engine's serializer, so a size check does not become a second place this package depends on the message format.

iex> Encryptor.Context.serialized_size(%{})
0

iex> Encryptor.Context.serialized_size(%{"app" => "my_app"})
15

@spec tenant_ref_key() :: String.t()

The key the vault writes a tenant reference under.

iex> Encryptor.Context.tenant_ref_key()
"tenant_ref"

@spec valid_string?(term()) :: boolean()

Whether a term is usable as a context key or value: a non-empty binary that is valid UTF-8.

iex> Encryptor.Context.valid_string?("customers")
true

iex> Encryptor.Context.valid_string?("")
false

iex> Encryptor.Context.valid_string?(:customers)
false