Design principles

Design phase: these are the principles the design follows today. Each links to the record or page that decides it. Principles 1 to 11 carry the same numbers as in sluis, a system that holds intermediates; ritueel’s own start at 12.

What ritueel is, and is not

• Teaching first, then tools that simplify the rituals. The mission is to give people a smooth and safe experience of managing the root of a PKI and the master key of OpenPGP; the site teaches the logic, and the tools carry out the manual ceremonies while the person stays in charge. See ADR 0007.
• A command-line tool, a wizard on localhost, and documentation, not a network service. It holds no online keys. See ADR 0001.
• It owns roots, root ceremonies and root transitions for X.509, OpenPGP and SSH CA key lists, personal OpenPGP keys included. See ADR 0001 and ADR 0005.
• It never holds an intermediate’s private key. Systems like sluis hold intermediates, and meet ritueel only through the hand-off contract.
• Its records are files the operator keeps: ceremony records, root lists, and keyring packages that ritueel builds and the user’s own pipeline publishes. See ADR 0004 and ADR 0006.

Shared with systems that hold intermediates

1. Every key is born in its store and never leaves it. A transition makes a new key, and the old one vouches for it. See ADR 0002 and Root and intermediate and Moving from one root to another.
2. Trust is layered, and redundancy answers loss, not compromise. There are two root cards because a card cannot be copied, and one KMS root plus a replica because KMS can replicate its key. A compromise is answered by revocation and a transition. See ADR 0002 and Two roots in practice.
3. Keys are shared and rotated by rule. A key is shared only where audience, lifetime, revocation coupling and callers are all equal, as for the X.509 root key that also signs the root list. Renewal re-signs; key material is replaced on an event or at most every three years, and a transition makes a new key, never a copy. See the slot map and renewal and replacement.
4. Verify; never trust a claim. Attest what can be attested, re-read KMS keys and their policies from the service, and accept no copy of either. A check that cannot run is reported as not run, never as passed. See What the tool checks and the proof file.
5. Open standards, as their consumers implement them. OpenPGP keys are version 4 while gpg has no version 6, and a revoked key leaves the keyring package because gpgv ignores revocations. See ADR 0006.
6. A written contract and test vectors, not shared code; things are named for what they are. The word is intermediate, not the name of a device. See the hand-off contract and its test vectors.
7. A person only where a person adds safety. A touch on a card and a typed digest of the plan need a person; routine work reads public files only and is automated. See ADR 0004 and What a ceremony is.
8. Nothing without a consumer. During design, a record is rewritten in place and not extended by amendments. See the roadmap and how decisions are made.
9. Measure, and date the measurement. A claim about a tool, a card or a service carries the day it was measured. See the research pages.

Principle 10 of sluis is particular to sluis; see Not applicable to ritueel.

11. Public by default, private where it protects. The design, the reasons and the roads not taken are public; secrets and private deployment details are not. See Public content and secrets.

Particular to ritueel

12. Roots are offline and rare, but not air-gapped. A ceremony runs on an ordinary workstation, because the key never leaves its card or KMS; the checks exist because that workstation can still lie about what is signed. See ADR 0002.
13. One ceremony, many key stores: software (an encrypted file, 1Password or the system keyring), PIV, OpenPGP card and AWS KMS today; Google Cloud KMS, Azure Key Vault and Nitrokey are planned and arrive with their first real installation. Only the store and the key’s consumer differ, and each store is proven on real hardware or a real account. See ADR 0003 and Where a key lives.
14. ritueel teaches first. Every ceremony is explained, every road not taken is recorded, and a guide walks through each transition. The tools exist to simplify the rituals, and the wizard is a second face of the same ceremony engine, not a second implementation. See ADR 0007 and A lost root card.

Not applicable to ritueel

Principle 10 of sluis, one product in many installation shapes, has no counterpart: ritueel is a command-line tool and documentation, not a running service. Nor do reference installations with tenants, an audit record format, or serverless and Kubernetes runtimes apply. Its record is the ceremony record of ADR 0004.