Behaviour for envelope formats, and the dispatcher used to decode stored values.
An envelope is the self-describing wrapper written to the database. It carries everything needed to decrypt a value except the key itself: the format version, the cipher id, the key version, the nonce, the authentication tag and the ciphertext.
AshVault.Envelope is both the behaviour and the dispatcher. decode/1 peeks at the
version byte and routes to the matching implementation, so values written by older
builds keep decoding after the default envelope version changes.
See AshVault.Envelope.V1 for the current wire format.
Summary
Callbacks
Parse a binary into a decoded envelope map. Must never raise.
Serialize a decoded envelope map to its wire representation.
The version byte this implementation writes.
Functions
Decode a stored value by dispatching on its envelope version byte.
The magic prefix every AshVault envelope starts with.
The envelope implementation for a version byte, if this build knows it.
Types
@type decoded() :: %{ version: pos_integer(), cipher: binary(), key_version: non_neg_integer(), nonce: binary(), tag: binary(), ciphertext: binary() }
Callbacks
@callback decode(binary()) :: {:ok, map()} | {:error, Exception.t()}
Parse a binary into a decoded envelope map. Must never raise.
Serialize a decoded envelope map to its wire representation.
@callback version() :: pos_integer()
The version byte this implementation writes.
Functions
@spec decode(binary()) :: {:ok, decoded()} | {:error, Exception.t()}
Decode a stored value by dispatching on its envelope version byte.
This function is total: any binary (or indeed any term) produces a tagged tuple, never an exception.
Returns {:error, %AshVault.Errors.UnsupportedEnvelope{}} for a well-formed magic with
an unknown version, and {:error, %AshVault.Errors.InvalidCiphertext{}} for anything
that is not an AshVault envelope at all.
@spec magic() :: binary()
The magic prefix every AshVault envelope starts with.
The envelope implementation for a version byte, if this build knows it.