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/0 is 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. aad is 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 ignores aad silently 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/0 must be exact. AshVault.Vault.verify_key_sizes!/2 compares it with the provider's key_bytes/0 at compile time where it can, and AshVault.Vault.Runtime raises AshVault.Errors.KeySizeMismatch at 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 to AshVault.Errors.KeySizeMismatch — a configuration fault, not retryable and not tampering; everything else becomes AshVault.Errors.CiphertextIntegrityFailed. Getting this backwards tells an operator their data was tampered with when they made a typo in config/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
end

A 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}
end

Registering 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
end

Registry 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.