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/keysmetadata read, thentransit/encrypt. A scope's very first encrypt adds the key-create call. - decrypt: 3 calls — tombstone read,
transit/keysmetadata read, thentransit/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
endConfiguration
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: falseStock 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.OpenBaoTransitThe 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
@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.
@spec current_key(AshVault.KeyProvider.scope(), AshVault.KeyProvider.purpose()) :: {:ok, AshVault.KeyProvider.key_info()} | {:error, term()}
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.
@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.
@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.
@spec get_key( AshVault.KeyProvider.scope(), AshVault.KeyProvider.version(), AshVault.KeyProvider.purpose() ) :: {:ok, AshVault.Key.opaque()} | {:error, term()}
A handle to one version of a scope's keyring for a purpose, validated against the
server first — see get_key/2.
@spec handle(String.t(), AshVault.KeyProvider.version()) :: AshVault.Key.opaque()
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.
@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"
@spec mac_handle(String.t(), AshVault.KeyProvider.version()) :: AshVault.Key.opaque()
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.
@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.
@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.
@spec purposes() :: [AshVault.KeyProvider.purpose()]
The purposes this provider serves: [:data, :mac].
@spec rotate(AshVault.KeyProvider.scope()) :: {:ok, AshVault.KeyProvider.version()} | {:error, term()}
Mint the next key version for a scope. Previous versions stay decryptable.
@spec rotate(AshVault.KeyProvider.scope(), AshVault.KeyProvider.purpose()) :: {:ok, AshVault.KeyProvider.version()} | {:error, term()}
Mint the next key version for a scope and purpose. The :data and :mac keyrings
are different transit keys and rotate independently.
@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.
@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.
@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.