HKDF-SHA256 key derivation: the one place this package expands a key into a labelled subkey.

This module is the primitive underneath ADR-0003 decisions 6 and 7. It holds no state, reads no configuration, touches no vault, and depends on nothing but :crypto. Everything above it - the root vault's wrapping material, the tenant reference subkey, and any purpose-separated subkey of a tenant master key - is a call into derive_subkey/3 with a different purpose.

Expand only on the wrapping trees, and why

RFC 5869 splits HKDF into extract (condense arbitrary, possibly biased input keying material into a pseudorandom key) and expand (stretch a pseudorandom key into labelled output). Both are implemented here, and they are not used on the same trees.

"encryptor/v1/root-wrap" and "encryptor/v1/tenant-ref" are expand only, because every input those two derive from is already a uniformly random key of at least 256 bits:

• the root key material is supplied to the host vault's init/1 as deployment-supplied key material (ADR-0001 decision 5), and
• a tenant master key is 32 bytes from the CSPRNG, generated once and never derived (ADR-0003 decision 1).

RFC 5869 section 3.3 names exactly this case - "if the input key material is already a good pseudorandom key" - as the one where the extract step may be skipped. Both accepted records say HKDF-Expand rather than HKDF, and those two trees implement what they say. Salting them would change the root vault's provider material and every stored tenant_ref, which is a rewrap of every stored wrapping and a re-index of every stored row.

The 32-byte guard on the pseudorandom key is what makes that reasoning enforceable rather than aspirational: a caller cannot expand from a short or low-entropy input by accident.

The salted tree

ADR-0003 amendment A (proposed, 2026-08-28) adds extract/2 and one tree that uses it: the derived-subkey surface a downstream consumer reaches through Encryptor.Vault.derive/3. Its output leaves this package, so it is salted with a per-deployment value that the consumer cannot supply, and two deployments provisioned from the same tenant key material derive unrelated subkeys.

salted_subkey/5 is that whole construction, and it is deliberately three steps rather than two:

PRK         = HKDF-Extract(salt, key_material)
purpose_key = HKDF-Expand(PRK, "encryptor/v1/<purpose>", 32)
derived     = HKDF-Expand(purpose_key, caller_info, length)

The label and the caller's info are never concatenated into one expansion, because purpose "a" with info "b" and purpose "ab" with info "" would spell the same string, and that collision is the label reuse ADR-0003 decision 6 forbids. The nesting is unambiguous: the purpose is consumed by a whole expansion before the caller's info is read.

The final expansion always runs, including when info is "". That costs one HMAC and keeps purpose_key from ever leaving the package: every byte a caller receives is one expansion further from the tree's root than anything held internally.

The label grammar

Every derivation in this package is labelled, and the label is composed here rather than at the call site:

"encryptor/" <> version <> "/" <> purpose

The version is currently v1. label/1 is the only thing that writes that prefix, so a caller supplies the purpose - "root-wrap", "tenant-ref" - and cannot spell the namespace differently by hand.

ADR-0003 decision 6 fixes two purposes and reserves the rest of the space:

The reservation is one-way. Any future purpose-separated key takes a new "encryptor/v<n>/<purpose>" label and never reuses an existing one (ADR-0003 decision 6). Reusing a label to mean a second thing is what silently collapses two keys that the design says are independent.

One use is deliberately unlabelled: a tenant master key is used directly as RawAes material on the encryption path. That use predates and defines the key, and labelling it would invalidate every stored ciphertext (ADR-0003 decision 7).

What domain separation buys, and what it does not

HKDF-Expand with distinct info strings under one pseudorandom key yields outputs that are computationally independent: an adversary holding one derived subkey learns nothing usable about another, and cannot recover the key they were expanded from. Three guarantees follow, and they are the reason the labels exist:

• Independent lifecycles. The wrapping subkey can be replaced by a rewrap pass while every stored tenant_ref stays valid, because the two are separate expansions of the same material (ADR-0003 decision 6).
• No cross-purpose reuse. A subkey derived for one purpose is not the key any other purpose uses, so a component handed one of them cannot perform the other's operation with it.
• Shred semantics are inherited, not weakened. A derived subkey is never stored; it is recomputed on demand from the key it was expanded from. Destroying that key destroys every subkey of it (ADR-0003 decision 7).

What it does not buy is capability separation. Deriving a subkey requires the key it is expanded from, so a component that can derive a tenant's index key necessarily holds that tenant's master key and can therefore also decrypt. ADR-0003 decision 7 states this plainly and holds the door open for independently wrapped, independently stored keys if a genuine search-only capability is ever wanted. Nothing in this module provides one.

Nested derivation

expand/3 takes the info string verbatim, which is what lets a consumer derive within a purpose it was given. A downstream package that owns a purpose-separated key tree derives its own key under this package's label first, then expands again under its own info string:

index_key = Encryptor.Kdf.derive_subkey(tenant_master_key, "blind-index")
field_key = Encryptor.Kdf.expand(index_key, downstream_info, 32)

Both steps are HKDF-Expand and the outer label stays this package's, so the reservation above still holds over the whole tree. What the inner info string is, and what it identifies, belongs to whichever package owns that tree; this module only makes the nesting expressible.

Why these functions raise rather than return {:error, _}

The package convention is that a function which can fail returns {:ok, value} | {:error, %Encryptor.Error{}}. Nothing here can fail at runtime. A too-short key, an empty purpose, a purpose containing the separator, an output length past the RFC bound: each is a caller-supplied constant that is wrong in the source, not an event that happens to a correct program. ADR-0003's contract agrees - root_subkey/2 and subkey/2 are specified returning a bare binary(), with no error half to return into.

Every raised message names the constraint and never the value, because a key-length violation is the one place a raise could otherwise put key material into a log line or a test failure report.

Records: ADR-0003 decisions 5, 6, 7 and amendment A. RFC 5869 sections 2.2, 2.3 and 3.3.