0009: Key protection tiers and recipient types
- Status: accepted
- Date: 2026-09-22
Context
Users expect biometric unlock on phones and desktops. Hardware key stores
(Secure Enclave, Android StrongBox, TPM, YubiKey PIV) keep private keys
non-exportable but implement P-256, not X25519. Passkeys authenticate by
signing challenges; the only way to obtain key material from one is the
WebAuthn PRF / CTAP2 hmac-secret extension.
Decision
Three tiers of protection for a device's identity, all gated by the platform's biometric or PIN where one exists:
- Hardware-resident identity key. Recipient type
p256(ECIES over P-256 with HKDF-SHA-256 and XChaCha20-Poly1305). The private key is generated in and never leaves the Secure Enclave, StrongBox, TPM or PIV slot. Every unwrap requires the platform gate (Touch ID, Face ID, Windows Hello, token touch). Strongest tier; recommended forprod. - Software X25519 identity, wrapped by an OS or hardware key. The X25519 private key exists in memory only after a biometric-gated unwrap through the OS keychain (macOS Keychain with Secure Enclave protection, Android Keystore, Windows Hello / DPAPI). This is the portable default and the fallback on every platform.
- Software identity wrapped by a passkey PRF secret. For YubiKeys and synced passkeys, using the PRF/hmac-secret extension through the native platform APIs (AuthenticationServices, webauthn.dll, Credential Manager, libfido2 on Linux for roaming authenticators only).
Related decisions:
- Recipient types in v1:
x25519andp256. Each wrap file names its type and suite. - Each device key record carries a
protectionattribute (hardware,os-keychain,prf,passphrase). Policy may require a minimum tier per collection. - Keys do not expire. Rotation of a device key is an explicit, additive event ("D1 superseded by D2") that re-wraps KEKs. There are no time bombs.
- On Linux desktops without biometrics, tier 2 falls back to a passphrase (Argon2id) plus the system keyring.
- The agent daemon (ADR 0011) performs the unwrap once per session and may be configured to re-prompt per sensitive request, generalising hardware touch policies.
Consequences
- Hardware-backed members cannot use X25519-only tooling; the
p256type must be in the v1 format to avoid a later break. - Passkeys are supported but are not the primary mechanism and are never the only mechanism on a platform.
- Two recipient types mean two code paths in every implementation; the spec provides test vectors for both.
Alternatives considered
- X25519 only, with software keys everywhere. Rejected: forfeits non-exportable keys on every major platform.
- Passkeys as the primary identity. Rejected: PRF availability is uneven and a passkey is an authenticator, not a key store.