# AshVault v0.2.0 - Table of Contents > Per-tenant encrypted attributes for Ash resources, with cryptographic erasure. ## Pages - [AshVault](readme.md) - [Changelog](changelog.md) - Tutorials - [Getting started](getting-started.md) - Topics - [Architecture](architecture.md) - [Tenant-scoped encryption](tenant-scoped-encryption.md) - [Rotation](rotation.md) - [Crypto-erasure](crypto-erasure.md) - [Migrating from plaintext](migrating-from-plaintext.md) - [Migrating with legacy:](legacy-expand.md) - [Two vaults in one application](two-vaults.md) - [Searchable fields](searchable-fields.md) - [Key purposes and MACs](key-purposes-and-macs.md) - [Macaroons](macaroons.md) - [Threat model](threat-model.md) - [Operations](operations.md) - How-to - [Running against OpenBao in Kubernetes](openbao-in-kubernetes.md) - [Writing a key provider](writing-a-key-provider.md) - [Writing a cipher](writing-a-cipher.md) - [Writing a scope](writing-a-scope.md) - [Writing a rotation policy](writing-a-rotation-policy.md) - Design decisions - [ADR 0001 — AshVault does not build on Cloak.Vault](0001-no-cloak-vault.md) - [ADR 0002 — AshVault distinguishes its crypto failures instead of returning a generic error](0002-distinguishable-crypto-errors.md) ## Modules - [AshVault.Ciphers.OpenBaoTransit](AshVault.Ciphers.OpenBaoTransit.md): The AEAD half of `AshVault.KeyProviders.OpenBaoTransit`: encryption and decryption happen inside OpenBao, so no key material ever enters the BEAM. - [AshVault.Erasure](AshVault.Erasure.md): The record of a completed crypto-erasure: what was erased, and when. - [AshVault.Key](AshVault.Key.md): An opaque handle to key material that may live outside the BEAM heap. - [AshVault.KeyCache](AshVault.KeyCache.md): Behaviour for the storage behind `AshVault.KeyProviders.Cached`. - [AshVault.KeyCaches.ETS](AshVault.KeyCaches.ETS.md): The default `AshVault.KeyCache` backend: a bounded, TTL'd, LRU ETS table. - [AshVault.KeyProviders.Cached](AshVault.KeyProviders.Cached.md): An `AshVault.KeyProvider` that wraps another provider with a bounded, TTL'd key cache. - [AshVault.KeyProviders.OpenBao.Transport](AshVault.KeyProviders.OpenBao.Transport.md): The HTTP, configuration, tombstone and error-classification layer shared by the two OpenBao-backed key providers. - [AshVault.KeyProviders.OpenBaoTransit](AshVault.KeyProviders.OpenBaoTransit.md): An `AshVault.KeyProvider` backed by OpenBao `transit` that **never exports key material**. - [AshVault.Lookup](AshVault.Lookup.md): Deterministic lookup tokens for searchable encrypted fields. - [AshVault.Mix.Shared](AshVault.Mix.Shared.md): Argument parsing, resolution and output helpers shared by the `ash_vault.*` Mix tasks. - [AshVault.Preparations.FilterByLookup](AshVault.Preparations.FilterByLookup.md): Backs the generated `:by_` read action: turns the action's plaintext argument into a filter on `_lookup`. - [AshVault.Query](AshVault.Query.md): Query helpers for searchable encrypted fields. - Extension - [AshVault](AshVault.md): Encrypted attributes for Ash resources. - [AshVault.Dsl](AshVault.Dsl.md): The `ash_vault` DSL section, as consumed by `use Spark.Dsl.Extension` in `AshVault`. - [AshVault.Encrypted](AshVault.Encrypted.md): One encrypted field of a resource — the target struct of the `encrypt` DSL entity. - [AshVault.Info](AshVault.Info.md): Introspection for the `AshVault` extension. - [AshVault.Serializer](AshVault.Serializer.md): The AshVault Plaintext ("AVP") format: the bytes handed to `c:AshVault.Vault.encrypt!/2`. - [AshVault.Telemetry](AshVault.Telemetry.md): The `:telemetry` events AshVault emits, and the rules about what may appear in them. - Extension internals - [AshVault.Actions.DestroyKeys](AshVault.Actions.DestroyKeys.md): Generic action implementation that crypto-erases this scope: every key version for it is destroyed and the scope is tombstoned. - [AshVault.Actions.RotateKey](AshVault.Actions.RotateKey.md): Generic action implementation that rotates this scope's encryption key. - [AshVault.Calculations.Decrypt](AshVault.Calculations.Decrypt.md): Decrypts the `encrypted_` attribute back into a value of the original type. - [AshVault.Changes.Encrypt](AshVault.Changes.Encrypt.md): Encrypts the action argument for one field into its `encrypted_` attribute. - [AshVault.Changes.MirrorLegacy](AshVault.Changes.MirrorLegacy.md): The dual-write of an `encrypt ..., legacy: ...` field, added by `AshVault.Transformers.SetupEncryption` as a global change on every create and update. - [AshVault.Context.Builder](AshVault.Context.Builder.md): Builds `%AshVault.Context{}` values at the Ash boundary — the only place they are constructed. - [AshVault.DecryptFor](AshVault.DecryptFor.md): Evaluates an `encrypt ..., decrypt_for: [...]` list against an actor. - [AshVault.Preparations.PreferVaultCopy](AshVault.Preparations.PreferVaultCopy.md): The dual-read of an `encrypt ..., legacy: ..., decrypt_for: [...]` field, added by `AshVault.Transformers.SetupEncryption` as a global preparation. - [AshVault.Transformers.ExpandAttributes](AshVault.Transformers.ExpandAttributes.md): Expands the `attributes [:a, :b]` sugar into real `%AshVault.Encrypted{}` entities. - [AshVault.Transformers.SetupEncryption](AshVault.Transformers.SetupEncryption.md): Replaces each encrypted attribute with a private ciphertext attribute plus a decrypt calculation, and rewrites the actions that used to accept it. - [AshVault.Transformers.SetupMacaroons](AshVault.Transformers.SetupMacaroons.md): Generates, for every `macaroon` in the `ash_vault` section - [AshVault.Verifiers.VerifyMacaroons](AshVault.Verifiers.VerifyMacaroons.md): Post-compile checks on every `macaroon` in the `ash_vault` section - [AshVault.Verifiers.VerifyVault](AshVault.Verifiers.VerifyVault.md): Post-compile checks on the `ash_vault` section. - Macaroons - [AshVault.Checks.MacaroonAllows](AshVault.Checks.MacaroonAllows.md): A policy check: true when the actor was authenticated by a macaroon and every `phase: :authorize` caveat that macaroon carries admits the action being authorized. - [AshVault.Macaroon](AshVault.Macaroon.md): Macaroons for Ash resources: bearer tokens that any holder can **attenuate** — add caveats that narrow what the token allows — without contacting the issuer, and that the issuer can revoke at three levels. - [AshVault.Macaroon.Actions.Mint](AshVault.Macaroon.Actions.Mint.md): Backs the generated `:mint_` generic action. - [AshVault.Macaroon.Caveat](AshVault.Macaroon.Caveat.md): Behaviour for a caveat check: decides whether one caveat value admits the request. - [AshVault.Macaroon.CaveatCodec](AshVault.Macaroon.CaveatCodec.md): The frozen, self-describing byte encoding of one caveat. - [AshVault.Macaroon.CaveatDefinition](AshVault.Macaroon.CaveatDefinition.md): The target of the `caveat` entity nested in a `macaroon`. See `AshVault.Dsl`. - [AshVault.Macaroon.Caveats.ActionIn](AshVault.Macaroon.Caveats.ActionIn.md): An `:authorize`-phase caveat check: admits the request only if the action being authorized is named in the caveat's list. - [AshVault.Macaroon.Chain](AshVault.Macaroon.Chain.md): The macaroon signature chain. - [AshVault.Macaroon.CheckContext](AshVault.Macaroon.CheckContext.md): What a caveat check is handed alongside the caveat's value. - [AshVault.Macaroon.Clock](AshVault.Macaroon.Clock.md): The clock macaroon expiry is checked against. - [AshVault.Macaroon.Definition](AshVault.Macaroon.Definition.md): The target of the `macaroon` entity in the `ash_vault` section. See `AshVault.Dsl` for the options and [Macaroons](macaroons.md) for the design. - [AshVault.Macaroon.Envelope](AshVault.Macaroon.Envelope.md): The frozen wire format of a macaroon token. - [AshVault.Macaroon.KeyWindow](AshVault.Macaroon.KeyWindow.md): Behaviour for a dynamic `accepted_key_versions`: how many recent `:mac` key versions a scope accepts, decided at verify time. - [AshVault.Macaroon.Preparations.Verify](AshVault.Macaroon.Preparations.Verify.md): Backs the generated `:_by_token` read action, and any read action you declare yourself to sign in with a macaroon. - [AshVault.Macaroon.Runtime](AshVault.Macaroon.Runtime.md): Minting and verifying macaroons for a resource's `macaroon` declaration. - [AshVault.Macaroon.Ttl](AshVault.Macaroon.Ttl.md): Behaviour for a dynamic `default_ttl`: the lifetime of a token, decided at mint time. - [AshVault.Macaroon.Verified](AshVault.Macaroon.Verified.md): What a verified macaroon proved, attached to the loaded record as the `:macaroon` metadata (`record.__metadata__.macaroon`), alongside `using_macaroon?: true`. - Crypto core - [AshVault.Cipher](AshVault.Cipher.md): Behaviour for AEAD ciphers, plus the registry used to resolve a cipher id read out of a stored envelope. - [AshVault.Ciphers.AES.GCM](AshVault.Ciphers.AES.GCM.md): AES-256-GCM, the default AshVault cipher. - [AshVault.Context](AshVault.Context.md): The non-secret context of a single encrypt or decrypt operation. - [AshVault.Envelope](AshVault.Envelope.md): Behaviour for envelope formats, and the dispatcher used to decode stored values. - [AshVault.Envelope.V1](AshVault.Envelope.V1.md): Version 1 of the AshVault envelope wire format. - [AshVault.Mac](AshVault.Mac.md): Behaviour for message authentication codes: the sibling of `AshVault.Cipher` for data that must be *authenticated* rather than *hidden*. - [AshVault.Macs.HmacSha256](AshVault.Macs.HmacSha256.md): HMAC-SHA256 computed in process, over a raw 32-byte `:mac` key. - [AshVault.Macs.OpenBaoTransit](AshVault.Macs.OpenBaoTransit.md): The MAC half of `AshVault.KeyProviders.OpenBaoTransit`: HMAC-SHA256 computed inside OpenBao, so the `:mac` key never enters the BEAM. - [AshVault.Vault](AshVault.Vault.md): Defines a vault: the bundle of key provider, cipher, envelope, scope and rotation policy that an application encrypts with. - [AshVault.Vault.Runtime](AshVault.Vault.Runtime.md): The implementation behind every module that `use`s `AshVault.Vault`. - Key providers - [AshVault.KeyProvider](AshVault.KeyProvider.md): Behaviour for key providers: the components that mint, serve, rotate and destroy the symmetric keys AshVault encrypts with. - [AshVault.KeyProviders.Local](AshVault.KeyProviders.Local.md): A filesystem-backed `AshVault.KeyProvider` for single-node deployments. - [AshVault.KeyProviders.Memory](AshVault.KeyProviders.Memory.md): An in-memory `AshVault.KeyProvider`, backed by a `GenServer`. - [AshVault.KeyProviders.OpenBao](AshVault.KeyProviders.OpenBao.md): An `AshVault.KeyProvider` backed by [OpenBao](https://openbao.org) (or Vault) `transit`. - [AshVault.KeyProviders.OpenBao.KubernetesAuth](AshVault.KeyProviders.OpenBao.KubernetesAuth.md): A supervised OpenBao token holder for the Kubernetes auth method. - Scopes - [AshVault.Scope](AshVault.Scope.md): Behaviour for resolving the *encryption scope* of an operation. - [AshVault.Scopes.AshTenant](AshVault.Scopes.AshTenant.md): Scopes encryption keys to the Ash tenant of the operation. - [AshVault.Scopes.Global](AshVault.Scopes.Global.md): A constant encryption scope, `"global"`, for applications that are not multitenant. - Rotation - [AshVault.RotationPolicies.Manual](AshVault.RotationPolicies.Manual.md): The default rotation policy: never rotate automatically. - [AshVault.RotationPolicy](AshVault.RotationPolicy.md): Describes when a scope's key should be rotated, and the behaviour that supplies it. - Migration - [AshVault.Backfill](AshVault.Backfill.md): The online backfill engine behind `mix ash_vault.backfill` and `mix ash_vault.verify`. - Errors - [AshVault.Errors](AshVault.Errors.md): Error structs raised and returned by the AshVault crypto core. - [AshVault.Errors.CiphertextIntegrityFailed](AshVault.Errors.CiphertextIntegrityFailed.md): Raised when the AEAD authentication tag does not verify. - [AshVault.Errors.InvalidCiphertext](AshVault.Errors.InvalidCiphertext.md): Raised when a stored value is not a well-formed AshVault envelope. - [AshVault.Errors.InvalidMac](AshVault.Errors.InvalidMac.md): Raised by `verify_mac!` when a tag does not verify. - [AshVault.Errors.InvalidMacaroon](AshVault.Errors.InvalidMacaroon.md): Raised or returned when a macaroon does not verify, and the reason is the token itself. - [AshVault.Errors.InvalidScope](AshVault.Errors.InvalidScope.md): Raised when an `AshVault.Scope` implementation returns something other than a binary. - [AshVault.Errors.KeyDestroyed](AshVault.Errors.KeyDestroyed.md): Raised when the key needed to decrypt a value was deliberately destroyed. - [AshVault.Errors.KeyNotFound](AshVault.Errors.KeyNotFound.md): Raised when the key provider has no key for the requested scope and version, and no tombstone recording that it was destroyed. - [AshVault.Errors.KeySizeMismatch](AshVault.Errors.KeySizeMismatch.md): Raised when the key material a provider supplies is not the size the cipher requires. - [AshVault.Errors.MacaroonRevoked](AshVault.Errors.MacaroonRevoked.md): Returned when a macaroon verified once and has since been revoked. `:reason` names the level that revoked it - [AshVault.Errors.MissingScope](AshVault.Errors.MissingScope.md): Raised when the encryption scope for a field could not be resolved. - [AshVault.Errors.ProviderForbidden](AshVault.Errors.ProviderForbidden.md): Raised when the key store answered and **refused** the request: OpenBao's `403 permission denied`. - [AshVault.Errors.ProviderUnavailable](AshVault.Errors.ProviderUnavailable.md): Raised when the key provider could not be reached or failed for a transient reason. - [AshVault.Errors.PurposeUnsupported](AshVault.Errors.PurposeUnsupported.md): Raised when the key provider cannot serve keys for a purpose — typically a vault asked to `mac!` over a provider whose `c:AshVault.KeyProvider.purposes/0` does not list `:mac`, or a third-party provider written before purposes existed. - [AshVault.Errors.SerializationFailed](AshVault.Errors.SerializationFailed.md): Raised when a value could not be dumped to (or cast back from) its embedded representation while being encrypted or decrypted. - [AshVault.Errors.UnsupportedCipher](AshVault.Errors.UnsupportedCipher.md): Raised when an envelope names a cipher that is not present in the cipher registry. - [AshVault.Errors.UnsupportedEnvelope](AshVault.Errors.UnsupportedEnvelope.md): Raised when an envelope carries a version byte this build does not know how to parse. - Exceptions - [AshVault.Errors.LookupNormalizationFailed](AshVault.Errors.LookupNormalizationFailed.md): Raised when a searchable field's `normalize:` strategy did not produce a binary. - [AshVault.Errors.LookupUnsupported](AshVault.Errors.LookupUnsupported.md): Raised when a lookup token is needed but the key provider cannot supply a lookup key. - [AshVault.Errors.OpaqueKeyUnsupported](AshVault.Errors.OpaqueKeyUnsupported.md): Raised when a key provider returned an opaque `AshVault.Key` handle to a cipher that can only work on raw key bytes. ## Mix Tasks - [mix ash_vault.backfill](Mix.Tasks.AshVault.Backfill.md): Encrypt an existing plaintext column into its `encrypted_` column, online. - [mix ash_vault.destroy_keys](Mix.Tasks.AshVault.DestroyKeys.md): Cryptographically erase an AshVault scope. - [mix ash_vault.key_info](Mix.Tasks.AshVault.KeyInfo.md): Report the key state of an AshVault scope: which provider serves it, what it is called there, its current version, when that version was minted, which historical versions are still fetchable, and whether the scope has been crypto-erased. - [mix ash_vault.local.init](Mix.Tasks.AshVault.Local.Init.md): Create and initialise a key root for `AshVault.KeyProviders.Local`. - [mix ash_vault.rotate](Mix.Tasks.AshVault.Rotate.md): Mint a new key version for a scope. - [mix ash_vault.verify](Mix.Tasks.AshVault.Verify.md): Verify a backfill: decrypt a sample of rows and compare them to the plaintext column they were encrypted from. - Migration - [mix ash_vault.openbao.init_retirement](Mix.Tasks.AshVault.Openbao.InitRetirement.md): Activate a retirement-plugin mount after importing every existing KV tombstone. - [mix ash_vault.openbao.migrate_namespace](Mix.Tasks.AshVault.Openbao.MigrateNamespace.md): Move a binary scope whose base64url representation starts with `nx_` to the disjoint exporting-provider namespace, preserving every key version and tombstone.