AshVault.KeyProviders.Local (AshVault v0.2.0)

Copy Markdown View Source

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 destroyed

scope_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_keys

or, 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}, for current_key/1, get_key/2 and rotate/1 alike, 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 :enoent counts as absence
  • no scope directory, or no meta.json → an ordinary absent scope: current_key/1 mints version 1, get_key/2 returns {:error, :not_found}
  • meta.json present but corrupt or truncated → {:error, %AshVault.Errors.ProviderUnavailable{}}
  • meta.json references 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

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

current_key(scope)

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

current_key(scope, purpose)

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

current_key/2 for a purpose, against an explicitly named instance.

destroy(scope)

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

destroy(server, scope)

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

Same as destroy/1, against an explicitly named instance.

get_key(scope, version)

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

get_key(scope, version, purpose)

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

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

init_root!(root)

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

key_bytes()

@spec key_bytes() :: pos_integer()

The key size in bytes this provider mints, from config, defaulting to 32.

lookup_key(scope)

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

lookup_key(server, scope)

@spec lookup_key(GenServer.server(), AshVault.KeyProvider.scope()) ::
  {:ok, binary()} | {:error, term()}

Same as lookup_key/1, against an explicitly named instance.

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 :data key version for a scope, keeping previous versions fetchable.

rotate(scope, purpose)

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

Two forms, told apart by the first argument:

rotate(server, scope, purpose)

rotate/2 for a purpose, against an explicitly named instance.

scope_dir(scope)

@spec scope_dir(binary()) :: String.t()

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.

sentinel_file()

@spec sentinel_file() :: String.t()

The name of the sentinel file that marks a directory as an initialised key root.

setup()

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

start_link(opts \\ [])

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