Zero to an encrypted attribute, ending with you looking at the ciphertext in your own database.
By the end you will have: a key provider running, a vault, a resource with an encrypted
:email, a row you can read back as plaintext through Ash, and a psql query proving the
column holds an AshVault envelope and no trace of the email address.
Assumed: an existing Phoenix or Elixir app with Ash and ash_postgres already working.
1. Add the dependency
# mix.exs
def deps do
[
{:ash, "~> 3.0"},
{:ash_postgres, "~> 2.0"},
{:ash_vault, "~> 0.2.0"}
]
endmix deps.getAdd AshVault to your formatter so the DSL formats correctly:
# .formatter.exs
[
import_deps: [:ash, :ash_postgres, :ash_vault],
...
]2. Pick a key provider
This is the one decision that matters, and the whole guarantee rests on it: the key store must be a different system from the database, so that restoring a database backup cannot restore the keys.
| Provider | Use it for |
|---|---|
AshVault.KeyProviders.Memory | tests only — keys die with the process |
AshVault.KeyProviders.Local | single-node deployments, homelab, dev with persistence |
AshVault.KeyProviders.OpenBao | production, multi-node |
We will use Local: it persists across restarts (so your data survives an iex restart,
which Memory would not), it needs no extra infrastructure, and it makes the "keys live
somewhere else" requirement concrete — it is a directory you can point at.
Create the key root. This is an explicit, one-time operator step:
mix ash_vault.local.init priv/ash_vault_keysInitialised AshVault key root: /home/you/my_app/priv/ash_vault_keys
mode: 0700
sentinel: .ash_vault_root
Back this directory up separately from the database, and exclude it from the
database backup job. See the AshVault.KeyProviders.Local moduledoc.priv/ is fine for development and wrong for production
In production the key root belongs on its own volume, excluded from the database backup
job — /var/lib/my_app/ash_vault_keys, say. If the keys and the database ever land in
the same tarball, crypto-erasure is defeated. Add priv/ash_vault_keys/ to your
.gitignore now, before you forget.
Configure it and start it:
# config/runtime.exs — under your own OTP application, not AshVault's
config :my_app, AshVault.KeyProviders.Local,
root: System.get_env("ASH_VAULT_KEY_ROOT", "priv/ash_vault_keys")# lib/my_app/application.ex
def start(_type, _args) do
children =
[MyApp.Repo] ++ MyApp.Vault.child_specs() ++ [MyAppWeb.Endpoint]
Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)
endMyApp.Vault.child_specs/0 answers for whichever provider the vault was built with, so
this line does not change when you move from Local to OpenBao — Local is a
GenServer and contributes itself, OpenBao is stateless HTTP and contributes nothing.
The provider also needs a one-time operator step, which is deliberately not something a supervisor does on every boot. One line again, for any provider:
# a deploy step, a release command, or a `mix my_app.setup` task
:ok = MyApp.Vault.setup()For AshVault.KeyProviders.Local that creates the key root and its .ash_vault_root
sentinel; for AshVault.KeyProviders.OpenBao it mounts the KV-v2 engine that holds
tombstones; for AshVault.KeyProviders.Memory it does nothing and returns :ok.
AshVault.KeyProviders.Local never creates its own key root as a side effect of starting;
if the directory or its .ash_vault_root sentinel is missing it refuses to start, which is
what stops an unmounted key volume from looking like a pristine, empty key store.
3. Define a vault
A vault bundles the key provider with a cipher, an envelope format, a scope and a rotation policy. Only the provider is required:
# lib/my_app/vault.ex
defmodule MyApp.Vault do
use AshVault.Vault, key_provider: AshVault.KeyProviders.Local
endThe defaults are AshVault.Ciphers.AES.GCM, AshVault.Envelope.V1,
AshVault.Scopes.AshTenant and AshVault.RotationPolicies.Manual — AES-256-GCM,
per-tenant keys, rotate only when asked. That is the right starting point.
4. Add ash_vault to a resource
# lib/my_app/accounts/user.ex
defmodule MyApp.Accounts.User do
use Ash.Resource,
domain: MyApp.Accounts,
data_layer: AshPostgres.DataLayer,
extensions: [AshVault]
ash_vault do
vault MyApp.Vault
encrypt :email
decrypt_by_default [:email]
end
postgres do
table "users"
repo MyApp.Repo
end
multitenancy do
strategy :attribute
attribute :org_id
end
attributes do
uuid_primary_key :id
attribute :org_id, :uuid, allow_nil?: false, public?: true
attribute :name, :string, public?: true
attribute :email, :string, public?: true
end
actions do
default_accept :*
defaults [:read, :destroy, create: :*]
update :update do
primary? true
require_atomic? false
end
end
endFour things to notice:
encrypt :emailreplaces the attribute. At compile time the:emailattribute is removed and replaced by a privateencrypted_email:binaryattribute plus an:emailcalculation that decrypts. There is no plaintext column, so no data layer can write one. You still declareattribute :email, :string— that declaration is what tells AshVault the type, the constraints and the nullability to preserve.decrypt_by_default [:email]loads the decrypt calculation automatically. Without it you load:emailexplicitly, like any other calculation.- The default scope is the Ash tenant, so this resource needs multitenancy — here,
attribute multitenancy on
org_id. Every read and write must pass a tenant. (If you are not multitenant, see the note at the end.) require_atomic? falseis not required —AshVault.Changes.Encryptimplementsatomic/3and both paths scrub the plaintext from the changeset. It is here because most resources have other non-atomic changes; drop it if yours does not.
5. Generate and run the migration
mix ash.codegen add_encrypted_users
mix ash.migrateThe generated migration creates encrypted_email bytea and no email column — the
attribute is gone by the time codegen sees the resource. Schema migrations like this need
no keys at all.
6. Write and read
iex -S mixorg_id = Ecto.UUID.generate()
user =
MyApp.Accounts.User
|> Ash.Changeset.for_create(:create, %{org_id: org_id, name: "Ada", email: "ada@example.com"},
tenant: org_id
)
|> Ash.create!()
user.email
#=> "ada@example.com"The key was minted on that first write — version 1, created by current_key/1, with no
explicit setup step.
Read it back:
[found] = Ash.read!(MyApp.Accounts.User, tenant: org_id)
found.email
#=> "ada@example.com"decrypt_by_default loaded the calculation. Without it:
MyApp.Accounts.User
|> Ash.Query.load([:email])
|> Ash.read!(tenant: org_id)7. Verify the column holds ciphertext
This is the step that matters. Look at the raw bytes:
%{rows: [[blob]]} = MyApp.Repo.query!("SELECT encrypted_email FROM users LIMIT 1")
# An AshVault envelope: "AV" magic, then the envelope version byte.
<<"AV", 1::8, _rest::binary>> = blob
# And no trace of the plaintext anywhere in it.
String.contains?(blob, "ada@example.com")
#=> false
String.contains?(blob, "example.com")
#=> falseThere is no plaintext column at all:
MyApp.Repo.query!("""
SELECT column_name FROM information_schema.columns
WHERE table_name = 'users' AND column_name = 'email'
""").rows
#=> []Decode the envelope to see what it actually carries — everything needed to decrypt except the key itself:
AshVault.Envelope.decode(blob)
#=> {:ok,
#=> %{
#=> version: 1,
#=> cipher: "aes_256_gcm_v1",
#=> key_version: 1,
#=> nonce: <<...12 bytes...>>,
#=> tag: <<...16 bytes...>>,
#=> ciphertext: <<...>>
#=> }}That key_version: 1 is what makes rotation cheap: rotate the tenant's key and this row
keeps decrypting with version 1 while new writes use version 2.
And the key material is where you put it, not in the database:
$ ls priv/ash_vault_keys/
.ash_vault_root <base64-of-the-tenant-id>
$ ls priv/ash_vault_keys/<base64-of-the-tenant-id>/
meta.json v1.key
AshVault.KeyProviders.Local.scope_dir(org_id)
#=> the directory name for that tenant8. See what erasure does
The reason for all of this. Destroy the tenant's keys:
:ok = AshVault.destroy_keys!(MyApp.Vault, org_id)Now read:
Ash.read(MyApp.Accounts.User, tenant: org_id)
#=> {:error, %Ash.Error.Invalid{errors: [%AshVault.Errors.KeyDestroyed{...}]}}Encryption key for scope "<org_id>" (version 1) has been destroyed.
This data was cryptographically erased and cannot be recovered.The row is still there. Its bytes are unchanged. Every backup you have taken still contains it — and none of them can be read. That is the whole library.
Note what the error is not: it is not CiphertextIntegrityFailed (which would mean
tampering) and not ProviderUnavailable (which would mean retry). Destruction is checked
before any decryption is attempted, and the provider records a tombstone so the tenant can
never be silently re-minted — even if someone restores an old key directory over the top,
the tombstone sits beside the scope directory rather than inside it.
In production this is a mix task with real guardrails — it makes you type the scope back,
and --yes does not skip that:
mix ash_vault.destroy_keys MyApp.Accounts.Organization --tenant <org_id>Where to go next
- Architecture — what the five layers do and why the envelope carries a key version
- Tenant-scoped encryption — how the tenant becomes a key, and the scope-agreement rule the verifier enforces
- Crypto-erasure — the guarantee in detail, plus the operational checklist to run through before you rely on it
- Threat model — read the non-goals before you promise anyone anything
- Operations — provider setup, backups, and every error
- Migrating from plaintext — if the column already has data in it
Notes and gotchas
If you are not multitenant, use the global scope. Both the vault and the resource must say so — the verifier requires the resource to restate a non-default scope:
defmodule MyApp.Vault do
use AshVault.Vault,
key_provider: AshVault.KeyProviders.Local,
scope: AshVault.Scopes.Global
end
ash_vault do
vault MyApp.Vault
scope :global
encrypt :email
endOne key lineage for the whole application, so rotation and erasure are application-wide.
You cannot filter or sort on an encrypted field. The decrypt calculation is
filterable?: false, sortable?: false, because randomized AEAD ciphertext supports
neither. See Searchable fields.
Every read and write needs a tenant, including background jobs and mix tasks. Without
one you get AshVault.Errors.MissingScope:
Cannot encrypt MyApp.Accounts.User.email because no Ash tenant was present.
This resource uses tenant-scoped encryption.
Pass a tenant when executing the Ash action or configure another AshVault scope.Do not lose the key directory. In this tutorial it is under priv/, which means a
git clean -xfd destroys every encrypted value you have written. That is the correct
behaviour — it is just cheaper to learn here than in production.