# Certificate authority ceremonies

This section is the canonical, executable record of every CCAT root-CA
ceremony — the procedures, paper artefacts, threat model, and
post-ceremony lessons. The documents here are loaded onto the
**supplies USB** by `step-ca/prepare-ceremony-usb.sh` so the air-gapped
ceremony laptop has the same content this Sphinx build does.

## When to run a ceremony

- **Phase 2 commissioning** — the original root + intermediate setup
  before any CCAT client trusts anything (this is what the playbook
  below is written for; first run was 2026-04-29).
- **Root rotation** — every ~10 years, or sooner if the threat model
  changes. The playbook is reusable; only PINs and HSM serials change.
- **Post-incident re-key** — if HSM #1 (root) leaves the safe under
  uncontrolled conditions, treat it as compromised and rerun the
  ceremony with fresh HSMs.

## The documents

```{toctree}
:maxdepth: 2

usb-readme
live-usb-setup
playbook
lessons-learned-2026-04-29
cutover-playbook
lessons-learned-cutover-2026-05-04
```

| Document | Audience | Purpose |
|---|---|---|
| [USB readme](usb-readme.md) | Operator at ceremony start | "Start here" entry point printed on the supplies USB. |
| [Live USB setup](live-usb-setup.md) | Prep operator (pre-ceremony) | How to build the boot + supplies USBs, threat model, hash-verify the manifest. |
| [Playbook](playbook.md) | Operator + witness during ceremony | Numbered, executable steps §0 through §16. The single source of truth. |
| [Lessons learned 2026-04-29](lessons-learned-2026-04-29.md) | Future ceremony operators | Post-ceremony retrospective: PKCS#11 URI shape, OpenSC virtual-token quirk, step-cli argument-order issues, and other surprises that the playbook now bakes in. |
| [Cutover playbook](cutover-playbook.md) | Operator + witness during HSM cutover | Stages A–H executable for the post-ceremony cutover on input-b: HSM verification, root rotation, compose changes, volume bootstrap, provisioner sync, test cohort re-bootstrap. |
| [Lessons learned cutover 2026-05-04](lessons-learned-cutover-2026-05-04.md) | Future cutover operators | Phase 2 cutover retrospective: the libusb-vs-pcscd architectural multi-pivot, step-cli's missing offline mode, host pcscd contention, the udev/GID alignment dance, and the plumbing bugs that ate hours. |

## Adjacent documents (background, not procedure)

- [Certificate authority architecture](../background/ca-architecture.md) — long-form explanation of the trust model, two-HSM layout, GitHub-team gate, lifetimes, and Pattern A. The Phase 2 ceremony itself is no longer narrated here; the executable procedure lives in `playbook.md` and `cutover-playbook.md`.
- [CCAT provisioner set](../background/ca-provisioner-set.md) — reference tables for the six provisioners, SSH access tiers, and the Ansible role tags exposed by `ca_trust` and `hsm_host`.
- [CA day-to-day operations](../ca-day-to-day.md), [CA provisioner management](../ca-provisioner-management.md), [CA rotation and recovery](../ca-rotation-and-recovery.md) — operator how-to guides for routine work, provisioner changes, and rotation/DR scenarios.
- [Certificate authority threat model](../background/certificate-authority-threat-model.md) — the broader threat-modelling document this ceremony's discipline derives from.
- [TLS and PKI primer](../background/tls-and-pki.md) — vocabulary refresher.

## Paper artefacts

The PIN sheet (`step-ca/ceremony-pin-sheet.tex` → `.pdf`) is the
paper companion the operator fills in by hand during the ceremony. It
captures the four PINs, two HSM serials, and the root-CA fingerprint
twice. The LaTeX source is committed; the rendered PDF should be
printed on a trusted printer immediately before the ceremony.

To rebuild the PDF from a checkout:

```
cd step-ca && pdflatex ceremony-pin-sheet.tex && pdflatex ceremony-pin-sheet.tex
```

(Twice, so the `LastPage` reference resolves.)