The AEAD half of AshVault.KeyProviders.OpenBaoTransit: encryption and decryption
happen inside OpenBao, so no key material ever enters the BEAM.
Every other AshVault.Cipher is a local :crypto call over a key the provider handed
it. This one has no key. It receives an AshVault.Key handle naming a transit key and
a version, and turns each encrypt/3 and decrypt/3 into one HTTP call to
transit/encrypt / transit/decrypt.
One network round trip per value, here
This module contributes one call per encrypt/3 and one per decrypt/3. The value
costs three end to end: AshVault.KeyProviders.OpenBaoTransit reads the scope's
tombstone and the transit key's metadata before handing over the handle this module
uses. Measured, not estimated — see the [:finch, :request, :stop] counter in
test/ash_vault/ciphers/open_bao_transit_test.exs, and
AshVault.KeyProviders.OpenBaoTransit for when that trade is worth making.
AAD is real here, verified against the live server
transit/encrypt accepts associated_data, and OpenBao binds it into the GCM tag.
Verified against openbao 2.6.2: decrypting with different associated data, or with
none, returns 400 "cipher: message authentication failed". A control probe sending a
genuinely unrecognised parameter comes back with
warnings: ["Endpoint ignored these unrecognized parameters: [bogus_param]"], and
associated_data produces no such warning — so it is being consumed, not dropped.
The AAD is AshVault.Vault.Runtime.build_aad/2 verbatim, base64-encoded for the JSON
body. Cross-tenant, cross-resource and cross-field ciphertext substitution therefore
fail exactly as they do under AshVault.Ciphers.AES.GCM. This guarantee is not
weakened by moving the AEAD into OpenBao.
context (transit's key-derivation input) is deliberately not used: it only applies to
derived: true keys and would change what a key is, rather than binding data to a
ciphertext.
What goes in the envelope
The transit ciphertext is a self-describing string, vault:v<N>:<base64>. It is stored
verbatim in the envelope's ciphertext slot, with empty nonce and tag:
- The nonce and tag are inside transit's own base64 blob. There is nothing to put in those slots, and the frozen v1 envelope layout permits zero-length values for both.
- Re-synthesising the
vault:v<N>:prefix from the envelope'skey_versionon the way out would mean assuming the prefix format forever. OpenBao already emits other shapes for other key classes; storing the server's own string means a future shape keeps working with no envelope change. - The version is therefore recorded twice — in the envelope header and inside the
transit string.
decrypt/3requires them to agree, which costs nothing and turns a spliced ciphertext body into a clean refusal before the round trip.
Envelope cipher id is :openbao_transit_v1, so a value encrypted this way decrypts
through this module forever, even if the vault's default cipher changes later.
Pairing
This cipher only works with AshVault.KeyProviders.OpenBaoTransit. Given raw key bytes
from any other provider it returns {:error, :requires_open_bao_transit_key_provider} rather than
inventing a transit key name — there is no correct name to invent. Conversely, every
other cipher declines this provider's handle with {:error, :opaque_key_unsupported}.
Summary
Functions
Decrypt through transit/decrypt, verifying aad as associated_data.
Encrypt through transit/encrypt, binding aad as associated_data.
The stable cipher id, :openbao_transit_v1.
The key size in bytes, 32, matching aes256-gcm96.
The key version embedded in a transit ciphertext string.
Functions
@spec decrypt(AshVault.Cipher.payload(), AshVault.Key.t(), binary()) :: {:ok, binary()} | {:error, term()}
Decrypt through transit/decrypt, verifying aad as associated_data.
Returns {:error, :auth_failed} — which AshVault.Vault.Runtime reports as
AshVault.Errors.CiphertextIntegrityFailed — only for a genuine authentication
failure. Every other failure (a deleted key, a 403, an unreachable server) is
returned as AshVault.Errors.ProviderUnavailable, so an outage is never reported to an
operator as "your data was tampered with".
@spec encrypt(binary(), AshVault.Key.t(), binary()) :: {:ok, AshVault.Cipher.payload()} | {:error, term()}
Encrypt through transit/encrypt, binding aad as associated_data.
The encrypt is pinned to the handle's key_version, so a rotation racing this call
cannot silently produce a ciphertext under a version the envelope does not name.
@spec id() :: :openbao_transit_v1
The stable cipher id, :openbao_transit_v1.
@spec key_bytes() :: pos_integer()
The key size in bytes, 32, matching aes256-gcm96.
Nominal only: this cipher never sees key bytes. It exists because
AshVault.Cipher.key_bytes/0 is a required callback and
AshVault.Vault.verify_key_sizes!/2 reads it. AshVault.KeyProviders.OpenBaoTransit
deliberately does not export key_bytes/0, so that compile-time comparison does not
fire for the supported pairing.
@spec parse_version(binary()) :: {:ok, pos_integer()} | :error
The key version embedded in a transit ciphertext string.
Public so the envelope-versus-transit agreement check can be tested directly.
Examples
iex> AshVault.Ciphers.OpenBaoTransit.parse_version("vault:v3:abcdef")
{:ok, 3}
iex> AshVault.Ciphers.OpenBaoTransit.parse_version("not a transit ciphertext")
:error