# 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.