The MAC half of AshVault.KeyProviders.OpenBaoTransit: HMAC-SHA256 computed inside
OpenBao, so the :mac key never enters the BEAM.
mac/3 is one transit/hmac/<name>/sha2-256 call and verify/4 one
transit/verify/<name>/sha2-256 call, both pinned to the handle's key version. The
algorithm is in the path rather than left to the server's default, so a default that
changed under an upgrade could not silently change every tag.
Same frame, same tag as AshVault.Macs.HmacSha256
Transit has no associated-data parameter, so the input sent is
AshVault.Mac.frame(data, aad) — exactly what AshVault.Macs.HmacSha256 HMACs. Transit
answers vault:v<N>:<base64>; mac/3 checks that N is the version it asked for and
returns the decoded 32 raw bytes. So for the same key bytes the two modules produce the
same tag, which test/ash_vault/macs/open_bao_transit_test.exs checks against a live
server by exporting an hmac key and comparing.
verify/4 rebuilds vault:v<N>:<base64(tag)> from the handle's version. Rebuilding the
prefix is safe here in a way it is not for ciphertext: the tag is a fixed 32-byte HMAC
whose wire form transit has never varied, and the version comes from the handle the
provider validated, not from the stored bytes.
Handles only
It accepts only a :mac handle from AshVault.KeyProviders.OpenBaoTransit
({:mac, name, version}). A data key handle is {:error, :opaque_key_unsupported},
and raw bytes are {:error, :requires_open_bao_transit_key_provider} — there is no
transit key name to invent for them.
Outage versus forgery
{:error, :invalid_tag} is returned only when transit answers 200 with
valid: false, or when the tag is not 32 bytes (refused before any round trip).
A 400 triggers an authoritative tombstone and key-metadata recheck: erasure returns
:destroyed, and a missing key or retired version returns {:key_not_found, version}.
The vault translates those into KeyDestroyed and KeyNotFound. A 403 is
ProviderForbidden; ambiguous responses and outages remain ProviderUnavailable.
Summary
Functions
Decode transit's vault:v<N>:<base64> HMAC into raw bytes, requiring N == version.
The stable id, :openbao_transit_hmac_sha256_v1.
The key size in bytes, 32. Nominal: this module never sees key bytes.
HMAC AshVault.Mac.frame(data, aad) through transit/hmac, returning 32 raw bytes.
Verify a tag through transit/verify. {:error, :invalid_tag} only for a tag transit
positively rejected, or one that is not 32 bytes.
Functions
@spec decode_tag(term(), pos_integer()) :: {:ok, binary()} | {:error, Exception.t()}
Decode transit's vault:v<N>:<base64> HMAC into raw bytes, requiring N == version.
Public so the parse can be tested without a server.
Examples
iex> AshVault.Macs.OpenBaoTransit.decode_tag("vault:v2:" <> Base.encode64(<<0::256>>), 2)
{:ok, <<0::256>>}
@spec id() :: :openbao_transit_hmac_sha256_v1
The stable id, :openbao_transit_hmac_sha256_v1.
@spec key_bytes() :: pos_integer()
The key size in bytes, 32. Nominal: this module never sees key bytes.
@spec mac(binary(), AshVault.Key.t(), binary()) :: {:ok, binary()} | {:error, term()}
HMAC AshVault.Mac.frame(data, aad) through transit/hmac, returning 32 raw bytes.
@spec verify(binary(), binary(), AshVault.Key.t(), binary()) :: :ok | {:error, :invalid_tag} | {:error, term()}
Verify a tag through transit/verify. {:error, :invalid_tag} only for a tag transit
positively rejected, or one that is not 32 bytes.