A filesystem-backed AshVault.KeyProvider for single-node deployments.
Local exists because AshVault's central property — restoring a PostgreSQL backup must
not resurrect destroyed keys — only requires the key store to be a different system
from the database. A directory on another volume, excluded from the database backup
job, is a legitimate answer for a single-node app. AshVault.KeyProviders.Memory
cannot serve that role (it forgets everything on restart) and OpenBao is overkill for
one node.
Layout
<root>/
<scope_dir>/
meta.json # {"current": 2, "versions": {"1": "<iso8601>", ...}}
v1.key # raw key bytes, mode 0600
v2.key
lookup.key # the non-rotating searchable-field secret, mode 0600
mac-meta.json # the :mac keyring's own meta, same shape as meta.json
mac-v1.key # :mac key bytes (always 32), mode 0600
<scope_dir>.tombstone # presence == scope destroyedscope_dir is Base.url_encode64(scope, padding: false) — total, reversible and
filesystem-safe. scope_dir/1 is public so operators can find a tenant's directory.
The tombstone deliberately sits beside the scope directory rather than inside it, so that deleting (or losing) the directory cannot delete the tombstone.
Starting it
# config/runtime.exs
config :ash_vault, AshVault.KeyProviders.Local,
root: "/var/lib/my_app/ash_vault_keys",
key_bytes: 32
# lib/my_app/application.ex
children = [MyApp.Repo, AshVault.KeyProviders.Local]:root is required, either as a start_link/1 option or under that config key.
start_link/1 also takes :name (default __MODULE__) and :key_bytes (default 32).
The key root must be initialised explicitly
Local never creates its own key root
Before the provider will start, the root directory must already exist and
contain the sentinel file .ash_vault_root. Create both, once, with:
mix ash_vault.local.init /var/lib/my_app/ash_vault_keysor, from code, AshVault.KeyProviders.Local.init_root!/1.
This is a deliberate, breaking operational requirement, and it exists because the
moduledoc tells you to put the key root on its own volume. If that volume fails to
mount — a reordered systemd unit, a degraded array, an NFS server that is not up
yet — a provider that ran File.mkdir_p!/1 would create the root on the underlying
filesystem, find no tombstones at all, report itself healthy, and mint a fresh
version 1 for every tenant you have ever crypto-erased. No attacker is needed; a
boot-order bug is enough.
The sentinel lives on the mounted volume, so its absence is exactly the signal that distinguishes "the key store is not there" from "the key store is empty". It is never created automatically — a fresh install has an empty root too, and auto-creating the sentinel would make the two indistinguishable again.
Every operation checks that the root and sentinel still identify the store opened
at startup. A missing, unreadable or replaced store returns ProviderUnavailable,
including when a mounted volume disappears while the provider is running.
All operations are serialised through a GenServer, reads included. Simplicity beats
throughput here; AshVault.KeyProviders.OpenBao is the answer for load.
Operating this provider
The key directory must be excluded from the database backup
If the key root and the database land in the same tarball, snapshot or volume clone, crypto-erasure is defeated: restoring that backup resurrects both the ciphertext and the keys that open it. Keep the key root off the volume you snapshot with the database, and exclude it from the database backup job explicitly.
Back the key directory up separately and deliberately, with its own retention policy. This is a real, sharp tradeoff with no free answer:
- Keeping key backups makes erasure harder — every retained copy of the key root is a copy that can resurrect a destroyed tenant, and your retention window is the real lifetime of a "destroyed" key.
- Keeping no key backups makes data loss easy — losing the key root destroys every encrypted value in the database, permanently, with no recovery path.
Decide which risk you are underwriting, write it down, and test the restore.
Local is single-node. Two nodes sharing one NFS or SMB mount will race on
meta.json and can mint conflicting versions; use AshVault.KeyProviders.OpenBao
for multi-node deployments.
Durability
Every write is: write to a temp file in the same directory, fsync the file, chmod
it, then rename into place (atomic within a filesystem). A key file always lands
before the meta.json entry that references it, so an ill-timed crash leaves a
harmless orphan key file rather than a meta.json pointing at a missing key — the
latter would be an accidental crypto-erasure, the worst failure this module could have.
Directory fsync is best-effort
OTP offers no way to open a directory for :file.sync/1 (:file.open/2 on a
directory returns {:error, :eisdir}), so this provider cannot fsync the containing
directory after a rename. Durability of the directory entry is therefore left to
the filesystem's own ordering guarantees. The load-bearing property — key file
durably written before the metadata naming it — does not depend on it.
Destruction
destroy/1 writes the tombstone first, fsyncs it, and only then overwrites each
*.key — :data, :mac and lookup alike — with random bytes of the same length, fsyncs, unlinks, and removes
meta.json and the scope directory. Once the shred completes the tombstone is
rewritten with a shredded_at, so an interrupted destroy is visible to an operator.
The ordering is load-bearing. Shredding first and tombstoning second leaves a window
— ENOSPC, EACCES, a read-only remount, a crash — in which the scope has no key
material and no tombstone. The next current_key/1 would see an absent scope and
mint a fresh version 1; existing rows carry key_version: 1, so get_key/2 would
hand back the new v1 key and the caller would get
AshVault.Errors.CiphertextIntegrityFailed — erasure wearing the costume of tampering.
Tombstone-first fails safe: the worst case is a scope marked destroyed whose key
files linger, and the provider refuses to serve them anyway.
A tombstone is honoured on presence alone: its contents are never parsed to decide whether a scope is destroyed, so a truncated or unreadable tombstone still means destroyed.
Overwrite-before-unlink guarantees nothing about the media
Overwriting a file's bytes in place is best-effort only. On copy-on-write and log-structured filesystems (btrfs, ZFS, APFS, any SSD behind an FTL, and any snapshotted or thinly-provisioned volume) the overwrite is written elsewhere and the original blocks survive until they are reclaimed — if ever. Treat the tombstone and the AEAD, not the overwrite, as the mechanism that makes data unreadable. If you need media-level erasure, use full-disk encryption and destroy the volume key.
Error discrimination
An outage must never look like erasure:
- tombstone present →
{:error, :destroyed}, forcurrent_key/1,get_key/2androtate/1alike, forever - tombstone unreadable (
:eacces,:eio,:estale,:eloop, …) →{:error, %AshVault.Errors.ProviderUnavailable{}}. A tombstone read that cannot complete is never answered with "not destroyed": only a positive:enoentcounts as absence - no scope directory, or no
meta.json→ an ordinary absent scope:current_key/1mints version 1,get_key/2returns{:error, :not_found} meta.jsonpresent but corrupt or truncated →{:error, %AshVault.Errors.ProviderUnavailable{}}meta.jsonreferences a version whose key file is missing →{:error, :not_found}
Neither corruption nor a missing key file is ever reported as :destroyed.
Summary
Functions
Returns a specification to start this module under a supervisor.
Fetch the current :data key for a scope, minting version 1 on first use.
Two forms, told apart by the first argument — a scope is always a binary, a server never is
current_key/2 for a purpose, against an explicitly named instance.
Irreversibly destroy every key for a scope — every purpose, and the lookup key — and write its tombstone.
Same as destroy/1, against an explicitly named instance.
Fetch a specific :data key version for a scope.
Two forms, told apart by the first argument
get_key/3 for a purpose, against an explicitly named instance.
Create and initialise a key root: the directory itself (mode 0700) and the
.ash_vault_root sentinel the provider refuses to start without.
The key size in bytes this provider mints, from config, defaulting to 32.
Fetch the scope's stable lookup key, minting lookup.key on first use.
Same as lookup_key/1, against an explicitly named instance.
The purposes this provider serves: [:data, :mac].
Mint the next :data key version for a scope, keeping previous versions fetchable.
Two forms, told apart by the first argument
rotate/2 for a purpose, against an explicitly named instance.
The directory name, relative to the root, holding a scope's key material.
The name of the sentinel file that marks a directory as an initialised key root.
Initialise the configured key root, if it is not initialised already.
Start the provider.
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec current_key(AshVault.KeyProvider.scope()) :: {:ok, AshVault.KeyProvider.key_info()} | {:error, term()}
Fetch the current :data key for a scope, minting version 1 on first use.
@spec current_key(term(), term()) :: {:ok, AshVault.KeyProvider.key_info()} | {:error, term()}
Two forms, told apart by the first argument — a scope is always a binary, a server never is:
current_key(scope, purpose)— theAshVault.KeyProvider.current_key/2callback, against the default-named instance;current_key(server, scope)—current_key/1against an explicitly named instance.
@spec current_key( GenServer.server(), AshVault.KeyProvider.scope(), AshVault.KeyProvider.purpose() ) :: {:ok, AshVault.KeyProvider.key_info()} | {:error, term()}
current_key/2 for a purpose, against an explicitly named instance.
@spec destroy(AshVault.KeyProvider.scope()) :: :ok | {:error, term()}
Irreversibly destroy every key for a scope — every purpose, and the lookup key — and write its tombstone.
@spec destroy(GenServer.server(), AshVault.KeyProvider.scope()) :: :ok | {:error, term()}
Same as destroy/1, against an explicitly named instance.
@spec get_key(AshVault.KeyProvider.scope(), AshVault.KeyProvider.version()) :: {:ok, binary()} | {:error, :not_found} | {:error, :destroyed} | {:error, term()}
Fetch a specific :data key version for a scope.
@spec get_key(term(), term(), term()) :: {:ok, binary()} | {:error, :not_found} | {:error, :destroyed} | {:error, term()}
Two forms, told apart by the first argument:
get_key(scope, version, purpose)— theAshVault.KeyProvider.get_key/3callback, against the default-named instance;get_key(server, scope, version)—get_key/2against a named instance.
@spec get_key( GenServer.server(), AshVault.KeyProvider.scope(), AshVault.KeyProvider.version(), AshVault.KeyProvider.purpose() ) :: {:ok, binary()} | {:error, :not_found} | {:error, :destroyed} | {:error, term()}
get_key/3 for a purpose, against an explicitly named instance.
@spec init_root!(binary()) :: :ok
Create and initialise a key root: the directory itself (mode 0700) and the
.ash_vault_root sentinel the provider refuses to start without.
This is the operator step. It is deliberately not something the provider does for itself — see the moduledoc. It is idempotent, and it never touches existing key material.
Raises File.Error if the directory or the sentinel cannot be created.
@spec key_bytes() :: pos_integer()
The key size in bytes this provider mints, from config, defaulting to 32.
@spec lookup_key(AshVault.KeyProvider.scope()) :: {:ok, binary()} | {:error, term()}
Fetch the scope's stable lookup key, minting lookup.key on first use.
Written with the same crash-safe ordering as a versioned key, gated by the same
tombstone, and shredded by the same destroy/1 — it ends in .key, so
shred_directory/1 overwrites it before unlinking like any other key file.
It is deliberately absent from meta.json: it has no version, and rotate/1 must
never touch it. See AshVault.KeyProvider.lookup_key/1.
@spec lookup_key(GenServer.server(), AshVault.KeyProvider.scope()) :: {:ok, binary()} | {:error, term()}
Same as lookup_key/1, against an explicitly named instance.
@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 :data key version for a scope, keeping previous versions fetchable.
@spec rotate(term(), term()) :: {:ok, AshVault.KeyProvider.version()} | {:error, term()}
Two forms, told apart by the first argument:
rotate(scope, purpose)— theAshVault.KeyProvider.rotate/2callback;rotate(server, scope)—rotate/1against a named instance.
@spec rotate( GenServer.server(), AshVault.KeyProvider.scope(), AshVault.KeyProvider.purpose() ) :: {:ok, AshVault.KeyProvider.version()} | {:error, term()}
rotate/2 for a purpose, against an explicitly named instance.
The directory name, relative to the root, holding a scope's key material.
iex> AshVault.KeyProviders.Local.scope_dir("acme")
"YWNtZQ"The encoding is Base.url_encode64/2 without padding: total, reversible and safe on
every filesystem, so operators can map a tenant id to a directory and back.
@spec sentinel_file() :: String.t()
The name of the sentinel file that marks a directory as an initialised key root.
@spec setup() :: :ok
Initialise the configured key root, if it is not initialised already.
The operator setup step: exactly init_root!/1 on the :root from configuration,
so a host application that has already written that configuration does not have to dig
it back out to call init_root!/1 by hand.
MyApp.Vault.setup()Idempotent — init_root!/1 is — but deliberately still explicit: it is the step that
creates the .ash_vault_root sentinel, and the sentinel's whole job is to be absent
when the key volume failed to mount. Running it automatically on boot would create it
on the underlying filesystem and hand back a pristine, empty key store. It belongs in
a deploy step, not in a supervision tree.
@spec start_link(keyword()) :: GenServer.on_start()
Start the provider.
Options: :name (default __MODULE__), :root (required, falling back to
config :ash_vault, AshVault.KeyProviders.Local, root: ...) and :key_bytes.