81 lines
3.9 KiB
Markdown
81 lines
3.9 KiB
Markdown
# 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.
|