up

docs/security/pq-provider-options.md

@@ -0,0 +1,80 @@
+# PQ Provider Options Design
+
+Last updated: 2025-11-27 · Owners: Security Guild · Scanner Guild · Policy Guild
+
+## Goals
+- Allow DSSE/attestation flows to choose post-quantum (PQ) signing profiles (Dilithium/Falcon) via the existing `ICryptoProviderRegistry` without breaking deterministic outputs.
+- Keep hash inputs stable across providers; only signature algorithm changes.
+- Remain offline-friendly and configurable per environment (registry entry + appsettings).
+
+## Provider identifiers
+- `pq-dilithium3` (default PQ profile)
+- `pq-falcon512` (lightweight alternative)
+- Each provider advertises:
+  - `algorithm`: `dilithium3` | `falcon512`
+  - `hash`: `sha256` (default) or `blake3` when `UseBlake3` flag is enabled
+  - `supportsDetached`: true
+  - `supportsDSSE`: true
+
+## Registry options (appsettings excerpt)
+```json
+{
+  "Crypto": {
+    "DefaultProvider": "rsa-2048",
+    "Providers": [
+      {
+        "Name": "pq-dilithium3",
+        "Type": "PostQuantum",
+        "Algorithm": "dilithium3",
+        "Hash": "sha256",
+        "KeyPath": "secrets/pq/dilithium3.key",
+        "CertPath": "secrets/pq/dilithium3.crt",
+        "UseBlake3": false
+      },
+      {
+        "Name": "pq-falcon512",
+        "Type": "PostQuantum",
+        "Algorithm": "falcon512",
+        "Hash": "sha256",
+        "KeyPath": "secrets/pq/falcon512.key",
+        "CertPath": "secrets/pq/falcon512.crt",
+        "UseBlake3": true
+      }
+    ]
+  }
+}
+```
+
+## Selection rules
+- CLI/Service settings may specify `Crypto:DefaultProvider` or per-feature overrides:
+  - `DSSE:SigningProvider` (affects attestation envelopes)
+  - `PolicyEngine:SigningProvider` (policy DSSE/OPA bundles)
+  - `Scanner:SigningProvider` (scanner DSSE outputs)
+- If the requested provider is missing, fall back to `DefaultProvider` and emit a warning.
+- Determinism: hash inputs (payload canonicalisation) remain identical; only signature material differs. Avoid provider-specific canonicalisation.
+
+## Hash strategy
+- Default hash remains SHA-256 for interop.
+- Optional `UseBlake3` flag allows switching to BLAKE3 where approved; must also set `DeterministicHashVersion = 2` in consumers to avoid mixed hashes.
+- DSSE payload hash is taken **before** provider selection to keep signatures comparable across providers.
+
+## Key formats
+- PQ keys stored as PEM with `BEGIN PUBLIC KEY` / `BEGIN PRIVATE KEY` using provider-specific encoding (liboqs/OpenQuantumSafe toolchain).
+- Registry loads keys via provider descriptor; validation ensures algorithm matches advertised name.
+
+## Testing plan (applies to SCANNER-CRYPTO-90-002/003)
+- Unit tests: provider registration + selection, hash invariants (SHA-256 vs BLAKE3), DSSE signature/verify round-trips for both algorithms.
+- Integration (env-gated): sign sample SBOM attestations and Policy bundles with Dilithium3 and Falcon512; verify with oqs-provider or liboqs-compatible verifier.
+- Determinism check: sign the same payload twice -> identical signatures only when algorithm supports determinism (Dilithium/Falcon are deterministic); record hashes in `tests/fixtures/pq-dsse/*`.
+
+## Rollout steps
+1) Implement provider classes under `StellaOps.Cryptography.Providers.Pq` with oqs bindings.
+2) Wire registry config parsing for `Type=PostQuantum` with fields above.
+3) Add DSSE signing option plumbing in Scanner/Policy/Attestor hosts using `SigningProvider` override.
+4) Add env-gated tests to `scripts/crypto/run-rootpack-ru-tests.sh` (skip if oqs libs missing).
+5) Document operator guidance in `docs/dev/crypto.md` and RootPack notes once providers are verified.
+
+## Risks / mitigations
+- **Interop risk**: Some consumers may not understand Dilithium/Falcon signatures. Mitigate via dual-signing toggle (RSA + PQ) during transition.
+- **Performance**: Larger signatures could affect payload size; benchmark during rollout.
+- **Supply**: oqs/lib dependencies must be vendored or mirrored for offline installs; add to offline bundle manifest.