AshVault.Mac behaviour (AshVault v0.2.0)

Copy Markdown View Source

Behaviour for message authentication codes: the sibling of AshVault.Cipher for data that must be authenticated rather than hidden.

A MAC is computed under a scope's :mac key — a keyring of its own, minted, rotated and destroyed by the vault's key provider alongside the :data keyring the cipher uses, but never the same key and never derived from it. See Key purposes and MACs.

Two implementations ship:

The frame

Both compute HMAC-SHA256 over the same frozen byte string, built by frame/2:

"ashvault:mac:v1|" <> <<byte_size(aad)::unsigned-big-64>> <> aad <> data

The associated data is length-prefixed, so no (aad, data) pair can be re-split into another pair with the same bytes, and the domain prefix keeps a MAC computed here from ever equalling an HMAC some other part of an application computed under the same key. OpenBao's transit/hmac has no associated-data parameter, which is why the binding is done in the frame and not left to the backend: framing it identically in both implementations is what makes a tag from one verifiable by the other for the same key.

Tags are raw bytes

mac/3 returns the raw 32-byte HMAC output, never a hex or vault:v1: string. A tag is something later layers build on — a macaroon's signature chain HMACs each caveat under the previous signature — so it must be usable as key material itself.

A tag is also a bearer credential. Implementations must not put it, the data, or the key into an error, a log line or telemetry.

Error conventions

The same as AshVault.Cipher, so AshVault.Vault.Runtime classifies both alike:

verify/4 additionally returns {:error, :invalid_tag} — and only for a tag that positively failed verification. That is the one answer reported as AshVault.Errors.InvalidMac; an outage must never be reported as a forgery, nor a forgery as an outage.

Summary

Callbacks

The stable identifier of this MAC construction.

The exact key size, in bytes, this MAC requires.

Compute a tag over data, bound to aad, under key.

Verify tag over data and aad under key.

Functions

The frozen byte string every shipped MAC authenticates.

Callbacks

id()

@callback id() :: atom()

The stable identifier of this MAC construction.

key_bytes()

@callback key_bytes() :: pos_integer()

The exact key size, in bytes, this MAC requires.

mac(data, key, aad)

@callback mac(data :: binary(), key :: AshVault.Key.t(), aad :: binary()) ::
  {:ok, binary()} | {:error, term()}

Compute a tag over data, bound to aad, under key.

key is an AshVault.Key.t(): raw bytes, or an opaque handle for a MAC that runs where the key lives.

verify(data, tag, key, aad)

@callback verify(
  data :: binary(),
  tag :: binary(),
  key :: AshVault.Key.t(),
  aad :: binary()
) ::
  :ok | {:error, :invalid_tag} | {:error, term()}

Verify tag over data and aad under key.

Returns {:error, :invalid_tag} only for a tag that does not verify. Implementations must compare in constant time.

Functions

frame(data, aad)

@spec frame(binary(), binary()) :: binary()

The frozen byte string every shipped MAC authenticates.

Examples

iex> AshVault.Mac.frame("payload", "aad")
"ashvault:mac:v1|" <> <<3::64>> <> "aad" <> "payload"

iex> AshVault.Mac.frame("ab", "c") == AshVault.Mac.frame("b", "ca")
false