@umbra-privacy/qos-ceremony 0.1.3 → 0.2.0

package/README.md

@@ -43,3 +43,60 @@ qos-ceremony status                # read-only phase + blockers
 
 Flags mirror env: `--api --namespace --nonce --alias --secret-path --yubikey
 --pcr3-preimage-path --qos-release-dir --qos-client`.
+
+## The at-rest layer
+
+A share is **double-sealed** everywhere it rests: the QOS P-256 envelope on the inside, an
+ML-KEM-1024 + X25519 envelope over it. `ceremony share` seals before upload and `ceremony provision`
+opens after download, so the singly-sealed form exists only inside a provision workdir, in the moment
+between recovery and re-encryption to the enclave's ephemeral key.
+
+The reason is the stored copy. `_shared/shares/<alias>.share` is durable and is the disaster-recovery
+material, so under P-256 alone a copy taken today is readable by a CRQC later. The outer layer closes
+that window without changing anything the enclave sees.
+
+### One-time setup, per operator
+
+```bash
+# a seed in the file — fine for a laptop ceremony or a test
+qos-ceremony encryption-key ~/.umbra/operator-encryption.json
+
+# a seed derived from hardware — only a salt is stored
+qos-ceremony encryption-key ~/.umbra/operator-encryption.json \
+  --challenge-command 'ykman otp calculate 2 {challenge}'
+```
+
+Then pass the key file to every ceremony command that touches a share:
+
+```bash
+export CEREMONY_ENCRYPTION_KEY=~/.umbra/operator-encryption.json
+qos-ceremony share       # derives, seals, uploads
+qos-ceremony provision   # downloads, opens, re-encrypts to the enclave
+```
+
+Add `--challenge-command` to `provision` when the key derives from hardware; the token must be
+present for that step and no other.
+
+### The tools directly
+
+`seal-share` and `unseal-share` are also exposed on their own, for a share handled outside the
+ceremony — a TVC deployment, or recovering one by hand. Arguments pass through to the underlying
+binary, so `--help` is the binary's own:
+
+```bash
+qos-ceremony seal-share --help
+qos-ceremony unseal-share --response quorum-key-response.json \
+  --key ~/.umbra/operator-encryption.json --out quorum_key_metadata.json   # tvc shape
+qos-ceremony unseal-share --response p1.share.sealed \
+  --key ~/.umbra/operator-encryption.json --out p1.share --format qos      # qos shape
+```
+
+`--format tvc` (the default) writes what `tvc keys re-encrypt-local-share` reads; `--format qos`
+writes the raw envelope `qos_client proxy-re-encrypt-share --share-path` reads.
+
+### Binaries
+
+`qos_client`, `umbra-encryption-key`, `umbra-seal-share` and `umbra-unseal-share` are embedded per
+platform. Override any of them with `--qos-client`, `--seal-share-bin`, `--unseal-share-bin`, or the
+matching `*_BIN` environment variable; on an uncovered platform the CLI falls back to the bare name
+on `PATH`.