AshVault.KeyProviders.Memory (AshVault v0.2.0)

Copy Markdown View Source

An in-memory AshVault.KeyProvider, backed by a GenServer.

Development and test only

Every key lives in process memory and dies with the process. There is no persistence, no replication and no protection of the key material at rest. Never use this provider in production — losing the process means losing every key, which means losing every encrypted value.

Adding it to your supervision tree

AshVault deliberately does not start this provider for you: applications opt in. Add it to your own supervisor, usually only outside production:

# config/dev.exs and config/test.exs
config :my_app, start_memory_key_provider?: true

# lib/my_app/application.ex — a runtime flag, not `Mix.env/0`, because `Mix` is
# not available in a release.
children =
  [MyApp.Repo] ++
    if Application.get_env(:my_app, :start_memory_key_provider?, false) do
      [AshVault.KeyProviders.Memory]
    else
      []
    end

Supervisor.start_link(children, strategy: :one_for_one)

It registers under its own module name by default. Pass name: to run several instances (for example one per test):

start_supervised!({AshVault.KeyProviders.Memory, name: :my_provider})

Note that the AshVault.KeyProvider callbacks take no process name, so a vault always talks to the default-named instance.

Configuration

config :ash_vault, AshVault.KeyProviders.Memory, key_bytes: 32

Destruction semantics

destroy/1 wipes the scope's key material — the :data and :mac keyrings and the lookup key alike — and records a permanent tombstone. Every current_key, get_key and rotate, for either purpose, and lookup_key/1 return {:error, :destroyed} afterwards, for the life of the process. Destroying twice is idempotent.

Purposes

Serves both :data and :mac (see Purposes in AshVault.KeyProvider). The two keyrings are separate maps of separately drawn random bytes, rotated independently.

Scopes

Scopes must be binaries, matching AshVault.KeyProviders.Local and AshVault.KeyProviders.OpenBao. A non-binary scope raises ArgumentError: a provider that silently accepted arbitrary terms would let a custom AshVault.Scope pass tests here and then behave differently — or unsafely — in production.

Key material never reaches a crash report

format_status/1 redacts the key table. Without it, any crash in this GenServer emits a SASL report containing every scope's raw key bytes, straight into the log aggregator and any APM handler attached to it.

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

Same as 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 tombstone it.

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

Same as get_key/3 for a purpose, against an explicitly named instance.

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

Fetch the scope's stable lookup key, minting it 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

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

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)

Two forms, told apart by the first argument — a scope is always a binary, a server never is:

current_key(server, scope, purpose)

Same as 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 tombstone it.

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()}

Same as get_key/3 for a purpose, against an explicitly named instance.

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 it on first use.

A separate map, never touched by rotate/1 and wiped by destroy/1. See AshVault.KeyProvider.lookup_key/1 for why it must not move.

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)

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

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Start the provider.

Accepts :name (defaults to this module) and :key_bytes.