AshVault.Macs.OpenBaoTransit (AshVault v0.2.0)

Copy Markdown View Source

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

decode_tag(arg1, version)

@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>>}

id()

@spec id() :: :openbao_transit_hmac_sha256_v1

The stable id, :openbao_transit_hmac_sha256_v1.

key_bytes()

@spec key_bytes() :: pos_integer()

The key size in bytes, 32. Nominal: this module never sees key bytes.

mac(data, key, aad)

@spec mac(binary(), AshVault.Key.t(), binary()) :: {:ok, binary()} | {:error, term()}

HMAC AshVault.Mac.frame(data, aad) through transit/hmac, returning 32 raw bytes.

verify(data, tag, key, aad)

@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.