AshVault.Ciphers.OpenBaoTransit (AshVault v0.2.0)

Copy Markdown View Source

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's key_version on 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/3 requires 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

decrypt(arg1, key, aad)

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

encrypt(plaintext, key, aad)

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

id()

@spec id() :: :openbao_transit_v1

The stable cipher id, :openbao_transit_v1.

key_bytes()

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

parse_version(arg1)

@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