packages/chip/docs/security/key-ceremony.md
Status: pre-silicon specification. No HSM, signer infrastructure, or audit pipeline exists yet. This document defines requirements before any production board may be provisioned to LOCKED state.
| Role | Description | Min headcount | Separation |
|---|---|---|---|
| Ceremony Officer (CO) | Conducts the ceremony, holds script, witnesses logs. | 1 | May not hold HSM credentials. |
| Key Custodian A / B (KC-A, KC-B) | Hold split-knowledge HSM activation credentials. | 2 | Each holds 1-of-2 PED key / smartcard. |
| Witness (W) | Independent witness; signs ceremony minutes. | 1 | Not employed by ceremony team. |
| Auditor (AU) | Reviews logs post-ceremony; read-only. | 1 | Not present during ceremony. |
| Vulnerability-response Owner (VRO) | Named accountable person for incident triage and key revocation decisions. | 1 | Named in key-ceremony.md revision history. |
No single individual may simultaneously hold any two of: HSM activation credentials, signer-host root credentials, or release-manager credentials.
| Tier | Hardware | Network | Keys | Use |
|---|---|---|---|---|
| Offline root HSM | FIPS 140-2 L3 or higher; PED-authenticated; smartcard-backed. | Air-gapped; write-once optical only. | Root key R; revocation key. | Sign AVB key A, vendor keys V, OTA key O. Ceremony only. |
| Online signing HSM | FIPS 140-2 L3; network-attached over mTLS. | Build VLAN, ACL'd to signer host only. | A, V, O, debug-auth, RMA keys. | Per-build signing on CI. |
| Signer host | Hardened Linux; reproducible image; remote attestation. | mTLS to online HSM only. | None (HSM-backed). | Receives image hash, returns signature. |
Prereqs: room with no networked devices, two cameras, optical write-once recorder, fresh tamper-evident bags, signed agenda witnessed by W.
Re-ceremony required if: any tamper-evident seal broken; HSM firmware updated; any custodian rotated; root key revoked.
CI builder --> signer host --> online HSM
^ |
| | signature
| v
+--------- audit log entry
|
v
append-only audit store (replicated)
Each signature request must include: image SHA-256, image_type, requested key_id, build provenance (git SHA, CI run URL, builder identity), requester (signed mTLS client cert).
Each emitted audit entry contains the above plus signer host attestation quote, HSM serial, key_id, timestamp, sequence number. Sequence numbers are gap-checked nightly; any gap is a P0 incident.
Per-device steps on the manufacturing line, lifecycle = MFG:
| Property | Requirement |
|---|---|
| Append-only | Storage layer rejects in-place edits; daily Merkle root anchored to release manifest. |
| Replication | Three replicas in two physical sites. |
| Retention | 10 years minimum; longer if any device on that key is still in field. |
| Searchability | Indexed by image SHA, key_id, builder, device_uid. |
| Integrity check | Nightly Merkle-root recomputation; mismatch is P0. |
| Review SLA | AU reviews ceremony logs within 7 days, signer logs weekly. |
| Incident handover | VRO on-call rotation; revocation decisions documented inside audit store. |
threat-model.md mitigations M11, M12boot-image-format.md §3 key ladder, §4 rollbackotp-fuse-map.md fuse allocationtest-plan.md cases TC-MFG-, TC-SIGNER-