saphan ceremony
The owner's key ceremonies when a team is set up: creating the root key, which is kept only on paper, and the intermediate key used to issue machine certificates.
The owner's key ceremonies when a team is set up: creating the root key, which is kept only on paper, and the intermediate key used to issue machine certificates.
saphan ceremony intermediate
Creates a new P-256 intermediate key pair, used to issue machine certificates, and a CA certificate for it signed by the root, whose 24 paper words you give on standard input; it also writes the root's own certificate (root.crt) beside it as the anchor of the chain. No root private key is written anywhere. The key file is readable only by you, and an existing key or certificate is not overwritten unless --force is given. The intermediate private key is an ordinary file on disk; keeping it in a hardware security chip is not done by this command.
| flag | type | default | what it does |
|---|---|---|---|
--days | int | 365 | How many days the CA certificate is valid. Defaults to 365. |
--expect-pin | string | The apk- pin the root words must produce, as printed by the root ceremony when the root was created; required with --root-words-stdin. | |
--force | bool | false | Overwrite an existing intermediate key and certificate at the target paths. ⚠ Certificates already issued under the old intermediate are orphaned. |
--intermediate-cert | string | Where to write the CA certificate. Defaults to ~/.saphan/trust/intermediate.crt. | |
--intermediate-key | string | Where to write the private key. Defaults to ~/.saphan/trust/intermediate.key. | |
--root-words-stdin | bool | false | Read the root's 24 paper words from standard input and sign the intermediate certificate with the root they produce; required unless --self-signed. |
--self-signed | bool | false | Let the intermediate sign its own certificate and write no root.crt, so nothing ties it to the root; meant for unattended installs and test setups, never a default. |
saphan ceremony root
Guides the root key ceremony: it creates a new root key, shows it as a numbered list of words to write on paper, asks for the words to be read back from the paper by a witness, and only when every word matches deletes the private key and word list from disk, leaving the public key. From then on the paper is the only way to sign as this root. When the workspace's record is reachable, it also creates an identity-signing delegate key (identity-delegate.key, which stays on disk) and records a root-signed grant for it; from then on identity rows are signed by that delegate, not by the root. When the record is not reachable no delegate is created, and after the wipe nothing on this machine can sign identity rows. A mismatch is refused (ceremony-capture-mismatch) and nothing is deleted. With --restore it works the other way, rebuilding the root on a new machine from the 24 words, granting a new identity-signing delegate, and wiping the private root key again; a machine that already has a root is refused (ceremony-root-exists).
| flag | type | default | what it does |
|---|---|---|---|
--delegate-days | int | 365 | How many days the identity-signing delegate's grant lasts, both for a new root and with --restore; after that the delegate signs nothing until the root grants it again. Defaults to 365. |
--expect-pin | string | With --restore, the root's public pin printed when the root was created; the words must reproduce it before anything is written. Required with --restore. | |
--no-qr | bool | false | Accepted but has no effect: this build shows the word list only and has no QR code to skip. |
--out-dir | string | Where the key and word list are written during the ceremony (deleted once the read-back succeeds). Defaults to the current directory; refused with --restore, which always writes to this machine's own trust directory. | |
--readback-file | string | Read the words back from this file instead of typing them, for rehearsals with a throwaway key. A file that is the ceremony's own word list is refused, because the check must come from a transcription. | |
--restore | bool | false | Rebuild this machine's root from the paper words, typed on standard input, instead of creating a new one; use it when the machine holding the root is lost. |
--yes | bool | false | Accept the air-gap and witness confirmation without a prompt. The word read-back check still always runs. With --restore and words piped on standard input, it is required, because it stands in for a person at the terminal. |
Global options apply to every command — see Every command.