AshVault.KeyProviders.OpenBaoTransit (AshVault v0.2.0)

Copy Markdown View Source

An AshVault.KeyProvider backed by OpenBao transit that never exports key material.

This is the sibling of AshVault.KeyProviders.OpenBao, and the difference is the whole point: that provider exports a scope's raw DEK so an in-process cipher can use it, and this one does not export anything ever. Encryption and decryption happen inside OpenBao, through transit/encrypt and transit/decrypt. The key bytes never become an Elixir term, never land on a process heap, and never appear in a crash dump, a core file or a :erlang.system_info(:procs) dump — because they never leave the server.

The cost is three network round trips per value

Per value, not per query — and three, not one. Measured with a [:finch, :request, :stop] counter in test/ash_vault/ciphers/open_bao_transit_test.exs:

  • encrypt: 3 calls — tombstone read, transit/keys metadata read, then transit/encrypt. A scope's very first encrypt adds the key-create call.
  • decrypt: 3 calls — tombstone read, transit/keys metadata read, then transit/decrypt.

For comparison, measured the same way, AshVault.KeyProviders.OpenBao costs 3 on encrypt and 2 on decrypt, and AshVault.KeyProviders.Cached collapses both to 0 on a cache hit. This provider gets nothing from that wrapper: Cached caches a key only when it is_binary/1, so a handle passes through uncached on every call. Transit also has batch endpoints, but the AshVault.Cipher contract is one value at a time, so they go unused.

A page of 50 rows with two encrypted columns is therefore ~300 calls, ~300 ms of serialised latency at a 1 ms round trip. Choose this provider when key material in BEAM memory is the threat you are actually defending against, and measure before you roll it out broadly.

How it works

A AshVault.KeyProvider callback has to return something as the key. This one returns an opaque AshVault.Key handle naming the transit key and the version to use:

%AshVault.Key{ref: {"ashvault_nx_dGVuYW50XzQy", 3}, owner: AshVault.KeyProviders.OpenBaoTransit}

The handle carries no secret — only a name and an integer — and it is a pure, deterministic function of the scope and the version, so two calls for the same scope and version are equal terms. AshVault.Ciphers.OpenBaoTransit is the only cipher that understands it; every other cipher returns {:error, :opaque_key_unsupported} and AshVault.Vault.Runtime raises AshVault.Errors.OpaqueKeyUnsupported naming both modules. There is deliberately no unwrap path.

defmodule MyApp.Vault do
  use AshVault.Vault,
    key_provider: AshVault.KeyProviders.OpenBaoTransit,
    cipher: AshVault.Ciphers.OpenBaoTransit
end

Configuration

config :ash_vault, AshVault.KeyProviders.OpenBaoTransit,
  address: "http://127.0.0.1:8200",
  token: {:system, "BAO_TOKEN"},
  transit_mount: "transit",
  kv_mount: "ashvault",
  key_type: "aes256-gcm96",
  receive_timeout: 5_000,
  max_retries: 2,
  reuse_connections: false,
  server_retirement: false

Stock Transit remains the default. server_retirement: true requires the initialized AshVault retirement plugin and transactional server storage. It fences every Transit operation at the server, including operations using a handle acquired before erasure, and prevents delayed creates from committing after retirement even if their client crashes. It never falls back to stock deletion. Live-scope checks add a server-retirement status request to the round-trip counts above. See Server-enforced retirement.

Instead of :token, auth: {:kubernetes, role: "..."} logs in with the pod's service account through a supervised token holder, and :cacertfile (or :connect_options) trusts a private CA. See Running against OpenBao in Kubernetes.

AshVault.Ciphers.OpenBaoTransit reads this same configuration block — address and token are looked up under this module's key, never carried in the handle.

The key is verified non-exportable on every metadata read

Creating a transit key that already exists is a silent no-op on OpenBao 2.6.2: the server returns the existing metadata and ignores the exportable flag you sent (verified live). So posting exportable: false is not a guarantee — if the key was already created exportable, by AshVault.KeyProviders.OpenBao or by an operator, this provider would quietly be using exportable key material while its moduledoc promised otherwise.

current_key/1 and get_key/2 therefore read data.exportable back and refuse with AshVault.Errors.ProviderUnavailable (reason: {:exportable_key, name}) if it is true. The claim in the headline is a checked invariant, not a hope.

This is checked when a key handle is obtained, not on every transit call — flipping a key to exportable mid-request is not defended against, and cannot be from here.

Transit key names are deliberately distinct from the exporting provider's

AshVault.KeyProviders.OpenBao uses ashvault_<base64url(scope)>; this provider uses ashvault_nx_<base64url(scope)> (nx for non-exportable). Sharing a name would mean the first provider to touch a scope decides whether its key is exportable, and the other one silently inherits that decision.

The consequence is that the two providers hold separate key material and separate tombstones for the same scope, exactly as AshVault.KeyProviders.Local and AshVault.KeyProviders.OpenBao do. Migrating between them means re-encrypting, and erasing a subject who has data under both means destroying under both vaults. See Two vaults in one application.

The exporting provider escapes ambiguous binary scopes into a versioned prefix. Before destruction this provider also checks that legacy data and MAC keys are non-exportable and no exporting-provider lookup key is present. Conflicting or ambiguous ownership is ProviderUnavailable, before writing any tombstone. With server retirement, the plugin repeats that check inside the retirement transaction.

The OpenBao policy this provider needs

Verified against openbao 2.6.2. POST /v1/transit/encrypt/<name> creates the key if it does not exist, and pinning key_version does not stop it. That matters here because the cipher issues the encrypt from a handle, and the tombstone check lives in the provider: a handle obtained microseconds before a destroy/1 would recreate the deleted transit key on its next encrypt. The recreated key is orphaned — the tombstone still fails every read closed — but it is key material that should not exist.

Withhold the create capability on the encrypt path and OpenBao refuses the auto-creation with 403 while still allowing encryption of existing keys (verified). The provider never relies on that auto-creation: current_key/1 and current_key/2 create a missing key explicitly through transit/keys before handing out a handle, so the application token needs create there and nowhere else:

path "transit/keys/ashvault_*"    { capabilities = ["create", "read", "update", "delete"] }
path "transit/encrypt/ashvault_*" { capabilities = ["update"] }
path "transit/decrypt/ashvault_*" { capabilities = ["update"] }
path "ashvault/data/tombstones/*" { capabilities = ["create", "read", "update"] }

(update on transit/keys covers rotate and config; delete is for destroy/1.) Note there is no transit/export/* grant, and there must not be one.

A 403 from any of these is AshVault.Errors.ProviderForbidden, naming the refused operation — a configuration fault, not the retryable ProviderUnavailable.

Address the active node

Against an HA cluster, :address must reach the active node only (the Helm chart's <release>-active Service). Standbys serve reads and policy checks from a copy that lags the active node, so an encrypt issued right after the explicit create can reach a standby that has not seen the key yet, which treats it as an implicit create and, under the policy above, answers 403. Verified against openbao 2.6.3.

A pooled keep-alive connection would quietly break that precondition: one opened while a node was active stays on it after it is demoted, for as long as traffic keeps it busy. So by default (reuse_connections: false) every request carries connection: close and opens a new connection, which the -active Service routes to the current leader. node_status/0 reports the HA role a request lands on, for a boot probe or a gauge. See AshVault.KeyProviders.OpenBao.Transport.reuse_connections?/1.

The :mac keyring

The :mac purpose (see Purposes in AshVault.KeyProvider) is a second transit key per scope, mac_key_name/1, created exportable: false and verified non-exportable on every metadata read exactly like the data key. Only its per-version HMAC key is used, through transit/hmac and transit/verify; like the exporting provider it is an aes256-gcm96 key rather than transit's hmac type, because an hmac-type key's metadata carries no creation times (see AshVault.KeyProviders.OpenBao). Its handle is a different shape from a data key handle:

%AshVault.Key{ref: {:mac, "ashvault_nx_dGVuYW50XzQy.mac", 1}, owner: AshVault.KeyProviders.OpenBaoTransit}

AshVault.Ciphers.OpenBaoTransit matches only the two-element data shape, so it refuses a MAC handle; AshVault.Macs.OpenBaoTransit matches only this one, so it refuses a data handle. The separation of the two keyrings is enforced at the handle, not left to the caller's discipline. Pair them:

use AshVault.Vault,
  key_provider: AshVault.KeyProviders.OpenBaoTransit,
  cipher: AshVault.Ciphers.OpenBaoTransit,
  mac: AshVault.Macs.OpenBaoTransit

The application token then also needs:

path "transit/hmac/*"            { capabilities = ["update"] }
path "transit/verify/*"          { capabilities = ["update"] }

transit/hmac does not create a missing key (verified against openbao 2.6.2: it answers "encryption key not found"), so the race described above for transit/encrypt has no MAC counterpart.

Searchable fields are not supported

This provider deliberately does not implement AshVault.KeyProvider.lookup_key/1. A lookup key must be raw bytes in the application process — AshVault.Lookup runs HKDF and HMAC locally — and transit cannot hand out raw bytes by definition. Implementing it through a second, exportable transit key would make the provider's one promise false for the sake of a feature the exporting provider already does well.

The consequence is loud, not silent: AshVault.Verifiers.VerifyVault turns searchable?: true under this provider into a compile-time DSL error naming the provider, and AshVault.Errors.LookupUnsupported is the runtime backstop. Use AshVault.KeyProviders.OpenBao for vaults with searchable fields, or split the resource across two vaults.

A future provider could compute tokens with transit/hmac/<key> and skip local HKDF entirely, at one more round trip per searchable field per query. That is not built.

Tombstones and fail-closed behaviour

Identical to AshVault.KeyProviders.OpenBao, through the shared AshVault.KeyProviders.OpenBao.Transport: destroy/1 writes the tombstone before deleting the transit key; a missing KV mount on a read path is AshVault.Errors.ProviderUnavailable and never "not destroyed"; destroy/1 returns :ok only once the transit key is confirmed absent by a fresh read. An outage is never reported as erasure, and erasure is never reported as an outage.

Summary

Functions

The current key handle for a scope, creating the transit key (version 1) on first use.

The current handle for a scope and purpose. :data is current_key/1; :mac creates the scope's non-exportable hmac transit key on first use.

Tombstone a scope, then irreversibly destroy every key version for it.

A handle to one specific key version of a scope.

A handle to one version of a scope's keyring for a purpose, validated against the server first — see get_key/2.

The opaque handle this provider serves for a transit key name and version.

The transit key name a scope maps to.

The opaque handle this provider serves for a :mac key version.

The transit key name holding a scope's :mac keyring.

The HA role of the node a request lands on: :active, :standby, :sealed or :uninitialized. See AshVault.KeyProviders.OpenBao.Transport.node_status/1.

The purposes this provider serves: [:data, :mac].

Mint the next key version for a scope. Previous versions stay decryptable.

Mint the next key version for a scope and purpose. The :data and :mac keyrings are different transit keys and rotate independently.

Mount the KV-v2 engine that holds tombstones, if it is not already mounted.

The transit key name and version a handle refers to, for AshVault.Ciphers.OpenBaoTransit.

The transit key name and version a :mac handle refers to, for AshVault.Macs.OpenBaoTransit. :error for anything else, a data handle included.

Functions

current_key(scope)

@spec current_key(AshVault.KeyProvider.scope()) ::
  {:ok, AshVault.KeyProvider.key_info()} | {:error, term()}

The current key handle for a scope, creating the transit key (version 1) on first use.

The :key is an AshVault.Key handle, never bytes. created_at comes from the server's own key metadata — never fabricated, because a key that is always "created now" is never older than a max_age and silently disables every age-based AshVault.RotationPolicy.

current_key(scope, atom)

The current handle for a scope and purpose. :data is current_key/1; :mac creates the scope's non-exportable hmac transit key on first use.

destroy(scope)

@spec destroy(AshVault.KeyProvider.scope()) :: :ok | {:error, term()}

Tombstone a scope, then irreversibly destroy every key version for it.

The tombstone is committed first, so an interrupted destroy fails closed: a later current_key/1 cannot mint a fresh v1 for ciphertext whose key is already gone. Returns :ok only once the transit key is confirmed absent by a fresh read, and a repeated call resumes cleanup behind an existing tombstone.

Both keyrings go: the data key and the :mac key, behind the one tombstone. There is no lookup key to delete — this provider has none.

get_key(scope, version)

@spec get_key(AshVault.KeyProvider.scope(), AshVault.KeyProvider.version()) ::
  {:ok, AshVault.Key.opaque()}
  | {:error, :not_found}
  | {:error, :destroyed}
  | {:error, term()}

A handle to one specific key version of a scope.

The version is validated against the server's latest_version and min_decryption_version before a handle is returned. Handing back a handle for a version that does not exist would push the failure into AshVault.Ciphers.OpenBaoTransit, where a transit 400 becomes AshVault.Errors.CiphertextIntegrityFailed — telling an operator their data was tampered with, over a key version that was simply never minted.

get_key(scope, version, atom)

A handle to one version of a scope's keyring for a purpose, validated against the server first — see get_key/2.

handle(name, version)

The opaque handle this provider serves for a transit key name and version.

Deterministic and secret-free: {name, version}. AshVault.Key derives a redacted Inspect that shows only :owner, which matters because the name is Base.url_encode64/2 of the tenant id and therefore reversible.

key_name(scope)

@spec key_name(AshVault.KeyProvider.scope()) :: String.t()

The transit key name a scope maps to.

Note the _nx_ infix: this provider's keys are a different namespace from AshVault.KeyProviders.OpenBao's, on purpose.

iex> AshVault.KeyProviders.OpenBaoTransit.key_name("tenant_42")
"ashvault_nx_dGVuYW50XzQy"

mac_handle(name, version)

The opaque handle this provider serves for a :mac key version.

Tagged {:mac, name, version} so it cannot be mistaken for a data key handle by unwrap/1 — or by AshVault.Ciphers.OpenBaoTransit, which goes through it.

mac_key_name(scope)

@spec mac_key_name(AshVault.KeyProvider.scope()) :: String.t()

The transit key name holding a scope's :mac keyring.

iex> AshVault.KeyProviders.OpenBaoTransit.mac_key_name("tenant_42")
"ashvault_nx_dGVuYW50XzQy.mac"

. is outside the base64url alphabet and the prefix, so no data key name can equal any MAC key name — see AshVault.KeyProviders.OpenBao.mac_key_name/1.

node_status()

@spec node_status() ::
  {:ok, :active | :standby | :sealed | :uninitialized} | {:error, Exception.t()}

The HA role of the node a request lands on: :active, :standby, :sealed or :uninitialized. See AshVault.KeyProviders.OpenBao.Transport.node_status/1.

purposes()

@spec purposes() :: [AshVault.KeyProvider.purpose()]

The purposes this provider serves: [:data, :mac].

rotate(scope)

@spec rotate(AshVault.KeyProvider.scope()) ::
  {:ok, AshVault.KeyProvider.version()} | {:error, term()}

Mint the next key version for a scope. Previous versions stay decryptable.

rotate(scope, atom)

Mint the next key version for a scope and purpose. The :data and :mac keyrings are different transit keys and rotate independently.

setup()

@spec setup() :: :ok | {:error, Exception.t()}

Mount the KV-v2 engine that holds tombstones, if it is not already mounted.

The operator setup step, and the only place the mount is created: the tombstone read path treats a missing mount as an outage and never provisions it, because a freshly created, empty tombstone store reports every erased scope as intact.

unwrap(key)

@spec unwrap(AshVault.Key.t()) :: {:ok, {String.t(), pos_integer()}} | :error

The transit key name and version a handle refers to, for AshVault.Ciphers.OpenBaoTransit.

unwrap_mac(key)

@spec unwrap_mac(AshVault.Key.t()) :: {:ok, {String.t(), pos_integer()}} | :error

The transit key name and version a :mac handle refers to, for AshVault.Macs.OpenBaoTransit. :error for anything else, a data handle included.