barrel_keyprovider behaviour (barrel_crypto v1.0.0)

View Source

Key provider behaviour and dispatcher for Barrel encryption at rest.

A provider maps a database KEYSPACE to a 256-bit key. The keyspace is the identity data is stored under: a timeline branch shares its parent's keyspace, so it resolves the parent's key and can read the checkpointed ciphertext. One logical database resolves one key across all of its stores.

Callers carry an encryption spec, runtime config supplied at each open:

  • disabled: no encryption (the default)
  • default: the built-in barrel_keyprovider_env provider (BARREL_ENCRYPTION_KEY)
  • #{provider := Mod}: a module implementing this behaviour, for KMS or token-derived keys

Resolution is fail closed: a provider error fails the database open.

Summary

Types

spec/0

Callbacks

key_for_db/1

Functions

key_for_db(Spec, Keyspace)

Resolve the key for a keyspace under the given spec. disabled resolves to the atom plaintext; providers must return a 32-byte key. Error terms never carry key material.

Types

spec/0

-type spec() :: disabled | default | #{provider := module(), _ => _}.

Callbacks

key_for_db/1

-callback key_for_db(Keyspace :: binary()) -> {ok, binary()} | {error, term()}.

Functions

key_for_db(Spec, Keyspace)

-spec key_for_db(spec(), binary()) -> {ok, plaintext} | {ok, binary()} | {error, term()}.

Resolve the key for a keyspace under the given spec. disabled resolves to the atom plaintext; providers must return a 32-byte key. Error terms never carry key material.