# Security & Compliance Requirements — Quantum‑Sign (Pure‑Rust, crates.io‑only)
**Status:** Locked baseline (v0). This document is the **single source of truth** for security posture, implementation constraints,
and CI guardrails prior to writing functional code.
## 0. Scope & Objectives
- Build a post‑quantum code‑signing CLI with **ML‑DSA‑87** default and optional multi‑signature (e.g., SLH‑DSA) for archival.
- Pure‑Rust **only**, **crates.io‑only** dependencies.
- Deterministic, reproducible builds with strict supply‑chain controls and offline‑first verification.
- No network activity in the `sign` hotpath. Timestamping/transparency are explicit, auditable steps.
> Background rationale is in the Quantum‑Sign write‑up (kept separately).
## 1. Standards Baseline (authoritative references)
- **FIPS 204** (ML‑DSA), **FIPS 205** (SLH‑DSA), **FIPS 203** (ML‑KEM).
- **SP 800‑90A/90B/90C** (DRBG, entropy, constructions) for RNG.
- **SP 800‑57 Parts 1–3** (key management).
- **SP 800‑131A** (algorithm/key‑length transitions).
- **SP 800‑53 Rev.5 / 53B** (controls & baselines) — mapped below.
- **RFC 3161** (timestamping), **RFC 6962** (CT‑style transparency logs), **CBOR** (RFC 8949) for the `.qsig` envelope.
## 2. Threat Model (non‑exhaustive)
- Compromise or misuse of signing keys (incl. insider threat).
- Supply‑chain tampering (tooling, dependencies, release artifacts).
- Downgrade / cross‑protocol misuse (wrong algorithms/profiles).
- TOCTOU on inputs, symlink/race attacks, path traversal.
- RNG failures / low‑entropy starts.
- Log tampering, timestamp forgery, transparency log equivocation.
## 3. Cryptographic Requirements
- **Signatures (default):** ML‑DSA‑87. CLI defaults to FIPS-only mode (`--allow-nonfips` required to opt out and policies may still forbid it).
- **Optional co‑sign:** SLH‑DSA (conservative archival profile).
- **Hashes/XOF:** SHA‑256/512 and SHAKE256.
- **RNG:** HMAC_DRBG(SHA‑512) and/or AES‑CTR_DRBG with continuous health tests, seed from OS CSPRNG; reseed policy on interval and usage count.
- **Key material hygiene:** constant‑time operations; explicit zeroization; prevent paging (`mlock`/platform equivalent); domain separation labels for all protocol transcripts.
- **Module boundary:** encapsulate all crypto in `qs-crypto` (and `qs-drbg`) with a clear separation to support eventual FIPS 140‑3 validation.
## 4. Operational Controls → NIST SP 800‑53 Mapping
| Access control & least privilege | AC‑3, AC‑6, IA‑2 | CLI privileged actions gated by strong local auth (when applicable); RBAC in policy layer; no ambient credentials. |
| Configuration management | CM‑6, CM‑7 | Secure‑by‑default profiles; deny‑by‑default policy engine; config is signed and versioned. |
| Audit & accountability | AU‑2, AU‑8, AU‑12 | Append‑only, tamper‑evident logs; per‑command signed audit chain; export to SIEM. |
| Cryptographic protection | SC‑12, SC‑13 | Approved algorithms; key protection; integrity for data at rest/in motion. |
| System & info integrity | SI‑7, SI‑10 | Input validation, canonicalization, and safe file handling; anti‑rollback/anti‑downgrade checks. |
| Contingency planning | CP‑9, CP‑10 | Backup and recovery procedures for keys and trust roots; periodic drills. |
| Supply‑chain security | SA‑10, SA‑11, RA‑5 | Vetting of dependencies, reproducible builds, vulnerability scanning, and fuzzing. |
## 5. File & Path Safety
- Refuse parent‑directory traversal by default (enforced via `qs-cli` safe I/O helpers).
- Do not follow symlinks for inputs unless an explicit `--allow-symlinks` is set; never for outputs.
- Use O_NOFOLLOW/O_EXCL equivalents and race‑free temp file creation.
- Hash‑then‑sign on byte content; treat file metadata as untrusted.
## 6. Timestamping & Transparency
- Timestamping (`qs-tsp`) follows **RFC 3161**; tokens are **detached** and embedded as raw DER in `.qsig`.
- Transparency (`qs-transparency`) uses an RFC 6962‑style Merkle tree with signed tree heads; inclusion + consistency proofs are stored in `.qsig`.
- Both steps are **opt‑in**, explicit CLI operations and never occur during `sign`.
## 7. Crate Vetting Rules (crates.io‑only)
- **Allowed source:** `crates.io` **only**. No git/path dependencies. Enforced by `deny.toml`.
- **Banned crates:** `openssl`, `native-tls`, `serde_cbor` (use `ciborium` instead), and any crate marked **unmaintained** or with **unsound** issues.
- **Pure Rust only:** All dependencies must be Rust; if an optional feature requires a vendor shared library (e.g., PKCS#11), it must be **disabled by default** and clearly isolated.
- **Lints:** `#![forbid(unsafe_code)]` and `#![deny(missing_docs)]` for all first‑party crates.
- **MSRV:** 1.77 (may be raised with justification and CI update).
## 8. CI / Build Gates (must pass)
1. `cargo fmt --all --check`
2. `cargo clippy --all-targets --all-features -- -D warnings`
3. Minimal‑versions build: `cargo update -Z minimal-versions && cargo build --workspace`
4. Tests: `cargo test --workspace --all-features`
5. **cargo‑deny**: `advisories`, `bans`, `licenses`, `sources`
6. **cargo‑audit**: no outstanding critical advisories
7. **cargo‑vet**: present with empty audits; require audits for cryptographic crates when versions stabilize
8. **Auditable binaries**: release CI builds with `cargo auditable build` (or feature `auditable` on binaries)
## 9. Reproducibility & Release
- Hermetic build scripts (no network during release build when caches are hot).
- `lto="fat"`, `codegen-units=1`, `panic="abort"` for binaries.
- Generate and ship SLSA‑style provenance and SBOMs (out of scope for this skeleton, but reserved in workflow).
## 10. Exceptions & Change Control
- Security‑relevant changes (algorithms, RNG, file formats, network behaviors) require a design note and review.
- Any dependency addition/removal or MSRV bump must update this document.