A vault is resolved at compile time. use AshVault.Vault bakes the key provider,
cipher, envelope, scope and rotation policy into the module, and every call site is a
plain module call into AshVault.Vault.Runtime. There is no runtime provider switch, and
there is not going to be one.
That is a deliberate trade, and it buys two things:
- The key-size check.
AshVault.Vault.verify_key_sizes!/2compares the provider'skey_bytes/0against the cipher's while the vault module is being compiled. Akey_type: "aes128-gcm96"under a 256-bit cipher is anArgumentErrorat compile time rather than anAshVault.Errors.CiphertextIntegrityFailedin production — an error that tells an operator their data was tampered with, over a config typo. A vault assembled at runtime from a config value cannot be checked this way. - A provider call that is a module call. The four provider call sites in
AshVault.Vault.Runtimestay direct dispatch, with no resolution step on the path of every encrypt and every decrypt.
One vault per application is the normal case, and it is the case this library is shaped for. If that is you, stop reading: name one vault module, point your resources at it, and nothing below applies.
When you actually need two
Two situations, both real:
- Migrating between key providers — moving from
AshVault.KeyProviders.LocaltoAshVault.KeyProviders.OpenBao, where both have to be live at once while keys move. - Demonstrating or testing several providers against one set of resources — which is
what AshVault's own acceptance suite does, and what the
example/application does.
The supported answer is: two vault modules and a fun/2 resolver. The vault DSL entry
already accepts a fun/2, and it is called with the resource and the normalized
ash_context on the write path, the read path and the key-lifecycle actions alike.
The pattern
defmodule MyApp.Vault.Local do
use AshVault.Vault, key_provider: AshVault.KeyProviders.Local
end
defmodule MyApp.Vault.Bao do
use AshVault.Vault, key_provider: AshVault.KeyProviders.OpenBao
end
defmodule MyApp.Vault do
@moduledoc "Which vault the application is currently encrypting with."
@spec current() :: module()
def current do
case Application.get_env(:my_app, :key_provider, "openbao") do
"local" -> MyApp.Vault.Local
_ -> MyApp.Vault.Bao
end
end
@doc "The `fun/2` vault form the resources declare."
@spec resolve(module() | Spark.Dsl.t(), term()) :: module()
def resolve(_resource, _context), do: current()
endand in each resource:
ash_vault do
vault &MyApp.Vault.resolve/2
scope :tenant
encrypt :email
endSupervision and setup go through whichever vault is current, so they stay one line each —
MyApp.Vault.current() answers for its own provider:
# lib/my_app/application.ex
children = [MyApp.Repo] ++ MyApp.Vault.current().child_specs()
# a deploy step
:ok = MyApp.Vault.current().setup()The hazard
The resolver must be stable for the lifetime of a row. A value written through one
vault and read through another is decrypted with the wrong provider's key material, and
what surfaces is AshVault.Errors.CiphertextIntegrityFailed — "the stored bytes were
modified". It is the correct error for what the crypto layer observed and a completely
misleading one for what happened, and it is indistinguishable from a real tampering
finding.
It is worse than misleading in one specific place: it looks like a passing crypto-erasure assertion. A test that erases a tenant and then asserts the read fails will pass just as happily when the read failed because the resolver flipped between the write and the read. AshVault's own acceptance suite therefore asserts, before doing anything else, that the resolver hands back the vault the test thinks it is testing:
setup do
MyApp.VaultResolver.put(MyApp.Vault.Bao)
assert MyApp.VaultResolver.resolve(MyApp.Accounts.User, %{}) == MyApp.Vault.Bao
:ok
endDo the same. A resolver keyed on anything request-scoped — an actor, a header, a process dictionary entry — will eventually read a row it did not write, so key it on something deployment-scoped (application config, a node name, an environment variable read at boot) and change it only with a migration that re-encrypts.
What a migration between providers looks like
- Add the second vault module alongside the first; leave the resolver returning the old one. Nothing has changed yet.
- Start the new provider (
child_specs/0) and run its setup (setup/0). - Flip the resolver. New writes go to the new provider; old rows do not move, and they now fail to decrypt, so this step alone is not a migration.
- Re-encrypt: read every row through the old vault and write it through the new one. Use
AshVault.Backfillwith the old vault as the source, or a one-off task that callsencrypt!/2anddecrypt!/2on the two vault modules explicitly — both vaults are ordinary modules and you can call either directly. - Once no row remains under the old provider, delete the old vault module and the resolver, and point the resources at the new vault by name.
Step 4 is the whole job; steps 1 to 3 are five minutes. Budget accordingly.