git.stella-ops.org/docs/security/pq-provider-options.md

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)

{
  "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.