AshVault.Vault.Runtime (AshVault v0.2.0)

Copy Markdown View Source

The implementation behind every module that uses AshVault.Vault.

Generated vault modules are one-line delegations into this module, passing their compile-time configuration as an opts map. Keeping the logic here (rather than in the use macro) keeps generated code tiny, stack traces readable, and this code testable on its own.

All functions here take opts, a map with the :key_provider, :cipher, :envelope, :scope and :rotation_policy modules, and — for mac!/3 and verify_mac!/5 — the :mac module. :vault, when present, labels telemetry.

Summary

Functions

Build the additional authenticated data bound into every ciphertext.

The current version of the scope's :mac keyring, minting the keyring on first use.

Decrypt an encoded envelope for the given context, returning the plaintext.

Destroy every key for a scope (crypto-erasure), raising on provider failure.

Encrypt plaintext for the given context, returning an encoded envelope.

Compute a MAC over data for a context, under the scope's current :mac key.

Compute a MAC over data under one stated version of the scope's :mac keyring.

Map a key provider's raw error term onto an AshVault error struct.

Resolve scope_module against ctx, enforcing the scope invariant.

Rotate the :data key for a scope, raising on provider failure.

Rotate a scope's keyring for purpose, raising on provider failure.

Verify a tag produced by mac!/3, returning :ok or raising.

Types

opts()

@type opts() :: %{
  :key_provider => module(),
  :cipher => module(),
  :envelope => module(),
  :scope => module(),
  :rotation_policy => module(),
  optional(:mac) => module(),
  optional(:vault) => module()
}

Functions

build_aad(scope, context)

@spec build_aad(term(), AshVault.Context.t()) :: binary()

Build the additional authenticated data bound into every ciphertext.

The format is frozen:

"ashvault:v1|" <> scope <> "|" <> inspect(resource) <> "|" <> field

It is a stable, human-inspectable binary rather than :erlang.term_to_binary/1, because term encoding is not guaranteed stable across OTP releases and ciphertext must outlive OTP upgrades. Binding scope, resource and field means a value cannot be replayed into a different tenant, resource or column.

current_mac_version!(ctx, opts)

@spec current_mac_version!(AshVault.Context.t(), opts()) :: pos_integer()

The current version of the scope's :mac keyring, minting the keyring on first use.

What mac_at!/4 needs to sign under the current key, and what a verifier compares a stated version against to decide whether that version is still accepted. Raises AshVault.Errors.KeyDestroyed for an erased scope, AshVault.Errors.PurposeUnsupported when the provider has no :mac keyring and AshVault.Errors.ProviderUnavailable for an outage. Never returns key material.

decrypt!(blob, ctx, opts)

@spec decrypt!(binary(), AshVault.Context.t(), opts()) :: binary()

Decrypt an encoded envelope for the given context, returning the plaintext.

The cipher is resolved from the envelope, not from the vault's configured default, so values keep decrypting after the default cipher changes.

Raises AshVault.Errors.InvalidCiphertext or AshVault.Errors.UnsupportedEnvelope for unparseable input, AshVault.Errors.KeyDestroyed for crypto-erased scopes, AshVault.Errors.KeyNotFound for unknown key versions, and AshVault.Errors.CiphertextIntegrityFailed when the tag does not verify.

destroy!(scope, opts)

@spec destroy!(term(), opts()) :: :ok

Destroy every key for a scope (crypto-erasure), raising on provider failure.

Returns only once the provider has confirmed the destruction.

encrypt!(plaintext, ctx, opts)

@spec encrypt!(binary(), AshVault.Context.t(), opts()) :: binary()

Encrypt plaintext for the given context, returning an encoded envelope.

Raises AshVault.Errors.MissingScope if the scope cannot be resolved, and AshVault.Errors.ProviderUnavailable / AshVault.Errors.KeyDestroyed if the key provider cannot supply a current key.

mac!(data, ctx, opts)

@spec mac!(binary(), AshVault.Context.t(), opts()) :: {pos_integer(), binary()}

Compute a MAC over data for a context, under the scope's current :mac key.

Returns {key_version, tag}: tag is the raw bytes AshVault.Mac.c:mac/3 produced, and key_version is what verify_mac!/5 needs back. The tag is bound to the scope, resource and field through the same associated data encrypt!/3 uses (build_aad/2), so a tag minted for one tenant, resource or field never verifies for another.

The scope's :mac keyring is minted on first use. Raises AshVault.Errors.KeyDestroyed for an erased scope, AshVault.Errors.PurposeUnsupported when the provider has no :mac keyring, and AshVault.Errors.ProviderUnavailable for an outage.

Emits [:ash_vault, :mac, :sign]; see AshVault.Telemetry.

mac_at!(data, key_version, ctx, opts)

@spec mac_at!(binary(), term(), AshVault.Context.t(), opts()) :: binary()

Compute a MAC over data under one stated version of the scope's :mac keyring.

mac!/3 always signs under the current version; this is its version-pinned sibling, for a caller that must recompute a tag at the version a credential names — a macaroon verifier recomputes its root signature this way, then compares the result itself.

The key is fetched exactly as verify_mac!/5 fetches it, so the taxonomy is the same: AshVault.Errors.KeyDestroyed (the scope was erased — revoked), AshVault.Errors.KeyNotFound (no such version, including a non-integer one — invalid) and AshVault.Errors.ProviderUnavailable (retry; nothing was decided). It never mints a keyring: a version that does not exist is KeyNotFound, not a fresh key.

Emits [:ash_vault, :mac, :sign] with the stated key_version.

map_provider_error(error, scope, ctx)

@spec map_provider_error(term(), term(), AshVault.Context.t()) :: Exception.t()

Map a key provider's raw error term onto an AshVault error struct.

resolve_scope!(ctx, scope_module, operation)

@spec resolve_scope!(AshVault.Context.t(), module(), atom()) :: binary()

Resolve scope_module against ctx, enforcing the scope invariant.

One place enforces it, so a custom AshVault.Scope that returns a non-binary fails here with a clear message rather than differently in each provider — a provider's own validate_scope!/1 would raise a bare ArgumentError naming the provider, which tells an operator nothing about the scope module that actually produced the bad term.

Public because the lookup-token path (AshVault.Lookup.field_key/3) resolves a scope outside encrypt!/3 and decrypt!/3 and must reach the same check.

Raises AshVault.Errors.InvalidScope for a non-binary, and re-raises AshVault.Errors.MissingScope tagged with operation.

rotate!(scope, opts)

@spec rotate!(term(), opts()) :: {:ok, non_neg_integer()}

Rotate the :data key for a scope, raising on provider failure.

rotate!(scope, purpose, opts)

@spec rotate!(term(), AshVault.KeyProvider.purpose(), opts()) ::
  {:ok, non_neg_integer()}

Rotate a scope's keyring for purpose, raising on provider failure.

:data calls the provider's AshVault.KeyProvider.rotate/1, exactly as rotate!/2 always has. A purpose the provider does not serve raises AshVault.Errors.PurposeUnsupported — a configuration fault, never reported as an outage.

verify_mac!(data, key_version, tag, ctx, opts)

@spec verify_mac!(binary(), term(), term(), AshVault.Context.t(), opts()) :: :ok

Verify a tag produced by mac!/3, returning :ok or raising.

The key is fetched before the tag is looked at, so the answer about the key always wins over the answer about the tag:

Comparison is constant-time (AshVault.Macs.HmacSha256) or done by OpenBao (AshVault.Macs.OpenBaoTransit). Emits [:ash_vault, :mac, :verify].