AshVault.KeyProvider behaviour (AshVault v0.2.0)

Copy Markdown View Source

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/1 mints the scope's key material on first use, at version 1. Callers never create a scope's key explicitly.
  • destroy/1 is a tombstone, not a delete. After destroying a scope, both current_key/1 and get_key/2 must 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 keys AshVault.Cipher encrypts 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 keys AshVault.Mac authenticates with: current_key/2, get_key/3 and rotate/2 with :mac as 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 :mac never moves :data, and rotating :data never moves :mac;
  • old versions stay fetchable after a rotation, so tags minted under them still verify;
  • destroy/1 destroys every purpose under the one tombstone, and afterwards each purpose answers {:error, :destroyed} forever and never re-mints;
  • a :mac key is never a :data key, never the lookup key, and never derived from either. It is minted at mac_key_bytes/0 bytes regardless of the provider's data key_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

key()

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

key_info()

@type key_info() :: %{
  version: version(),
  key: AshVault.Key.t(),
  created_at: DateTime.t()
}

purpose()

@type purpose() :: :data | :mac

Which keyring of a scope a key belongs to. See Purposes above.

scope()

@type scope() :: term()

version()

@type version() :: non_neg_integer()

Callbacks

child_spec(term)

(optional)
@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.

current_key(scope)

@callback current_key(scope()) :: {:ok, key_info()} | {:error, term()}

Fetch (minting on first use) the current key for a scope.

current_key(scope, purpose)

(optional)
@callback current_key(scope(), purpose()) :: {:ok, key_info()} | {:error, term()}

current_key/1 for a purpose. Only called with a purpose purposes/0 lists.

destroy(scope)

@callback destroy(scope()) :: :ok | {:error, term()}

Irreversibly destroy all key material for a scope and record a tombstone.

get_key(scope, version)

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

get_key(scope, version, purpose)

(optional)
@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.

key_bytes()

(optional)
@callback key_bytes() :: pos_integer()

The key size, in bytes, this provider mints. Defaults to 32.

lookup_key(scope)

(optional)
@callback lookup_key(scope()) :: {:ok, binary()} | {:error, term()}

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/1 MUST 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/1 destroys it along with everything else, and the same tombstone gates it afterwards — erasure still erases, and a destroyed scope's lookup_key/1 returns {: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.

purposes()

(optional)
@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.

rotate(scope)

@callback rotate(scope()) :: {:ok, version()} | {:error, term()}

Mint a new key version for a scope, retaining history.

rotate(scope, purpose)

(optional)
@callback rotate(scope(), purpose()) :: {:ok, version()} | {:error, term()}

rotate/1 for a purpose. Only called with a purpose purposes/0 lists.

setup()

(optional)
@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

all_purposes()

@spec all_purposes() :: [purpose()]

Every purpose AshVault knows, [:data, :mac].

children(vault_or_provider)

@spec children(module()) :: [module()]

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.

config(provider)

@spec config(module()) :: keyword()

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_app

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

current_key(provider, scope, purpose)

@spec current_key(module(), scope(), purpose()) ::
  {:ok, key_info()} | {:error, term()}

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.

default_key_bytes()

@spec default_key_bytes() :: pos_integer()

The default key size in bytes, 32.

get_key(provider, scope, version, purpose)

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

key_bytes(provider)

@spec key_bytes(module()) :: pos_integer()

The key size a provider mints, falling back to 32 bytes when it does not say.

lookup_key(provider, scope)

@spec lookup_key(module(), scope()) :: {:ok, binary()} | {:error, term()}

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.

mac_key_bytes()

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

otp_apps()

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

purposes(provider)

@spec purposes(module()) :: [purpose()]

The purposes a provider serves: its purposes/0, or [:data] when it has none.

register_otp_app(app)

@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(provider, scope, purpose)

@spec rotate(module(), scope(), purpose()) :: {:ok, version()} | {:error, term()}

Rotate a scope's purpose keyring. See current_key/3.

setup(vault_or_provider)

@spec setup(module()) :: :ok | {:error, term()}

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.

supports_lookup?(provider)

@spec supports_lookup?(module()) :: boolean()

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.

supports_purpose?(provider, purpose)

@spec supports_purpose?(module(), purpose()) :: boolean()

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.

unwrap_cached(provider)

@spec unwrap_cached(module()) :: module()

The provider a AshVault.KeyProviders.Cached wrapper wraps, or the module itself.