Security model
The Secure Enclave security model
The private key never leaves your Mac.
- Generated inside the chip. On Apple Silicon the private key is created within the Secure Enclave and bound to that hardware — it cannot be read, copied, or exported by anyone or anything.
- Released with Touch ID. Decryption prompts your fingerprint, every time. If that gets old,
sopsy recipient rotate -s enclave -tswaps in a key with no Touch ID gate: it still never leaves the chip, but any program running as you can then decrypt. - Only the public recipient travels. The
age1se1…string is safe to commit and safe to share. It is all a teammate or admin needs to grant you access. - No Secure Enclave? Use a YubiKey. On Intel Macs and Linux the key lives in a YubiKey PIV slot instead: a PIN once per session with
-c cached, then a touch. Up to 20 keys fit on one YubiKey. - Lose the device, keep the repo. Because the key is bound to one Mac or one YubiKey, a break-glass recipient is what keeps secrets recoverable if every hardware key is lost.
Break-glass keys
Set up disaster recovery on day one.
A break-glass key is a separate emergency age key pair — portable by design, stored offline in a vault and shared with only a few admins. If every developer's Secure Enclave or YubiKey is lost, it can still decrypt and re-key the repository. An interactive sopsy init sets it up by default. sopsy recipient break-glass runs the whole ceremony in one command: generate, hand off, wait for ENTER, delete the local copies, register and re-key.
Lose your only hardware key with no break-glass key, and every secret becomes permanently undecryptable. That's why doctor and check nag until one exists — and sopsy refuses to remove the sole break-glass recipient. The same guided ceremony powers sopsy recipient ci for your pipeline — but the two keys must never be the same: offline/few-hands and online/every-run are opposite threat models.