PQ Provider Options Design

Audience: Security Guild, Scanner/Policy/Attestor engineers, crypto maintainers. Scope: The current shape of the post-quantum signing provider (pq.soft) — supported algorithms, activation gate, options, key handling, and the gap between design intent and what is implemented today.

Last updated: 2026-05-30 · Owners: Security Guild · Scanner Guild · Policy Guild

Reconciled against the implementation on 2026-05-30. The post-quantum signing provider is implemented as the pq.softcrypto plugin (StellaOps.Cryptography.Plugin.PqSoft), a software-only provider built on BouncyCastle PQC primitives. Several items in earlier drafts of this design (a Crypto:Providers appsettings registry, per-feature SigningProvider overrides, BLAKE3 hashing, PEM key files, liboqs/oqs-provider bindings) were never implemented; they are now marked NOT IMPLEMENTED or Draft / roadmap below rather than described as current behavior.

Goals

• Allow DSSE/attestation flows to choose a post-quantum (PQ) signing profile (Dilithium3/Falcon512) via the existing ICryptoProvider / crypto provider registry surface without breaking deterministic outputs.
• Keep hash inputs stable across providers; only the signature algorithm changes.
• Remain offline-friendly and configurable per environment (plugin manifest entry
  • PqSoftProviderOptions).

Provider implementation (current)

The PQ provider is a single ICryptoProvider implementation:

• Plugin id / provider Name: pq.soft(PqSoftCryptoProvider.Name returns the literal "pq.soft").
• Assembly: StellaOps.Cryptography.Plugin.PqSoft.dll, type StellaOps.Cryptography.Plugin.PqSoft.PqSoftCryptoProvider.
• It exposes signing and verification only. GetHasher and GetPasswordHasher throw NotSupportedException — the provider does not expose hashing or password hashing.

There is no separate pq-dilithium3 / pq-falcon512 provider. Earlier drafts named two distinct providers; in the implementation there is one provider (pq.soft) that supports two signature algorithms, selected per key.

Supported algorithms

PqSoftCryptoProvider.Supports(...) returns true only for the Signing/Verification capabilities and only for these two algorithm identifiers (from StellaOps.Cryptography.SignatureAlgorithms):

Notes:

• Algorithm ids are matched case-insensitively (StringComparer.OrdinalIgnoreCase); UpsertSigningKey upper-cases the id before lookup.
• The legacy name DILITHIUM3maps to the standardized ML-DSA-65 parameter set; the implementation uses MLDsaParameters.ml_dsa_65 and the MLDsaSigner/MLDsaKeyPairGenerator classes. The exported JWK uses crv = "Dilithium3" / alg = "DILITHIUM3" for the public key, and crv = "Falcon512" / alg = "FALCON512" for Falcon.

Inconsistency to be aware of — the crypto plugin manifest (devops/etc/crypto-plugins-manifest.json, id pq.soft) advertises a broader capability set (ML-DSA-44/65/87, SLH-DSA-SHA2/SHAKE, SHA3-256/512, SHAKE256; compliance NIST-PQC, FIPS-203, FIPS-205). Those manifest capabilities are aspirational/inaccurate: the code only accepts DILITHIUM3 and FALCON512 for signing, supports no hashing, and provides no SLH-DSA / SHA3 implementation. Treat the C# Supports(...) result as ground truth, not the manifest capability strings.

Activation gate

PQ signing is gated off by default. The provider is enabled only when:

• PqSoftProviderOptions.RequireEnvironmentGate is false, or
• the PQ_SOFT_ALLOWED environment variable is set to 1 or true (case-insensitive; any other value, or unset, leaves the provider disabled).

When the gate is closed, Supports(...) returns false for all algorithms and GetSigner / UpsertSigningKey throw InvalidOperationException ("Provider 'pq.soft' is disabled. Set PQ_SOFT_ALLOWED=1 or disable RequireEnvironmentGate to enable.").

Provider options (current shape)

The provider binds PqSoftProviderOptions:

{
  // PqSoftProviderOptions
  "RequireEnvironmentGate": true,        // default; gate via PQ_SOFT_ALLOWED
  "Keys": [
    {
      // PqSoftKeyOptions
      "KeyId": "pq-key-1",
      "Algorithm": "DILITHIUM3",          // or "FALCON512"; default DILITHIUM3
      "PrivateKeyPath": "secrets/pq/dilithium3.key",
      "PublicKeyPath": "secrets/pq/dilithium3.pub"   // optional
    }
  ]
}

There is no top-level Crypto.DefaultProvider / Crypto.Providers registry binding, no Type: "PostQuantum" discriminator, no Hash field, no CertPath, and no UseBlake3 field in the implementation. The only options bound by the PQ provider are RequireEnvironmentGate and a Keys list of PqSoftKeyOptions (KeyId, Algorithm, PrivateKeyPath, PublicKeyPath). Plugin discovery and priority (priority 70) come from the manifest entry, not from a Crypto appsettings section.

Key handling (current)

• Keys are supplied as raw private-key bytes, not PEM. UpsertSigningKey rejects an empty private key ("PQ provider requires raw private key bytes.").
• The private-key bytes are used as deterministic seed material: the provider feeds them through a DigestRandomGenerator(Sha512Digest) / SecureRandom and runs the BouncyCastle key-pair generator (CreateSeededRandom → MLDsaKeyPairGenerator / FalconKeyPairGenerator). The same seed therefore reproduces the same key pair, which keeps tests/fixtures deterministic.
• On-disk keys (PqSoftKeyOptions.PrivateKeyPath / PublicKeyPath) are read with File.ReadAllBytes at construction time via TryLoadKeyFromFile. Missing files are skipped silently (the key simply is not registered); load failures are logged type-only (exception type, never the message/path/key bytes) to avoid echoing key material — see the LogWarnExceptionTypeOnly helper (SPRINT_20260528_037 / S037-002).
• A registered key validates that its stored algorithm matches the algorithm requested at GetSigner time, otherwise GetSigner throws ("... is registered for algorithm '...', not '...'.").
• DescribeKeys() emits descriptors tagged certified=false, simulation=software — this is explicitly a software PQ provider, not a certified/HSM-backed one.

Selection rules

• The provider is selected through the crypto provider registry (ICryptoProviderRegistry / CryptoProviderRegistry / TenantAwareCryptoProviderRegistry) by requesting a supported algorithm (DILITHIUM3 / FALCON512) for the Signing/Verification capability while the gate is open.
• Determinism: hash inputs (payload canonicalisation) are unchanged by provider selection — only the signature material differs. Both algorithms sign deterministically (MLDsaSigner(deterministic: true); Falcon as implemented), so signing the same payload with the same key yields the same signature.

NOT IMPLEMENTED (Draft / roadmap). The following per-feature override keys referenced in earlier drafts do not exist anywhere in the codebase and are not consumed by Scanner, Policy, or Attestor:

• Crypto:DefaultProvider
• DSSE:SigningProvider
• PolicyEngine:SigningProvider
• Scanner:SigningProvider

There is likewise no “fall back to DefaultProvider and emit a warning” behavior for a missing PQ provider; a missing/unregistered key throws KeyNotFoundException and a closed gate throws InvalidOperationException.

Hash strategy

NOT IMPLEMENTED (Draft / roadmap). The PQ provider does not expose any hasher (GetHasher throws NotSupportedException). There is no UseBlake3 flag and no DeterministicHashVersion setting in the implementation; searches across src/** return no matches for either. Hashing for DSSE/attestation payloads continues to use the platform’s existing hash strategy (SHA-256), independent of the PQ signing provider. BLAKE3 selection and a DeterministicHashVersion = 2 switch are aspirational only.

Key formats

Corrected. PQ keys are not stored as PEM (BEGIN PUBLIC KEY / BEGIN PRIVATE KEY) and there is no liboqs / OpenQuantumSafe toolchain dependency. The implementation uses BouncyCastle (Org.BouncyCastle.*, Pqc.Crypto.Falcon, ML-DSA) and reads keys as raw bytes via File.ReadAllBytes. Private-key bytes act as deterministic seed material for key-pair generation (see “Key handling” above). The provider validates that a key’s stored algorithm matches the requested algorithm at sign time.

Testing plan

Implemented tests:

• StellaOps.Cryptography.Tests/PqSoftCryptoProviderTests.cs:
  • GateBehavior_RespectsEnvironmentFlag — Supports is false until PQ_SOFT_ALLOWED=1.
  • Constructor_SkipsMissingKeyFile — missing key path → key not registered.
  • UpsertSigningKey_RegistersSigner — upsert then GetSigner round-trip for DILITHIUM3.
• Additional PQ-related coverage lives in StellaOps.Cryptography.Tests/SimRemoteCapabilityDetectionTests.PostQuantum.cs and PqSoftCryptoProviderTests.cs (a duplicate under src/__Libraries/StellaOps.Cryptography.Tests/).

Orphaned reference. Earlier drafts scoped this work to SCANNER-CRYPTO-90-002/003; those task ids do not exist anywhere in the repo and have been removed as the authoritative tracking reference. The env-gated integration harness ops/crypto/run-rootpack-ru-tests.sh referenced below also does not exist (no ops/crypto/ directory). Sign-and-verify round-trips, oqs/liboqs-compatible interop verification, and SBOM/Policy attestation integration tests are not yet implemented and remain roadmap items.

Planned (Draft / roadmap, not yet implemented):

• Integration (env-gated): sign sample SBOM attestations and Policy bundles with Dilithium3 and Falcon512; verify with an interop verifier.
• Determinism check: sign the same payload twice → identical signatures (both algorithms sign deterministically as implemented); record hashes in fixtures.

Rollout status

1. Done — provider classes implemented under StellaOps.Cryptography.Plugin.PqSoft (BouncyCastle PQC, not oqs bindings).
2. Done (partial) — provider is discovered via the plugin manifest (devops/etc/crypto-plugins-manifest.json, id pq.soft) and binds PqSoftProviderOptions. There is no Crypto:Providers appsettings registry.
3. NOT IMPLEMENTED — DSSE signing-option plumbing in Scanner/Policy/Attestor hosts via a SigningProvider override (no such override keys exist).
4. NOT IMPLEMENTED — env-gated tests in ops/crypto/run-rootpack-ru-tests.sh (script and directory absent).
5. NOT IMPLEMENTED — operator guidance in docs/dev/crypto.md (file absent) and RootPack notes.

Risks / mitigations

• Manifest vs. code drift — the pq.soft manifest entry advertises ML-DSA-44/87, SLH-DSA, and SHA3/SHAKE capabilities the code does not implement. Reconcile the manifest with PqSoftCryptoProvider.Supports(...) or implement the advertised algorithms before relying on the manifest for capability negotiation.
• Software-only, not certified — keys are tagged certified=false, simulation=software. This provider is not a substitute for an HSM- or CSP-backed PQ provider where certification is required.
• Interop risk — consumers may not understand Dilithium3/Falcon512 signatures. Dual-signing (classical + PQ) during transition is a design intent but is not wired through a SigningProvider toggle today.
• Performance — larger PQ signatures could affect payload size; benchmark during any rollout.
• Supply / offline — the provider depends on BouncyCastle (already a vendored dependency), not liboqs; no additional native PQ libraries need mirroring for offline installs.