A cipher turns (plaintext, key, aad) into (ciphertext, nonce, tag) and back. AshVault
ships one, AshVault.Ciphers.AES.GCM, and you should have a specific reason before adding
another — a hardware requirement, a compliance rule naming a different algorithm, or a
migration away from one.
The contract
@type payload :: %{ciphertext: binary(), nonce: binary(), tag: binary()}
@callback id() :: atom()
@callback key_bytes() :: pos_integer()
@callback encrypt(plaintext :: binary(), key :: binary(), aad :: binary()) ::
{:ok, payload()} | {:error, term()}
@callback decrypt(payload(), key :: binary(), aad :: binary()) ::
{:ok, binary()} | {:error, term()}Rules:
id/0is forever. It is written into every envelope and is how a value is matched back to the code that can open it. Version it in the name (:aes_256_gcm_v1), and if you change the algorithm, parameters, or framing in any observable way, mint a new id rather than redefining the old one. Values already in the database still say the old id.- It must be an AEAD.
aadis not optional decoration: it is"ashvault:v1|<scope>|<Resource>|<field>", and binding it into the tag is what stops a ciphertext being relocated between tenants, resources and columns. A cipher that ignoresaadsilently removes threats 4, 5 and 6 from the threat model. - Fresh nonce per encryption. Never a counter derived from anything in the row. GCM nonce reuse under the same key is catastrophic — it leaks the XOR of two plaintexts and the authentication subkey.
key_bytes/0must be exact.AshVault.Vault.verify_key_sizes!/2compares it with the provider'skey_bytes/0at compile time where it can, andAshVault.Vault.RuntimeraisesAshVault.Errors.KeySizeMismatchat the point of use where it cannot.- Error vocabulary. Return
{:error, {:invalid_key_size, n}}for a wrong-size key and{:error, :auth_failed}(or any other term) for a verification failure. The first is mapped toAshVault.Errors.KeySizeMismatch— a configuration fault, not retryable and not tampering; everything else becomesAshVault.Errors.CiphertextIntegrityFailed. Getting this backwards tells an operator their data was tampered with when they made a typo inconfig/runtime.exs.
Failure modes that matter
Validate nonce and tag lengths yourself, before :crypto
This is the single sharpest edge in the whole cipher layer, and it is not obvious.
The envelope stores nonce_len and tag_len as bytes read straight out of the database.
:crypto.crypto_one_time_aead/7 on OTP 29 accepts a truncated GCM tag — verified: 1,
2, 4, 8 and 12-byte tags all return plaintext, compared only over their leading bytes;
only a 0-byte tag is rejected. GCM is CTR mode, so an attacker with database write access
can XOR the ciphertext to any chosen plaintext, store tag_len: 1, and enumerate 256
values. Success is guaranteed within 256 read attempts.
Likewise a short nonce is a perfectly valid input to the primitive: OTP derives J0 by GHASHing anything that is not 96 bits, so a 1-byte nonce widens the space an attacker controls rather than erroring.
So check both, before the key touches :crypto:
defp validate_nonce(nonce) when byte_size(nonce) == @nonce_bytes, do: :ok
defp validate_nonce(_nonce), do: {:error, :auth_failed}
defp validate_tag(tag) when byte_size(tag) == @tag_bytes, do: :ok
defp validate_tag(_tag), do: {:error, :auth_failed}Do not make these configurable. A per-vault tag_bytes option is an invitation to
downgrade the forgery bound in config.
Do not let :crypto raise through
:crypto raises on some malformed inputs. decrypt/3 is called with bytes from the
database, so wrap it:
defp safe_decrypt(ciphertext, key, nonce, tag, aad) do
:crypto.crypto_one_time_aead(@cipher, key, nonce, ciphertext, aad, tag, false)
rescue
_ -> :error
endA FunctionClauseError or an ErlangError escaping the cipher is an unhelpful 500 where
a CiphertextIntegrityFailed belonged.
Add a total fallback clause
def decrypt(_payload, _key, _aad), do: {:error, :auth_failed}A payload map that does not have the three expected binary keys is not a decryptable payload; say so as a value rather than a match error.
A worked example
ChaCha20-Poly1305: 32-byte keys, 12-byte nonces, 16-byte tags.
defmodule MyApp.Ciphers.ChaCha20Poly1305 do
@moduledoc """
ChaCha20-Poly1305 for AshVault.
32-byte keys, fresh 12-byte nonces per encryption, 16-byte tags. The AshVault
associated data is bound into the tag, so a value only decrypts under the same
scope, resource and field.
"""
@behaviour AshVault.Cipher
@cipher :chacha20_poly1305
@key_bytes 32
@nonce_bytes 12
@tag_bytes 16
@impl AshVault.Cipher
def id, do: :chacha20_poly1305_v1
@impl AshVault.Cipher
def key_bytes, do: @key_bytes
@impl AshVault.Cipher
def encrypt(plaintext, key, aad)
when is_binary(plaintext) and is_binary(key) and is_binary(aad) do
with :ok <- validate_key(key) do
nonce = :crypto.strong_rand_bytes(@nonce_bytes)
{ciphertext, tag} =
:crypto.crypto_one_time_aead(@cipher, key, nonce, plaintext, aad, true)
{:ok, %{ciphertext: ciphertext, nonce: nonce, tag: tag}}
end
end
@impl AshVault.Cipher
def decrypt(%{ciphertext: ciphertext, nonce: nonce, tag: tag}, key, aad)
when is_binary(ciphertext) and is_binary(nonce) and is_binary(tag) and
is_binary(key) and is_binary(aad) do
with :ok <- validate_key(key),
:ok <- validate_nonce(nonce),
:ok <- validate_tag(tag) do
case safe_decrypt(ciphertext, key, nonce, tag, aad) do
plaintext when is_binary(plaintext) -> {:ok, plaintext}
_other -> {:error, :auth_failed}
end
end
end
def decrypt(_payload, _key, _aad), do: {:error, :auth_failed}
defp safe_decrypt(ciphertext, key, nonce, tag, aad) do
:crypto.crypto_one_time_aead(@cipher, key, nonce, ciphertext, aad, tag, false)
rescue
_ -> :error
end
defp validate_key(key) when byte_size(key) == @key_bytes, do: :ok
defp validate_key(key), do: {:error, {:invalid_key_size, byte_size(key)}}
defp validate_nonce(nonce) when byte_size(nonce) == @nonce_bytes, do: :ok
defp validate_nonce(_nonce), do: {:error, :auth_failed}
defp validate_tag(tag) when byte_size(tag) == @tag_bytes, do: :ok
defp validate_tag(_tag), do: {:error, :auth_failed}
endRegistering it
Two steps. First, put it in the registry so decryption can find it by id — the registry is keyed by the binary id, exactly what the envelope stores:
# config/config.exs
config :ash_vault, :ciphers, %{
"chacha20_poly1305_v1" => MyApp.Ciphers.ChaCha20Poly1305
}Then point a vault at it so new writes use it:
defmodule MyApp.Vault do
use AshVault.Vault,
key_provider: MyApp.KeyProviders.Sql,
cipher: MyApp.Ciphers.ChaCha20Poly1305
endRegistry and vault are separate on purpose. Leaving the old cipher in the registry is
how existing rows keep decrypting after you switch the default — AshVault.Vault.Runtime
resolves the cipher from the envelope, never from the vault's configuration. Remove a
cipher from the registry only once nothing in the database names it; until then a row
carrying it fails with:
Unsupported cipher: "chacha20_poly1305_v1".
Register it under `config :ash_vault, :ciphers, %{...}` if this build should support it.There is no migration tool for re-encrypting old rows onto a new cipher. The mechanism is the same as for rotation: read and re-save the rows, which re-encrypts them with the vault's current cipher and current key.
Testing it
test/ash_vault/ciphers/aes_gcm_test.exs and test/ash_vault/cipher_test.exs are the
model. At minimum assert:
- roundtrip, including empty plaintext and a large (1MB) plaintext;
- a flipped ciphertext byte fails; a flipped tag byte fails; a flipped nonce byte fails;
- the wrong key fails;
- a different AAD fails — this is the one that proves relocation is impossible;
- 1000 encryptions produce 1000 distinct nonces;
- a key of the wrong size returns
{:error, {:invalid_key_size, n}}, not:auth_failed; - a truncated tag (1, 2, 4, 8, 12 bytes) is rejected, and so is a short nonce;
AshVault.Cipher.fetch("your_id")returns your module once registered.
Related
AshVault.Cipher,AshVault.Ciphers.AES.GCM- Architecture — where the AAD comes from
- Threat model