Behaviour for key providers: the components that mint, serve, rotate and destroy the symmetric keys AshVault encrypts with.
A provider is addressed by scope — an opaque term (normalised to a binary by
AshVault.Scope implementations) identifying the blast radius of a key, typically a
tenant id.
Two rules every implementation must honour:
current_key/1mints the scope's key material on first use, at version 1. Callers never create a scope's key explicitly.destroy/1is a tombstone, not a delete. After destroying a scope, bothcurrent_key/1andget_key/2must return{:error, :destroyed}forever — never{:error, :not_found}, and never a freshly minted key. Silently re-minting would turn crypto-erasure into silent data loss.
Purposes
A scope can hold more than one keyring, one per purpose:
:data— the keysAshVault.Cipherencrypts with. The arity forms every provider has always had (current_key/1,get_key/2,rotate/1) are this purpose, and always will be.:mac— the keysAshVault.Macauthenticates with:current_key/2,get_key/3androtate/2with:macas the last argument.
A provider declares what it can serve with purposes/0; one that does not define it
serves :data only, and every provider written before purposes existed keeps working
unchanged. Call sites never dispatch on arity themselves — they go through
current_key/3, get_key/4 and rotate/3 in this module, which route :data to the
original callbacks and refuse a purpose the provider has not declared.
The rules for a :mac keyring are the :data rules, plus separation:
- minted on first use at version 1, rotated independently — rotating
:macnever moves:data, and rotating:datanever moves:mac; - old versions stay fetchable after a rotation, so tags minted under them still verify;
destroy/1destroys every purpose under the one tombstone, and afterwards each purpose answers{:error, :destroyed}forever and never re-mints;- a
:mackey is never a:datakey, never the lookup key, and never derived from either. It is minted atmac_key_bytes/0bytes regardless of the provider's datakey_bytes/0.
Summary
Types
The key material a provider serves.
Which keyring of a scope a key belongs to. See Purposes above.
Callbacks
A Supervisor child specification for this provider, when it needs to be supervised.
Fetch (minting on first use) the current key for a scope.
current_key/1 for a purpose. Only called with a purpose purposes/0 lists.
Irreversibly destroy all key material for a scope and record a tombstone.
Fetch a specific historical key version for a scope.
get_key/2 for a purpose. Only called with a purpose purposes/0 lists.
The key size, in bytes, this provider mints. Defaults to 32.
The scope's lookup key: the secret that searchable fields derive HMAC tokens from.
The purposes this provider can serve keys for. Optional; [:data] when absent.
Mint a new key version for a scope, retaining history.
rotate/1 for a purpose. Only called with a purpose purposes/0 lists.
The operator setup step this provider needs before it can serve keys.
Functions
Every purpose AshVault knows, [:data, :mac].
The child specifications a vault's (or a provider's) key material needs supervised.
The configuration for a provider, from the host application's OTP app key first and
:ash_vault's second.
Fetch (minting on first use) a scope's current key for purpose.
The default key size in bytes, 32.
Fetch one key version of a scope's purpose keyring. See current_key/3.
The key size a provider mints, falling back to 32 bytes when it does not say.
Fetch a scope's lookup key, or {:error, :lookup_unsupported} when the provider has
no lookup_key/1.
The size, in bytes, of every :mac key a shipped provider mints: 32.
The host OTP applications provider configuration may be written under.
The purposes a provider serves: its purposes/0, or [:data] when it has none.
Record app as an OTP application whose config config/1 should consult.
Rotate a scope's purpose keyring. See current_key/3.
Run the operator setup step for a vault's (or a provider's) key provider.
Whether a provider can serve lookup keys.
Whether a provider can serve keys for purpose.
The provider a AshVault.KeyProviders.Cached wrapper wraps, or the module itself.
Types
@type key() :: AshVault.Key.t()
The key material a provider serves.
A raw binary for every provider AshVault ships. The union with AshVault.Key is the
opt-in extension point for a provider that keeps key material outside the BEAM heap
and hands out an opaque handle instead; see AshVault.Key.
@type key_info() :: %{ version: version(), key: AshVault.Key.t(), created_at: DateTime.t() }
@type purpose() :: :data | :mac
Which keyring of a scope a key belongs to. See Purposes above.
@type scope() :: term()
@type version() :: non_neg_integer()
Callbacks
@callback child_spec(term()) :: Supervisor.child_spec()
A Supervisor child specification for this provider, when it needs to be supervised.
Optional. A provider that owns no process — AshVault.KeyProviders.OpenBao is a pile
of stateless HTTP calls — simply does not define it, and
AshVault.KeyProvider.children/1 reports no children for it.
AshVault.KeyProviders.Local, AshVault.KeyProviders.Memory and the generated
AshVault.KeyProviders.Cached wrappers all satisfy this callback for free, through
use GenServer and their own child_spec/1.
Do not call this callback directly to build a supervision tree. Call
MyApp.Vault.child_specs/0, which knows about the cache wrapper as well as the
provider underneath it.
Fetch (minting on first use) the current key for a scope.
current_key/1 for a purpose. Only called with a purpose purposes/0 lists.
Irreversibly destroy all key material for a scope and record a tombstone.
@callback get_key(scope(), version()) :: {:ok, AshVault.Key.t()} | {:error, :not_found} | {:error, :destroyed} | {:error, term()}
Fetch a specific historical key version for a scope.
@callback get_key(scope(), version(), purpose()) :: {:ok, AshVault.Key.t()} | {:error, :not_found} | {:error, :destroyed} | {:error, term()}
get_key/2 for a purpose. Only called with a purpose purposes/0 lists.
@callback key_bytes() :: pos_integer()
The key size, in bytes, this provider mints. Defaults to 32.
The scope's lookup key: the secret that searchable fields derive HMAC tokens from.
Optional. A provider that does not implement it makes searchable?: true a
compile-time DSL error naming the provider, rather than a runtime surprise.
Three rules, and all three are load-bearing:
- it is stable.
rotate/1MUST NOT change it. A lookup key that rotates silently invalidates every token already stored: existing rows stop matching, and nothing raises. Mint it once per scope and return the same bytes forever. - it is per scope, like every other key here, so the equality a token leaks never leaks across tenants.
destroy/1destroys it along with everything else, and the same tombstone gates it afterwards — erasure still erases, and a destroyed scope'slookup_key/1returns{:error, :destroyed}rather than a fresh secret.
It must not be the key current_key/1 serves, nor derived from it. Per-field
separation is HKDF's job (AshVault.Lookup), not the provider's.
@callback purposes() :: [purpose()]
The purposes this provider can serve keys for. Optional; [:data] when absent.
A provider listing :mac must implement current_key/2, get_key/3 and
rotate/2, and its destroy/1 must destroy the :mac keyring too.
Mint a new key version for a scope, retaining history.
rotate/1 for a purpose. Only called with a purpose purposes/0 lists.
@callback setup() :: :ok | {:error, term()}
The operator setup step this provider needs before it can serve keys.
Optional, and deliberately separate from child_spec/1: it is a one-shot,
privileged, occasionally destructive-adjacent action (creating a key root, mounting a
secrets engine), not something a supervisor should be doing on every boot of every
node.
Implementations must be idempotent — AshVault.KeyProviders.OpenBao.setup/0 is a
no-op against an already-mounted KV engine, and AshVault.KeyProviders.Local.setup/0
is a no-op against an already-initialised root.
A provider that needs no setup does not define it; AshVault.KeyProvider.setup/1
returns :ok for it.
Functions
@spec all_purposes() :: [purpose()]
Every purpose AshVault knows, [:data, :mac].
The child specifications a vault's (or a provider's) key material needs supervised.
This is the one line a host application's Application.start/2 writes:
children = [MyApp.Repo] ++ MyApp.Vault.child_specs()Pass a vault rather than a provider. A vault built with cache: true supervises
two things — the generated CachedKeyProvider, which owns the cache, and the provider
underneath it if that one owns a process too — and only the vault knows about both.
Passing a provider module works and returns that provider's own children.
A provider with no child_spec/1 contributes nothing, which is why
AshVault.KeyProviders.OpenBao needs no case in your Application module.
The configuration for a provider, from the host application's OTP app key first and
:ash_vault's second.
Every provider AshVault ships reads its configuration through here, so all of them accept both of these, with the host application's winning on a key-by-key merge:
# your application's own OTP app key — preferred
config :my_app, AshVault.KeyProviders.OpenBao, address: "http://127.0.0.1:8200"
# AshVault's OTP app key — the original form, still supported
config :ash_vault, AshVault.KeyProviders.OpenBao, address: "http://127.0.0.1:8200"The host application is learned from your vault: use AshVault.Vault records the OTP
application the vault module is compiled into (override it with otp_app:), and
registers it the first time the vault module is loaded. You can also name it
explicitly, which is what a library with no vault of its own would do:
config :ash_vault, otp_app: :my_appWhy this is not simply a keyword list on the vault
A AshVault.KeyProvider callback takes a scope and nothing else — current_key/1,
get_key/2, rotate/1, destroy/1 — so there is no argument on any provider call
site through which a vault could hand its provider a configuration. Provider
configuration is therefore per provider module, globally, exactly as it was; the
only thing that changed is which OTP application key it may be written under.
Fetch (minting on first use) a scope's current key for purpose.
:data calls current_key/1, exactly as AshVault always has. Any other purpose the
provider does not list in purposes/0 is {:error, {:purpose_unsupported, purpose}}
— a configuration fault, which AshVault.Vault.Runtime reports as
AshVault.Errors.PurposeUnsupported, never as an outage.
@spec default_key_bytes() :: pos_integer()
The default key size in bytes, 32.
@spec get_key(module(), scope(), version(), purpose()) :: {:ok, AshVault.Key.t()} | {:error, term()}
Fetch one key version of a scope's purpose keyring. See current_key/3.
@spec key_bytes(module()) :: pos_integer()
The key size a provider mints, falling back to 32 bytes when it does not say.
Fetch a scope's lookup key, or {:error, :lookup_unsupported} when the provider has
no lookup_key/1.
Every caller goes through here rather than calling the optional callback directly, so
"this provider cannot do searchable fields" is one tagged value instead of an
UndefinedFunctionError from inside a before_action hook.
@spec mac_key_bytes() :: pos_integer()
The size, in bytes, of every :mac key a shipped provider mints: 32.
Fixed, and deliberately independent of a provider's data key_bytes/0 — an
aes128-gcm96 data keyring must not quietly halve the MAC key.
@spec otp_apps() :: [atom()]
The host OTP applications provider configuration may be written under.
config :ash_vault, otp_app: :my_app (an atom or a list) comes first, then whatever
the loaded vault modules registered through register_otp_app/1.
The purposes a provider serves: its purposes/0, or [:data] when it has none.
@spec register_otp_app(atom() | nil) :: :ok
Record app as an OTP application whose config config/1 should consult.
Called from a vault module's @on_load, so a vault's own application is registered
before anything can reach a provider through that vault — a provider call site is only
ever reached by way of a vault, and calling a vault loads it.
:ash_vault itself is ignored: it is already config/1's base.
Rotate a scope's purpose keyring. See current_key/3.
Run the operator setup step for a vault's (or a provider's) key provider.
The counterpart to children/1, and the other line a host writes — in a release
task, a mix task, or a one-shot deploy step:
MyApp.Vault.setup()Returns :ok when the provider has no setup/0, so a host does not need a case
over provider modules to know whether there is anything to do. Stops at the first
error when a cache wrapper and the provider it wraps both define one.
Whether a provider can serve lookup keys.
Fails open: a provider module that is not compiled yet answers true. This is
called from AshVault.Verifiers.VerifyVault, and a compile-order-dependent DSL error
is worse than the clean runtime AshVault.Errors.LookupUnsupported the same path
produces later. AshVault.Verifiers.VerifyVault treats an uncompiled vault the same way.
AshVault.KeyProviders.Cached is unwrapped to the provider it caches: the generated
wrapper delegates lookup_key/1 unconditionally, so asking the wrapper directly would
always answer true and defeat the compile-time check.
Whether a provider can serve keys for purpose.
:data is always true. For any other purpose this fails open for a module that
is not compiled yet, exactly like supports_lookup?/1 and for the same reason: it is
called from compile-time checks, and AshVault.Errors.PurposeUnsupported is the clean
runtime backstop. AshVault.KeyProviders.Cached is unwrapped to the provider it wraps.
Purpose support is read from purposes/0 and never inferred from arity:
AshVault.KeyProviders.Memory and AshVault.KeyProviders.Local have long exported a
current_key/2 that takes a server and a scope, and a provider that copied that
pattern must not be mistaken for one that understands purposes.
The provider a AshVault.KeyProviders.Cached wrapper wraps, or the module itself.