Cryptography — Architecture

Audience: crypto/platform engineers and compliance reviewers wiring Stella Ops for regional or sovereign deployments.

Cryptography is the Stella Ops library layer that supplies algorithm-agile, compliance-profile-driven primitives (hashing, MAC, signing, KEK management). It lets every service request operations by purpose and resolve the concrete algorithm from the active regional profile (eIDAS, FIPS, GOST, SM, KCMVP, PQ), while keeping signing deterministic and reproducible. It is on-prem first: HashiCorp Vault is the flagship KEK backend, and no cloud-managed crypto service is a default.

0) Mission & boundaries

Mission. Provide algorithm-agile, compliance-profile-driven cryptographic primitives that support regional requirements (eIDAS/FIPS/GOST/SM/KCMVP/PQ) while ensuring deterministic, reproducible signing operations across all StellaOps services. Components request hashing/MAC by purpose (graph, symbol, content, merkle, attestation, interop, secret) and the active compliance profile resolves the concrete algorithm — see §4.

Boundaries.

• Cryptography is a library layer, not a standalone service. (The only optional in-repo crypto microservices are SM Remote, src/SmRemote/, and the test-only universal simulator under devops/services/crypto/sim-crypto-service/.)
• Cryptography does not store keys. Key/secret storage is delegated to the KEK source (IKekSource: env/file/Vault/HSM — see §4.9), the in-process PKCS#11 HSM provider, the signing KMS facade (IKmsClient), or Signer.
• All cryptographic operations are deterministic for reproducibility.
• The Stella audit/evidence chain default is EdDSA Ed25519. ECDSA-P256 is available only for explicitly selected regional or interop profiles and is not the evidence default.
• Supports offline operation without external crypto services.
• On-prem first. HashiCorp Vault is the flagship KEK/secret backend. Cloud KMS (AWS/Azure) is deliberately out of scope for the master-KEK source — there are no cloud-KMS stubs and no cloud defaults (IKekSource doc comment, 2026-05-27 decision). The separate signing-key IKmsClient facade ships file-based, FIDO2, and PKCS#11 (HSM) backends plus optional AWS/GCP adapters, but the on-prem posture means no cloud backend is wired by default.

1) Solution & project layout

Canonical-assembly note (SPRINT_20260430_017). The core crypto types live in src/__Libraries/StellaOps.Cryptography/, NOT in src/Cryptography/StellaOps.Cryptography/. The latter was a SPRINT_000 scaffold whose AssemblyName collision broke Auth.ServerIntegration; it was deleted and everything consolidated into the canonical assembly. The plugin projects under src/Cryptography/ reference the canonical project. Public namespaces are unchanged (StellaOps.Cryptography, StellaOps.Cryptography.Plugin*). See src/Cryptography/AGENTS.md.

Canonical core assembly — src/__Libraries/StellaOps.Cryptography/:

src/__Libraries/StellaOps.Cryptography/
 ├─ CryptoProvider.cs              # ICryptoProvider, ICryptoProviderRegistry, ICryptoHasher,
 │                                 #   CryptoCapability, CryptoKeyReference, *Resolution records
 ├─ CryptoProviderRegistry.cs      # Default ICryptoProviderRegistry (deterministic ordering, fail-closed hints)
 ├─ DefaultCryptoProvider.cs       # Name="default" — BCL ES*/RS*/PS*/Ed25519 + SHA hashing
 ├─ LibsodiumCryptoProvider.cs     # Name="libsodium" (STELLAOPS_CRYPTO_SODIUM build)
 ├─ CompliancePolicyCryptoProviders.cs  # fips.ecdsa.soft / eu.eidas.soft / kr.kcmvp.hash
 ├─ ComplianceProfile.cs           # Per-purpose algorithm map (the regional routing model)
 ├─ ComplianceProfiles.cs          # world / fips / gost / sm / kcmvp / eidas built-ins
 ├─ CryptoComplianceService.cs     # ICryptoComplianceService — resolve algorithm by purpose
 ├─ HashPurpose.cs / HashAlgorithms.cs / HmacAlgorithms.cs / SignatureAlgorithms.cs
 ├─ ICryptoHash.cs / ICryptoHmac.cs / ICryptoRandom.cs / ICryptoSigner.cs
 ├─ IHmacAlgorithm.cs / DefaultHmacAlgorithm.cs / FipsHmacAlgorithm.cs
 ├─ Argon2idPasswordHasher.cs (+ .Sodium / .BouncyCastle) / Pbkdf2PasswordHasher.cs
 ├─ MultiProfileSigner.cs / SignatureProfile.cs / EcdsaSigner.cs
 └─ Models/, Digests/, KeyEscrow/, Audit/, Interop/

Provider plugin projects — src/Cryptography/ (reference the canonical assembly):

src/Cryptography/
 ├─ StellaOps.Cryptography.Plugin.Fips/      # FipsPlugin (OS FIPS-mode probe, FIPS symmetric/HMAC)
 ├─ StellaOps.Cryptography.Plugin.Eidas/     # EidasPlugin, CAdES-B/-T/-LT/-LTA builder, TSL service
 ├─ StellaOps.Cryptography.Plugin.Gost/      # In-process BouncyCastle GOST (hash + 256-bit gen test signing)
 ├─ StellaOps.Cryptography.Plugin.Sm/        # BouncyCastle SM2/SM3/SM4
 ├─ StellaOps.Cryptography.Plugin.Hsm/       # HsmPlugin + Pkcs11HsmClientImpl (Pkcs11Interop)
 ├─ StellaOps.Cryptography.Plugin.OpenPgp/   # OpenPgpEncryptionProvider/v1 (email handoff)
 ├─ StellaOps.Cryptography.Profiles.Ecdsa/   # ECDSA signing profile
 ├─ StellaOps.Cryptography.Profiles.EdDsa/   # EdDSA signing profile
 ├─ plugins/                                 # external plugin drop directory
 └─ StellaOps.Cryptography.sln

Additional provider/KMS/KEK libraries — src/__Libraries/:

src/__Libraries/
 ├─ StellaOps.Cryptography.DependencyInjection/   # AddStellaOpsCrypto(...) + provider registration
 ├─ StellaOps.Cryptography.Plugin.EIDAS/          # eu.eidas — remote TSP/QSCD HTTP adapter
 ├─ StellaOps.Cryptography.Plugin.CryptoPro/      # ru.cryptopro.csp (Windows CryptoPro CSP GOST)
 ├─ StellaOps.Cryptography.Plugin.OpenSslGost/    # ru.openssl.gost
 ├─ StellaOps.Cryptography.Plugin.Pkcs11Gost/     # ru.pkcs11 (GOST via PKCS#11)
 ├─ StellaOps.Cryptography.Plugin.SmSoft/         # cn.sm.soft (software SM2/SM3; signed crypto-sm pack, §4.3b)
 ├─ StellaOps.Cryptography.Sm.Contracts/          # host-owned HTTP transport (cn.sm.remote.http): SmRemoteHttpClient/Provider/Signer (§4.3b)
 ├─ StellaOps.Cryptography.Plugin.SmRemote/       # thin plug-in wrapper that references Sm.Contracts (§4.3b)
 ├─ StellaOps.Cryptography.Plugin.SimRemote/      # sim.crypto.remote (test-only universal simulator)
 ├─ StellaOps.Cryptography.Plugin.PqSoft/         # pq.soft (DILITHIUM3 / FALCON512, experimental)
 ├─ StellaOps.Cryptography.Plugin.BouncyCastle/   # bouncycastle.ed25519
 ├─ StellaOps.Cryptography.Plugin.WineCsp/        # Wine-hosted CryptoPro CSP bridge
 ├─ StellaOps.Cryptography.Providers.OfflineVerification/  # offline.verification
 ├─ StellaOps.Cryptography.Plugin.BouncyCastleGost/ # BouncyCastle GOST (distinct from src/Cryptography/…Plugin.Gost)
 ├─ StellaOps.Cryptography.Plugin.OfflineVerification/ # distinct from Providers.OfflineVerification below
 ├─ StellaOps.Cryptography.Kms/                   # IKmsClient signing facade (File/FIDO2/Pkcs11/AWS/GCP — see §4.9)
 ├─ StellaOps.Cryptography.CredentialStore/       # KEK sources + secret-provider/registry contracts + AEAD/derived-tenant-keys (see §4.9)
 ├─ StellaOps.Cryptography.CredentialStore.Vault/ # VaultKekSource (flagship KEK source)
 ├─ StellaOps.Cryptography.CredentialStore.Hsm/   # HsmKekSource
 ├─ StellaOps.Cryptography.CredentialStore.Persistence/   # Postgres secret-provider registry + crypto.kek_versions migration/bootstrap
 ├─ StellaOps.Cryptography.CredentialStore.PluginRouter/  # secret-provider routing
 ├─ StellaOps.Cryptography.CredentialStore.ReSeal/        # KEK re-seal machinery (§11 --reseal)
 ├─ StellaOps.Cryptography.CertificateStatus/ (+ .Abstractions) # OCSP/CRL status layer (eIDAS LT, §4.8)
 ├─ StellaOps.Cryptography.Dsse/                  # DSSE PAE / envelope verification primitives
 ├─ StellaOps.Cryptography.HostProviders/         # RegionalCryptoRegistration / HostCryptoProfiles
 ├─ StellaOps.Doctor.Plugins.Cryptography/        # Doctor checks for this module
 └─ StellaOps.Cryptography.PluginLoader/

The in-process provider project src/Cryptography/StellaOps.Cryptography.Plugin/ ships CryptoProviderPackCatalog, CryptoProviderPackProbeReporter, CryptoPluginBase, and CredentialStoreInlineKey (cited by §4.3b without naming the owning project).

The AddStellaOpsCrypto(...) entry point (StellaOps.Cryptography.DependencyInjection) registers DefaultCryptoProvider, ICryptoHash/ICryptoHmac/ICryptoRandom, and the ICryptoProviderRegistry. The dependency-injection project is base-safe by default: regional, simulator, and proprietary provider source files plus their project references are compiled only when StellaOpsEnableOptionalCryptoProviders=true is set for an explicit provider-pack build. Base services may use AddStellaOpsCrypto(...) without pulling GOST/SM/PQ/simulator/CSP provider DLLs into their publish graph.

SmRemote runtime boundary (2026-06-05; contracts-only split completed 2026-06-07, d2e24267aa). src/SmRemote/StellaOps.SmRemote.Service does not consume AddStellaOpsCrypto(...); it constructs the narrow provider registry it needs for the remote SM2/SM4 API. The service host references the canonical crypto assembly plus the host-owned HTTP transport in StellaOps.Cryptography.Sm.Contracts (the production cn.sm.remote.http forwarder). As of the contracts-only split it no longer ProjectReferences StellaOps.Cryptography.Plugin.SmRemote or StellaOps.Cryptography.Plugin.SmSoft— the in-process cn.sm.soft provider is mounted as a signed pack (Production) or reached via a reflective Dev/Testing fallback (§4.3b). It does not reference the broad crypto DI package, sim.crypto.remote, PQ, GOST, CSP, or other optional regional provider payloads directly. A follow-up Authority slice removed the unused Auth.ServerIntegration -> StellaOps.Configuration project reference, so freshly built Auth.ServerIntegration restored assets no longer carry StellaOps.Configuration, StellaOps.Cryptography.DependencyInjection, or the optional provider assemblies. Full extraction of cn.sm.soft to a mounted provider pack is complete (ADR-024, 2026-06-07): the com.stellaops.crypto.sm pack and cn.sm.soft runtime provider IDs are reconciled, and the in-process software provider loads via the fail-closed MountedSmCryptoRuntimePluginLoader (crypto:provider:sm, runtime-bundle.v1, AllowUnsigned=false). cn.sm.soft stays test/local-harness only by default; Production startup rejects it unless the operator opts in with SMREMOTE_ALLOW_SIGNED_SOFT_PACK_IN_PROD AND an admitted signed pack supplies it (fail-closed otherwise — see §4.3a). StellaOps.Configuration can expose registry options without pulling optional provider payloads because the shared crypto DI project now keeps optional provider registrations behind an explicit opt-in build property.

1.1 Provider catalog (DB-driven, SPRINT_20260503_008)

The set of well-known providers surfaced by the Platform admin UI is held in platform.crypto_provider_catalog(Postgres). Each row is metadata only — provider id, display name, health endpoint, advertised algorithms, supported compliance profiles, production / test-only flags, and the linked plug-in id. Catalog rows are not executable code; the actual ICryptoProvider implementations still ship as code under src/__Libraries/StellaOps.Cryptography.Plugin.* and src/Cryptography/....

The boundary is non-negotiable: catalog identity is a foreign key into the registered-plug-in set, not a substitute for it. Loading arbitrary DLLs from a DB row would punch a hole in supply-chain integrity.

The migration (068_CryptoProviderCatalog.sql) auto-applies on startup (per CoC §2.7) and the catalog is seeded from src/Platform/StellaOps.Platform.WebService/Configuration/crypto-provider-catalog.seed.yaml on first boot only — subsequent updates flow through the /api/v1/admin/crypto-providers/catalog admin endpoints with audit emission (AuditActions.Platform.{Create,Update,Delete}CryptoCatalogEntry).

The seed YAML preserves the previously hard-coded list of smremote, cryptopro, and crypto-sim byte-for-byte so first-boot behaviour is unchanged. Operators add a new well-known provider (eIDAS QTSP, HSM PKCS#11, GOST CryptoPro/OpenSSL, …) by either inserting a catalog row directly or calling POST /api/v1/admin/crypto-providers/catalog with the crypto:admin scope (catalog write endpoints are POST/PUT/DELETE /api/v1/admin/crypto-providers/catalog[/{providerId}]; the catalog group requires authorization but is not tenant-scoped because platform.crypto_provider_catalog is a platform-global resource). (A cloud signing-KMS adapter such as AWS/GCP can be catalogued too, but it is an explicit operator opt-in, not a default — see §4.9 on the on-prem-first posture.)

2) External dependencies

• .NET Cryptography APIs - Built-in crypto primitives
• BouncyCastle (Apache-2.0, vendored) - Extended algorithm support (GOST, SM, OpenPGP, Argon2id fallback)
• libsodium (optional, STELLAOPS_CRYPTO_SODIUM build) - Ed25519 / Argon2id native path
• Pkcs11Interop (managed) - PKCS#11 HSM and PKCS#11 GOST routes
• CryptoPro CSP (optional) - GOST support on Windows (ru.cryptopro.csp) / Linux sidecar
• HSM (optional) - In-process PKCS#11 hardware security modules
• HashiCorp Vault (flagship, on-prem) - master-KEK source (VaultKekSource)
• Signing KMS (optional, non-default) - IKmsClient facade with File/FIDO2 and a PKCS#11 (HSM) backend (Pkcs11KmsClient/Pkcs11Facade, wired via ServiceCollectionExtensions.Pkcs11Kms.cs → AddPkcs11Kms); AWS/GCP adapters exist but are not wired by default (on-prem posture; no cloud KMS for the master KEK). The PKCS#11 backend is the on-prem HSM-backed signing-key route, distinct from the master-KEK HsmKekSource.

3) Contracts & data model

3.1 Core provider model (ICryptoProvider / ICryptoProviderRegistry)

The crypto core is capability- and algorithm-id based, not a per-profile ISignatureProvider. A provider declares which (capability, algorithmId) pairs it supports; the registry resolves the first capable provider in a deterministic preferred order. (Source: CryptoProvider.cs, CryptoProviderRegistry.cs.)

public enum CryptoCapability
{
    PasswordHashing, Signing, Verification,
    SymmetricEncryption, KeyDerivation, ContentHashing
}

public sealed record CryptoKeyReference(string KeyId, string? ProviderHint = null);

public interface ICryptoProvider
{
    string Name { get; }                                        // e.g. "default", "fips.ecdsa.soft"
    bool Supports(CryptoCapability capability, string algorithmId);

    IPasswordHasher GetPasswordHasher(string algorithmId);
    ICryptoHasher   GetHasher(string algorithmId);              // content hashing
    ICryptoSigner   GetSigner(string algorithmId, CryptoKeyReference keyReference);
    ICryptoSigner   CreateEphemeralVerifier(string algorithmId, ReadOnlySpan<byte> publicKeyBytes);

    void UpsertSigningKey(CryptoSigningKey signingKey);
    bool RemoveSigningKey(string keyId);
    IReadOnlyCollection<CryptoSigningKey> GetSigningKeys();
}

public interface ICryptoProviderRegistry
{
    IReadOnlyCollection<ICryptoProvider> Providers { get; }
    bool TryResolve(string preferredProvider, out ICryptoProvider provider);
    ICryptoProvider ResolveOrThrow(CryptoCapability capability, string algorithmId);

    // Explicit provider hints are fail-closed: an unknown/unsupported hint throws,
    // it does NOT fall back to another provider (see §4.4).
    CryptoSignerResolution ResolveSigner(CryptoCapability capability, string algorithmId,
        CryptoKeyReference keyReference, string? preferredProvider = null);
    CryptoHasherResolution ResolveHasher(string algorithmId, string? preferredProvider = null);
}

3.2 Hash computation (ICryptoHash / ICryptoHasher)

ICryptoHash is purpose-driven — callers request a hash for a HashPurposeand the active compliance profile resolves the concrete algorithm. It does not expose ComputeSha256/ComputeBlake3 convenience methods, and there is no HashAlgorithm enum (algorithm ids are the string constants in HashAlgorithms). (Source: ICryptoHash.cs, HashAlgorithms.cs.)

public interface ICryptoHash
{
    // Algorithm-based (backward compatible) — algorithmId is null ⇒ default algorithm
    byte[] ComputeHash(ReadOnlySpan<byte> data, string? algorithmId = null);
    string ComputeHashHex(ReadOnlySpan<byte> data, string? algorithmId = null);
    string ComputeHashBase64(ReadOnlySpan<byte> data, string? algorithmId = null);
    ValueTask<byte[]> ComputeHashAsync(Stream stream, string? algorithmId = null, CancellationToken ct = default);

    // Purpose-based (preferred for compliance)
    byte[] ComputeHashForPurpose(ReadOnlySpan<byte> data, string purpose);
    string ComputeHashHexForPurpose(ReadOnlySpan<byte> data, string purpose);
    string ComputePrefixedHashForPurpose(ReadOnlySpan<byte> data, string purpose); // e.g. "blake3:abc…"

    // Metadata
    string GetAlgorithmForPurpose(string purpose);
    string GetHashPrefix(string purpose);                       // "blake3:" / "sha256:" / "gost3411:" / "sm3:"
}

// Single-algorithm hasher returned by ICryptoProvider.GetHasher(...)
public interface ICryptoHasher
{
    string AlgorithmId { get; }
    byte[] ComputeHash(ReadOnlySpan<byte> data);
    string ComputeHashHex(ReadOnlySpan<byte> data);
}

Algorithm-id constants (HashAlgorithms.cs): SHA256, SHA384, SHA512, GOST3411-2012-256, GOST3411-2012-512, BLAKE3-256, SM3. There is no Blake3-512 and no Streebog* token — GOST Stribog is spelled GOST3411-2012-256/512.

Signature algorithm-id constants (SignatureAlgorithms.cs): ES256/ES384/ ES512, RS256/RS384/RS512, PS256/PS384/PS512, ED25519, EdDSA, GOST12-256, GOST12-512, SM2, DILITHIUM3, FALCON512.

3.2.1 VEX signature scheme verification (Excititor consumer)

Excititor’s ProductionVexSignatureVerifier (src/Concelier/__Libraries/StellaOps.Excititor.Core/Verification/ProductionVexSignatureVerifier.cs) is the reference consumer of the cryptography registry for VEX signature verification. Sprint 502_004 EXCITITOR-CRYPTO-AUDIT-00 (2026-05-02) audited this integration and recorded the binding shape; the dossier captures the conclusions here so future readers don’t repeat the audit.

The integration uses JOSE algorithm IDs, not signature scheme names. When the verifier resolves a provider it calls:

provider = _cryptoProviders.ResolveOrThrow(CryptoCapability.Signing, algorithm);
verifier = provider.CreateEphemeralVerifier(algorithm, key.PublicKey.Span);

…where algorithm is one of the JOSE constants from src/__Libraries/StellaOps.Cryptography/SignatureAlgorithms.cs (ES256, ES384, ES512, RS256, RS384, RS512, ED25519, EdDSA). These primitives are already shipped by DefaultCryptoProvider, EcdsaSigner, LibsodiumCryptoProvider, and CompliancePolicyCryptoProviders.

Signature schemes (cosign-detached, cosign-keyless, pgp-detached, dsse) are NOT registry algorithm IDs. They are scheme names that the verifier represents as VerificationMethod enum values, selected by ExtractSignatureInfo reading document metadata (signature-type, cosign-keyid, pgp-keyid, DSSE envelope JSON). The schemes wrap the underlying JOSE primitives — cosign signs with ECDSA-P256, PGP with RSA or ECDSA, DSSE envelopes any of the above. Operator-facing config (e.g. etc/excititor.worker.yaml.sample per-connector signature.profile) uses the scheme names as routing labels; they do not need round-tripping with the registry.

Per-issuer routing table (binding): see Excititor architecture §4.2.1 “Connector signature sources” for the canonical Cisco→cosign-keyless / Oracle→pgp-detached / RedHat→cosign-detached (with pgp-detached fallback) / Ubuntu→pgp-detached / Rancher→dsse / MSRC→quarantine mapping. The cryptography dossier deliberately does NOT duplicate that table to avoid drift.

Open work — scheme-level verifier methods (owned by Excititor, not this dossier). Several ProductionVexSignatureVerifier scheme strategies (PGP-detached, cosign-keyless, DSSE-keyless, X.509-chain) are scheme-level wirings inside the Excititor verifier — Fulcio/PGP/X.509 chain handling on top of the registry primitives (ECDSA, RSA, Ed25519), all of which already exist in this module. Because that is another module’s implementation state (with volatile per-method line numbers that rot silently — §1.5), the authoritative, dated tracking lives in the Excititor dossier / verification sprint, not here. This cryptography dossier keeps only the binding shape above (JOSE algorithm IDs vs. scheme names). Worker host wiring of AllowUnsigned=false and the per-connector profile configuration ships as part of sprint 502_001 EXCITITOR-WORKER-VRF-01…02; the YAML sample at etc/excititor.worker.yaml.sample is the binding configuration shape.

License posture (CLAUDE.md §2.6): the audit confirmed no new external dependencies are required for the VEX signature scheme work. Bouncy Castle (Apache-2.0, already vendored under StellaOps.Cryptography.Plugin.OpenPgp and third-party-licenses/) covers PGP packet parsing and ECDSA primitives where the BCL is insufficient. Sigstore-go bindings, Sigstore.NET, or Cosign-net are NOT introduced; cosign signature math is implemented against the existing ECDsa primitives directly.

3.3 MAC primitives (IHmacAlgorithm)

public interface IHmacAlgorithm
{
    byte[] ComputeMac(
        ReadOnlyMemory<byte> key,
        ReadOnlyMemory<byte> data,
        HmacAlgorithmName algorithm = default);

    bool Verify(
        ReadOnlyMemory<byte> key,
        ReadOnlyMemory<byte> data,
        ReadOnlySpan<byte> expectedMac,
        HmacAlgorithmName algorithm = default);
}

IHmacAlgorithm is the only sanctioned HMAC API for production code in the StellaOps repository. Direct calls to System.Security.Cryptography.HMACSHA256, HMACSHA384, or HMACSHA512 are forbidden outside the canonical crypto assembly (src/__Libraries/StellaOps.Cryptography/) — specifically DefaultHmacAlgorithm.cs and FipsHmacAlgorithm.cs, which are the only sanctioned BCL call sites — plus the legacy FipsPlugin.HashAsync HMAC switch in src/Cryptography/StellaOps.Cryptography.Plugin.Fips/FipsPlugin.cs. The architecture-conformance test in src/Cryptography/__Tests/StellaOps.Cryptography.Tests/HmacBclCallSiteConformanceTests.cs enforces this rule.

Note (SPRINT_20260430_017): IHmacAlgorithm and its types (HmacAlgorithmName, DefaultHmacAlgorithm, FipsHmacAlgorithm) live in the canonical legacy assembly (src/__Libraries/StellaOps.Cryptography/), not in the SPRINT_000 scaffolding project (src/Cryptography/StellaOps.Cryptography/) which has been deleted. Public namespaces are unchanged (StellaOps.Cryptography, StellaOps.Cryptography.Plugin, StellaOps.Cryptography.Plugin.Fips); consumers reference the canonical assembly via __Libraries/StellaOps.Cryptography.csproj. The SPRINT_000-introduced StellaOps.Cryptography.dll AssemblyName collision that broke Auth.ServerIntegration is retired.

Algorithm names

HmacAlgorithmName is a value type modelled on the BCL HashAlgorithmName style. The repository ships three well-known names:

default(HmacAlgorithmName) resolves to HmacSha256 so callers can omit the algorithm parameter and still get a documented MAC algorithm.

Implementations

Both implementations call the same BCL one-shot static methods (HMACSHA256.HashData, HMACSHA384.HashData, HMACSHA512.HashData); they delegate to the FIPS-validated provider on systems where FIPS mode is enabled. The split exists so that the FIPS plugin can advertise a distinct, attested implementation in the plugin manifest, and so that key handling differs:

• FipsHmacAlgorithm.ComputeMac(key, data, algorithm) accepts the key explicitly and does not depend on the FIPS plugin’s HmacKeyBase64 configuration. Webhook signature validators (Policy registry, Notify webhook inbound) must use this entry point — they negotiate keys per tenant or per-secret and must not silently fall through to the plugin-config key.
• The legacy FipsPlugin.HashAsync(data, "HMAC-SHA256", ...) path continues to pull from FipsOptions.HmacKeyBase64 and fails closed when that value is unset. The implementation now delegates to FipsHmacAlgorithm.ComputeMac, but the throw-on-missing-key gate is unchanged.

Regional plugin extension

GOST and SM regional plugins may register their own MAC algorithms by:

1. Introducing additional HmacAlgorithmName tokens (for example HMAC-Streebog256 or HMAC-SM3) — pattern follows the HmacSha256 / HmacSha384 / HmacSha512 static members in src/__Libraries/StellaOps.Cryptography/HmacAlgorithmName.cs.
2. Implementing IHmacAlgorithm in the regional plugin assembly (StellaOps.Cryptography.Plugin.Gost, StellaOps.Cryptography.Plugin.Sm, etc.) — same constructor pattern as FipsHmacAlgorithm.
3. Updating the architecture-conformance allow-list in src/Cryptography/__Tests/StellaOps.Cryptography.Tests/HmacBclCallSiteConformanceTests.cs to cover the new plugin path.

The regional plugin MAC implementations are out of scope for the foundational sprint that introduced IHmacAlgorithm; they are scheduled in their own follow-up sprints once the corresponding hash primitives (Streebog, SM3) are exposed.

3.3.1 Cryptographic RNG primitives (ICryptoRandom)

public interface ICryptoRandom
{
    void Fill(Span<byte> destination);
    byte[] GetBytes(int count);
}

ICryptoRandom is the only sanctioned cryptographic-RNG API for production code in the StellaOps repository. Direct calls to System.Security.Cryptography.RandomNumberGenerator (Fill, GetBytes, Create) and the legacy RNGCryptoServiceProvider are forbidden outside the canonical crypto assembly (src/__Libraries/StellaOps.Cryptography/) and the regional crypto plugins. The architecture-conformance test in src/Cryptography/__Tests/StellaOps.Cryptography.Tests/RandomBclCallSiteConformanceTests.cs enforces this rule (active enforcement as of Sprint 503_011).

The non-cryptographic System.Random.Shared surface is covered separately by the determinism analyzer (STELLA0114); ICryptoRandom intentionally focuses on cryptographic-grade randomness only.

Implementations

AddStellaOpsCrypto(...) registers ICryptoRandom → DefaultCryptoRandom as a singleton. Regional plugins (FIPS / HSM / CryptoPro) wrap their own CSPRNG access internally through their plugin entry points; the shared abstraction does not need to be plugin-aware in the same way ICryptoHmac is. If a future regional plugin needs to plug its own RNG into ICryptoProviderRegistry, the default can be superseded via the standard DI override.

3.3.2 AEAD primitives (IAeadAlgorithm)

The canonical assembly also defines an authenticated-encryption surface — IAeadAlgorithm, AeadAlgorithmName, and DefaultAeadAlgorithm (src/__Libraries/StellaOps.Cryptography/). This is the sanctioned AEAD API that the §11 re-seal profiles (AES-256-GCM / SM4-GCM / GOST-GCM) and CredentialStore.CredentialAead route sealing through, in the same “one sanctioned primitive” spirit as IHmacAlgorithm (§3.3) and ICryptoRandom (§3.3.1). AeadAlgorithmName enumerates the supported AEAD algorithm identifiers; production code seals/unseals via IAeadAlgorithm rather than constructing BCL AEAD ciphers directly.

Migration narrative (Sprint 503_011)

Sprint 503_011 (SPRINT_20260503_011_Cryptography_icryptorandom_abstraction) introduced the abstraction and migrated the production-code snapshot recorded by Sprint 503_005 / B-CRYPTO-004. The pattern:

• Region-aware nonce / salt / key generation (the dominant case) — sites that need cryptographic-grade randomness for an internal Stella security primitive and don’t pin a specific BCL type by contract were migrated to ICryptoRandom.Fill(...) / GetBytes(...).
• Schema-pinned RNG (rare for RNG; common for HMAC) — none of the production RNG sites turned out to be schema-pinned because the random output participated only in nonces / IVs / per-tenant keys, never in a reproducible identifier.
• Vendor-protocol pinned — none discovered for RNG. Most external protocols accept any cryptographic RNG output.

Test fixtures, oracles, and benchmark seeds remain on the BCL by design and stay in RandomBclCallSiteConformanceTests.KnownLegacyOffenders as permanent annotations (same convention as HmacBclCallSiteConformanceTests).

3.4 Compliance profile (ComplianceProfile)

The regional routing primitive is ComplianceProfile(not a CryptoProfile record — that type does not exist). A profile maps each HashPurpose to a hash algorithm + display prefix and each HmacPurpose to an HMAC algorithm. ICryptoComplianceService.GetAlgorithmForPurpose(purpose) resolves the algorithm for the active profile; ValidateAlgorithm(...) enforces it (fail-closed when StrictValidation=true). (Source: ComplianceProfile.cs, CryptoComplianceService.cs.)

public sealed class ComplianceProfile
{
    public required string ProfileId { get; init; }       // "world" | "fips" | "gost" | "sm" | "kcmvp" | "eidas"
    public required string StandardName { get; init; }    // e.g. "FIPS 140-3"
    public string? Description { get; init; }
    public required IReadOnlyDictionary<string, string> PurposeAlgorithms { get; init; }
    public required IReadOnlyDictionary<string, string> HashPrefixes { get; init; }
    public IReadOnlyDictionary<string, string>? HmacPurposeAlgorithms { get; init; }
    public bool AllowInteropOverride { get; init; } = true;  // interop purpose may stay SHA-256

    public string GetAlgorithmForPurpose(string purpose);
    public string GetHashPrefix(string purpose);
    public string GetHmacAlgorithmForPurpose(string purpose);
    public bool IsCompliant(string purpose, string algorithmId);
}

public interface ICryptoComplianceService
{
    ComplianceProfile ActiveProfile { get; }
    string GetAlgorithmForPurpose(string purpose);
    string GetHashPrefix(string purpose);
    void ValidateAlgorithm(string? purpose, string requestedAlgorithm); // throws CryptoComplianceException when strict
    bool IsAlgorithmCompliant(string algorithmId);
}

3.5 OpenPGP Email Encryption Provider

OpenPGP public-key encryption for operator-controlled email handoffs is exposed through StellaOps.Cryptography.OpenPgpEncryptionProvider/v1, implemented by src/Cryptography/StellaOps.Cryptography.Plugin.OpenPgp/. Product modules call this provider boundary instead of using OpenPGP libraries or external gpg commands directly.

The provider validates the supplied full recipient fingerprint against the local public key ring, rejects revoked or expired primary/encryption keys, checks encryption-key capability and key flags when present, emits ASCII-armored ciphertext, and records SHA-256 evidence for the exact ciphertext plus provider/key identity metadata. It requires the caller to supply the evaluation time so expiry checks remain deterministic and testable offline.

Contract doc: docs/contracts/openpgp-encryption-provider-v1.md.

4) Supported Profiles

4.1 Compliance profiles (regional routing)

The active compliance profile is the primary regional-routing mechanism. It is a per-tenant preference (Crypto:Compliance:ProfileId, default world, overridable via STELLAOPS_CRYPTO_COMPLIANCE_PROFILE). Each profile maps the seven HashPurpose values to a concrete hash algorithm, and the three HmacPurpose values to an HMAC algorithm. Components hash/MAC by purpose; the profile resolves the algorithm. (Source: ComplianceProfiles.cs, HashPurpose.cs, HmacAlgorithms.cs.)

The six built-in profiles (ComplianceProfiles.All):

Notes:

• The interop purpose always resolves to SHA256 for external-tool compatibility (cosign/rekor), even under GOST/SM, when AllowInteropOverride is true. gost/sm also force HMAC-SHA256 for the WebhookInterop HMAC purpose.
• GetProfile(id) falls back to world for an unknown id; GetProfileOrThrow throws. Unknown ids fail closed at registration when the id comes from config.
• world is the only profile using BLAKE3; FIPS uses PBKDF2-SHA256 for password hashing instead of Argon2id (Argon2id is not FIPS-approved).

4.2 Registered providers (provider-id inventory)

ICryptoProvider.Name is the stable provider id used in fail-closed routing hints and the platform catalog. Verified registered ids (from source Name => declarations):

For a confirmed regional Production profile, StellaOps.Cryptography.HostProviders composes the portable holders directly into the canonical default-ALC ICryptoProvider registry: ru.pkcs11 from StellaOps:Crypto:Pkcs11 and cn.sm.remote.http from StellaOps:Crypto:SmRemote. The SM production composition also registers a separate verification-only cn.sm.soft facade; environment variables or software options cannot promote that facade to a signer. Production SmRemote composition forces a live vendor-contract probe and explicit key mapping (SkipProbe=false, RequireVendorAdapterContract=true, AllowImplicitKeyMapping=false), and the provider validates the status envelope before advertising SM2. ru.cryptopro.csp remains a licensed, distribution-specific registration. See regional signing.

The in-process HSM provider (HsmPlugin, src/Cryptography/StellaOps.Cryptography.Plugin.Hsm/) and the in-process BouncyCastle GOST/SM plugins (StellaOps.Cryptography.Plugin.Gost / .Sm) register through the plugin loader rather than AddStellaOpsCrypto’s default set.

4.3 Signature profiles (signing-side curve/algorithm selection)

Separately from the compliance (hashing) profiles above, signing services select a signature profile. The audit/evidence-chain default is EdDSA Ed25519:

Audit bundles, evidence capsules, release decision capsules, and other evidence-chain signatures resolve eddsa-ed25519 unless a service is explicitly signing for a regional interop profile. ECDSA-P256 remains available for FIPS/eIDAS/legacy interoperability, but it must not be bound as the default audit-chain signer because the current P-256 signer is non-deterministic.

Regional signature algorithm ids (advertised by the regional providers above): GOST12-256/GOST12-512 (GOST R 34.10-2012), SM2, plus DILITHIUM3 / FALCON512 (PQ, experimental). The eIDAS plugin signs CMS/CAdES with RSA/ECDSA.

4.3a SM Remote Runtime Guard

SM Remote exposes SM2/SM3/SM4 over HTTP for services that cannot run the SM provider in-process. Its production posture is fail closed:

• cn.sm.soft is restricted to Development/Testing local harnesses by default. It may run in Production only via the explicit, default-OFF opt-in SMREMOTE_ALLOW_SIGNED_SOFT_PACK_IN_PROD, and even then only when an admitted signed crypto pack supplies it through MountedSmCryptoRuntimePluginLoader (mount devops/plugins/crypto/crypto-sm → /app/plugins/crypto/crypto-sm + the trust root, mirroring crypto-gost). With the flag set but no admitted pack the registry has no provider and the service fails closed at startup. The opt-in does not re-enable the un-admitted in-process software hatch (SM_SOFT_ALLOWED/AllowSoftwareProvider), which stays Production-forbidden — the signed-pack provider is authorized by admission. Remote HSM (cn.sm.remote.http) remains the default Production provider.
• Ephemeral key seeding is opt-in (default false) even on Development/Testing harnesses (SMREMOTE_ALLOW_EPHEMERAL_KEYS=1); when enabled, a positive TTL (SMREMOTE_EPHEMERAL_KEY_TTL, ISO-8601 duration) is required at startup and every minted key is stamped with ephemeral=true|expiresAt|seededBy=<RuntimeId> metadata, recorded in the EphemeralKeyAuditLog (sm-remote.key.seeded), and rotated by the EphemeralKeyRotationService once it crosses TTL (audit event sm-remote.key.rotated). Production environments still reject ephemeral keys outright.
• Unknown production keyId values must fail instead of creating signing authority.
• /hash, /encrypt, /decrypt, /sign, and /verify require operation-specific scopes (sm-remote:hash, sm-remote:encrypt, sm-remote:decrypt, sm-remote:sign, sm-remote:verify) plus tenant context.

4.3b SM crypto contracts-only split (ADR-024, d2e24267aa)

The SmRemote service image must not statically link the in-process SM crypto provider plug-ins. The boundary is enforced by a project-reference boundary test (SmRemoteRuntimePluginBoundaryTests, flipped Contains → DoesNotContain): StellaOps.SmRemote.Service no longer ProjectReferences StellaOps.Cryptography.Plugin.SmRemote or StellaOps.Cryptography.Plugin.SmSoft. This closed the last two hard source-coupling violations (repo audit violationCount → 0).

The decomposition follows the same shape as the GOST runtime-plugin split — host-owned transport vs signed provider pack — but with one deliberate asymmetry: the SM remote path carries no in-process crypto material, so it stays host-owned rather than becoming a mounted pack.

Host-owned HTTP transport — StellaOps.Cryptography.Sm.Contracts. The HTTP forwarder and its DTOs were extracted into a new contracts-only library that is its own project at src/__Libraries/StellaOps.Cryptography.Sm.Contracts/(NOT under src/Cryptography/, and NOT hosted inside Plugin.SmRemote). It contains SmRemoteHttpClient (incl. the request/response DTOs and SmRemoteVendorContract), SmRemoteHttpProvider, SmRemoteProviderOptions, and SmRemoteSigner. The thin src/__Libraries/StellaOps.Cryptography.Plugin.SmRemote/ project merely references Sm.Contracts; the SmRemote service references Sm.Contracts directly (verified in src/SmRemote/StellaOps.SmRemote.Service/StellaOps.SmRemote.Service.csproj) — that direct reference is the point of ADR-024. The types were moved with their namespaces preserved, so Cli, StellaOps.Cryptography.DependencyInjection, and Attestor compile unchanged. cn.sm.remote.http is a pure forwarder with no in-process crypto material, so it is woven directly into the SmRemote service Program.cs endpoints and stays in-process — it is not a signed mounted pack and not a base-image crypto default. In CryptoProviderPackCatalog it is catalogued ownership=HostOwned, requiresSignedPack=false, cloudManaged=false, productionAllowed=true.

Signed mounted pack — cn.sm.soft. Only the in-process SM2/SM3 software provider (StellaOps.Cryptography.Plugin.SmSoft) becomes a signed mounted crypto pack. It is catalogued ownership=RuntimePlugin, requiresSignedPack=true, profiles=[crypto-sm, sm], productionAllowed=true with the decision text “the in-process SM software provider carries real SM2/SM3 material and must be mounted as a signed crypto pack, never compile-time referenced by the SmRemote service image.” BouncyCastle SM3/SM4 remain host-owned — the violation was the project references, not the NuGet package.

MountedSmCryptoRuntimePluginLoader (src/SmRemote/StellaOps.SmRemote.Service/Plugins/). A new long-lived loader (NOT the GOST probe-and-unload loader) that instantiates the SM provider from the mounted signed pack and feeds it to the host ICryptoProviderRegistry. It reuses the shared SignedRuntimePluginAdmission (module crypto, capability crypto:provider:sm, contract runtime-bundle.v1, detached RSA-PKCS1-SHA256, AllowUnsigned = false) for fail-closed admission, plus a Default-ALC Resolving hook that serves the transitive StellaOps.* dependencies the mounted provider assemblies carry (the TPA-list trap — without the hook, activation throws FileNotFoundException; BouncyCastle is already on the host TPA). Crucially it ActivatorUtilities-activates the ICryptoProvider, so the host-registered SmRemoteHttpClient, IOptions<T>, and ILogger<T> constructor dependencies are injected. This host-DI activation is the operational gap the Signer GOST probe loader cannot fill: a probe loader uses a collectible ALC and a parameterless activator, so it can never serve a live provider for /sign and /verify. Providers are de-duplicated by ICryptoProvider.Name so a bundle mounted twice registers once and a shadowed provider is surfaced as rejected (no silent-green).

crypto-sm bundle producer profile. devops/build/package-runtime-plugins.ps1 gains a crypto-sm profile (alongside crypto-gost) that stages a signed cn.sm.soft bundle from StellaOps.Cryptography.Plugin.SmSoft.csproj with capability crypto:provider:sm. Mount it at devops/plugins/crypto/crypto-sm → /app/plugins/crypto/crypto-sm plus the trust root, mirroring crypto-gost. The Production runtime guard, opt-in flag, and fail-closed-without-pack semantics are documented in §4.3a; the compose mount is the live-lane follow-up (the admission/activation paths are covered by SmRuntimePluginLoaderAdmissionTests, with every reject path admitting zero providers).

Dev/Testing fail-open-to-host fallback. Outside Production, the SmRemote service Program.cs falls back to the in-process cn.sm.soft provider via a reflective SmHostDevFallbackProviderFactory (no compile-time SmSoft reference, preserving the boundary) so local harnesses keep working. Production has no fallback: an empty provider set faults startup (asserted fail-closed).

4.4 Provider Maturity And Fail-Closed Selection

Regional providers must not silently upgrade an unconfigured deployment into a signing authority:

• HSM mode requires a configured PKCS#11 LibraryPath; the simulated HSM is available only when AllowSimulation=true is set by a Development or Testing local harness. A production runtime rejects the simulation flag instead of reporting HSM-backed success.
• FIPS, GOST, and SM software providers do not generate signing keys by default. Local deterministic tests may opt in with GenerateKeysOnInit=true; production deployments must use configured key material or HSM/KMS-backed providers.
• FIPS HMAC and FIPS/GOST/SM symmetric operations require configured key material. Derived test keys are available only through explicit local harness flags and must not be used as production evidence keys.
• FIPS-mode detection is OS-level. FipsPlugin consults IFipsModeProbe (default OperatingSystemFipsModeProbe) which reads HKLM\SYSTEM\CurrentControlSet\Control\Lsa\FIPSAlgorithmPolicy\Enabled on Windows and /proc/sys/crypto/fips_enabled on Linux. macOS and unsupported hosts return a structured unsupported-platform source with IsEnabled=false. The legacy exception-based probe (SHA256.Create() success was treated as proof of FIPS) has been removed: managed SHA256 succeeds whether or not FIPS mode is enabled. When RequireFipsMode=true and the probe reports disabled, the plugin refuses to initialize (raises InvalidOperationException from InitializeAsync) and surfaces the probe Source tag for forensics.
• GOST symmetric mode is CBC by default. GostPlugin performs GOST-28147-89 encryption with a CBC BufferedBlockCipher, a randomly generated 8-byte IV per encrypt prepended to the ciphertext, and PKCS#7 padding. Truncated ciphertext (length below the IV header) is rejected with CryptographicException. ECB is retained behind the explicit Mode = "ECB-Interop" opt-in for legacy Russian regulator interop scenarios; selecting it emits a startup warning that ECB is not safe for confidentiality.
• SM Remote SM4 mode is negotiable — CBC by default (ADR-037 Option 3). The SmRemote service accepts SM4-CBC (default) and SM4-GCM; SM4-ECB is reachable only under the explicit SMREMOTE_SM4_MODE=ECB-Interop waiver, mirroring the GOST precedent (loud startup warning, no bare ECB token). The soft path (Sm4SoftCipher) uses PKCS#7 for CBC/ECB and AEAD for GCM, with IV/tag carried as explicit wire fields (never prepended); the in-process SmPlugin already implements SM4-CBC/SM4-GCM. Mode negotiation is fail-closed: a CBC/GCM-configured host requires the bridge /status.supportedAlgorithms to advertise that SM4 mode and rejects a mismatch at probe time with algorithm_missing rather than downgrading to ECB. The vendor wire contract is versioned sm-remote-vendor-adapter.v2 (adds IV/tag transport and the CBC/GCM ids); v1 remains valid and means ECB-only, pinned via SM_REMOTE_HSM_CONTRACT_VERSION. See SM Remote vendor adapter contract.
• AEAD/CBC decrypt paths bound-check the IV/tag header. FIPS and SM AES-GCM/AES-CBC and HSM SimulatedHsmClient AES-GCM decrypt now reject inputs shorter than the prepended IV (12 bytes) + Tag (16 bytes) (GCM) or IV (16 bytes) (CBC) header with a clear CryptographicException instead of slicing empty arrays.
• HSM PIN handling. Pkcs11HsmClientImpl.SlotContext stores the operator PIN as a mutable byte[] (UTF-8) and zero-wipes it via CryptographicOperations.ZeroMemory on dispose. The Pkcs11Interop ISession.Login API requires a System.String at the FFI boundary; the projection is scoped to the call frame and not stored on the slot context.
• The GOST software provider advertises generated signing support only for GOST-R34.10-2012-256. GOST-R34.10-2012-512 remains unavailable until a real provider-backed implementation and test vectors are present.
• Explicit provider hints are fail-closed trust-root selections. ICryptoProviderRegistry.ResolveSigner(...) and ResolveHasher(...) reject unknown configured providers instead of falling back to another implementation. Production Authority and Attestor signing paths also reject sim.crypto.remote and the software-only cn.sm.soft signing provider; use cn.sm.remote.http, GOST/CryptoPro/PKCS#11, eIDAS QSCD/TSP, HSM, or KMS-backed adapters with configured keys.

Provider selection therefore means “resolve a configured capable provider” rather than “fall back to a generated local provider.” If the requested regional profile lacks a configured provider, callers must surface unsupported or unavailable and fail the verification/signing path closed.

4.5 Provider Implementation Inventory (Local Inspection, 2026-04-27)

This map is based only on local source, docs, and devops files. It separates production-capable provider code from service adapters, simulator harnesses, and deployment/provider-pack material.

Planning consequence: regional-crypto continuation is provider selection, configuration, health, deployment overlays, and end-to-end route tests against existing provider surfaces. Real eIDAS QSCD/QTSP/TSA/OCSP/CRL/TSL material, licensed GOST provider evidence, vendor SM HSM/SDF adapters, and physical HSM details are expected in deployment-specific provider packs. They are not simulator defaults and they do not justify fake success; unsupported advanced evidence levels fail closed until a selected pack supplies the required material. Base/default Signer crypto and offline verification are host-owned runtime capabilities, so the default recommended and harness compose profiles must not declare empty /app/plugins/crypto/{base,recommended,harness} executable bundle mounts. Explicit regional crypto overlays are the place for signed provider-pack mounts and should remain non-green when selected without real pack and trust-root material. The local crypto-gost profile is packaged as a signed runtime bundle under devops/plugins/crypto/crypto-gost/com.stellaops.crypto.gost/; the fips-hsm profile is packaged under devops/plugins/crypto/fips-hsm/ with signed com.stellaops.crypto.fips and com.stellaops.crypto.hsm packs. Signer’s plugin probe endpoint validates mounted manifest/checksum/signature/capability metadata before any provider probe. Full profile acceptance still requires live container proof with the overlay and trust-root mount, plus image audit evidence.

4.5a Provider-Pack Manifest And Registry Contract (2026-06-12)

The source catalog, manifest, registry, and profile appsettings are a static gate for the pluginized crypto split:

devops/etc/crypto-plugins-manifest.json uses packId when the signed bundle ID differs from the runtime provider ID. devops/etc/plugins/crypto/registry.yaml exposes profile pack rows and backs each active row with providers/*.yaml. The appsettings.crypto.*.yaml profiles use runtime provider IDs. AWS/GCP/Azure KMS adapters remain future-only in source and are not present in the default/base registry profile.

For eIDAS, “provider pack” is a compliance boundary, not just a code plugin. It means either a selected QTSP/QSCD-backed deployment pack or a compliance-owned sealed pack containing RFC 3161 timestamp tokens, OCSP/CRL evidence, archive timestamp tokens, signing and TSA certificate chains, and sealed TSL/LOTL snapshots. BaselineT needs timestamp evidence, BaselineLT needs timestamp plus revocation evidence, and BaselineLTA needs those plus archive timestamp evidence. The default provider cannot make these profiles release-evidence eligible from simulator bytes or live trust-list lookups because those paths are not deterministic, not air-gap replayable, and do not prove qualified trust status. Provider-pack intake, legal review, and offline validation are tracked in docs/implplan/SPRINT_20260427_018_Cryptography_eidas_production_evidence.md.

4.6 Provider And Simulator Placement Contract

Use these locations when adding or reviewing regional crypto work:

• The only Stella-owned universal simulator microservice lives in devops/services/crypto/sim-crypto-service/, is composed by devops/compose/docker-compose.crypto-provider.crypto-sim.yml, and is consumed through src/__Libraries/StellaOps.Cryptography.Plugin.SimRemote/. It must remain opt-in and test-only.
• SM production HTTP bridging lives in src/SmRemote/ with deployment packaging under devops/services/sm-remote/ and devops/compose/docker-compose.sm-remote.yml. Vendor-specific SM HSM, SDF, or PKCS#11 adapters belong behind the cn.sm.remote.http contract exposed through SM_REMOTE_HSM_URL; they must not be added to the simulator service. The production adapter contract and deterministic fixtures are documented in docs/modules/cryptography/sm-remote-vendor-adapter-contract.md.
• eIDAS production QSCD/QTSP work is an external or operator-controlled service behind the TSP/QSCD HTTP contract implemented by src/__Libraries/StellaOps.Cryptography.Plugin.EIDAS/. If Stella Ops later ships an optional bridge image for a specific QTSP, place it under devops/services/eidas-qscd-bridge/ and keep the provider-facing contract in the eIDAS plugin library. The bridge HTTP contract is documented in docs/modules/cryptography/eidas-qscd-bridge-contract.md; simulator-style success payloads are not production evidence.
• GOST production provider code lives in src/__Libraries/StellaOps.Cryptography.Plugin.OpenSslGost/, src/__Libraries/StellaOps.Cryptography.Plugin.Pkcs11Gost/, and src/__Libraries/StellaOps.Cryptography.Plugin.CryptoPro/. The Linux CryptoPro sidecar belongs in devops/services/cryptopro/linux-csp-service/ and is a fail-closed readiness/license/keyset wrapper for customer-provided packages, not a signing simulator.
• HSM production support is the in-process PKCS#11 provider in src/Cryptography/StellaOps.Cryptography.Plugin.Hsm/. A future shared network HSM bridge, if needed, should be a new explicit service under devops/services/hsm-bridge/ with a dedicated remote provider adapter; do not reuse SimulatedHsmClient or sim.crypto.remote for release evidence.

4.7 Development/Testing Regional Fixture Policy

Regional fixture work has a simulator-backed Development/Testing path. Development and Testing can use sim.crypto.remote as the local fixture provider when STELLAOPS_ALLOW_UNSAFE_CRYPTO_SIM=1 is set. The simulator-backed path covers:

Simulator smoke output may be stored as test evidence only. Production release decisions must reject simulator identifiers, testOnly=true responses, production=false provider payloads, and any payload that does not explicitly prove release-evidence eligibility through a real provider route.

4.8 Runtime Loader And Claim Control (eIDAS)

The eIDAS plugin (src/Cryptography/StellaOps.Cryptography.Plugin.Eidas/) ships two fail-closed loaders that gate any production CAdES-T / CAdES-LT / CAdES-LTA path. Both loaders are vendor-independent and are operative regardless of the upstream QTSP-vendor-agreement outcome (sprint SPRINT_20260502_005_Cryptography_eidas_qtsp_vendor_intake.md).

• Loader 1 — Static offline trust-material pack. Reads an operator-supplied manifest from the path declared by configuration key Eidas:TrustedList:OfflineTrustMaterialPackPath (legacy alias Eidas:TrustedList:FixturePackManifestPath). Verifies SHA-256 integrity of every referenced LOTL / TSL / certificate / OCSP / CRL artefact, plus a roll-up packSha256 over the canonicalised file list. Required manifest fields: packVersion, validFromUtc, validUntilUtc (legacy alias expiryUtc), trustedListVersion, tlv6Compatible, qtspServiceIdentifier, serviceStatusUri, serviceTypeUri, packSha256, files. Refuses the load if (a) the pack file is missing, (b) the pack is expired, © no authorised QTSP agreement is loaded from Eidas:TrustedList:QtspAgreementPath, or (d) the pack is not TLv6 / ETSI TS 119 612 v2.4.1 compatible and the operator has not opted in to the historical-validation use-case via Eidas:TrustedList:AllowHistoricalPreTlv6Use=true AND Eidas:TrustedList:IsHistoricalReplay=true.

• Loader 2 — Per-transaction evidence. Per counsel response 2 (docs/legal/decisions/lawyer-response2.md), RFC 3161 timestamp tokens and CAdES archive timestamps cannot be pre-vendored — each token is bound to the message-imprint of a specific datum and is issued per-transaction. Loader 2 reads from Eidas:TransactionEvidence:RootPath, expects one sub-directory per release-id with an evidence-manifest.json declaring releaseId, messageImprintSha256, evidenceTimestampUtc, qtspServiceIdentifier, and evidenceDigestBinding. The loader verifies that (a) the evidence manifest’s QTSP identifier matches the static pack’s, and (b) the evidenceDigestBinding equals SHA256(messageImprintSha256_lower || ":" || qtspServiceIdentifier). Refuses with structured EidasEvidenceNotProductionReadyException reasons MissingTransactionEvidence, TransactionEvidenceQtspMismatch, or TransactionEvidenceDigestUnbound.

The plugin gates SignAsync and VerifyAsync for any algorithm name containing CAdES-T, CAdES-LT, or CAdES-LTA. CAdES-BES paths are unaffected — they are the simulator-success scenario allowed without the loaders being satisfied. When the gate is closed (any of the four Loader 1 branches or any of the three Loader 2 branches above), both methods throw EidasEvidenceNotProductionReadyException carrying the structured Reason enum.

The runtime emits a counsel-cleared wire-form claim state (EidasRuntimeClaimState) consumable by Doctor and evidence envelopes:

Claim-control wording. Per eIDAS Articles 33 / 34 / 40, runtime output paths must NOT use “qualified validation service” / “qualified preservation service” / “qualified timestamping service” / “claimed-against” affirmative claims unless all loader gates are closed AND a current TLv6 pack (or an explicit historical-validation exception) is in force. The plugin exposes the verbatim safer-wording counsel cleared in docs/legal/decisions/lawyer-response2.md §“Revised vendor-facing claim-control wording” via EidasClaimWording.SaferWording. The role description Stella Ops MAY use without a QTSP agreement is exposed via EidasClaimWording.RoleDescription. Both constants are character-for-character verbatim; tests assert the equality and will break if either is paraphrased.

4.8.1 CAdES-T / -LT / -LTA production readiness (EIDAS-EVIDENCE-018-03)

CadesSignatureBuilder produces real CAdES-T / -LT / -LTA outputs that embed the corresponding ETSI EN 319 122-1 unsigned attributes when an IEidasFixturePack is wired in. The pack is operator-supplied at deploy time (production) or supplied by the sealed deterministic test fixture (CI). When no pack is wired in (DI returned null), the higher levels stay fail-closed and the builder throws NotSupportedException whose message points to the QTSP/QSCD bridge. The plugin-level gate (EidasPlugin.SignAsync / EidasPlugin.VerifyAsync) still throws EidasEvidenceNotProductionReadyException first when Loader 1 / Loader 2 are not both satisfied — that gate fires regardless of whether a pack is wired in.

Fail-closed posture (binding):

• No pack wired in → builder throws NotSupportedException (legacy contract; tested by CadesSignatureBuilderFailClosedTests).
• Pack wired in but loader gate is open (no manifest, expired pack, no QTSP agreement, TLv6-incompatible without historical-replay opt-in, or per-transaction evidence missing/mismatched/unbound) → plugin’s EidasPlugin.GuardProductionClaimAlgorithm throws EidasEvidenceNotProductionReadyException BEFORE the builder is invoked.
• Caller-supplied metadata that pretends the pack is loaded (the “simulator-style success payload” pattern) is ignored — the gate decision uses the EidasLoaderState produced by the loader, not the request metadata. Tested by CadesEmbedTests.EmbedCadesT_RejectsSimulatorStyleSuccessPayload.

Sealed-test-fixture story. CI uses the deterministic in-repo pack authored under EIDAS-EVIDENCE-018-01 at src/Cryptography/__Tests/StellaOps.Cryptography.Tests/Eidas/Fixtures/sealed-pack/. The test-side SealedFixturePack (in src/Cryptography/__Tests/StellaOps.Cryptography.Tests/Eidas/SealedFixturePack.cs) implements IEidasFixturePack against that pack. Production deployments are expected to wire an operator-supplied implementation backed by the QTSP-supplied pack at deploy time; the eIDAS plugin’s DI registration intentionally does NOT register a default IEidasFixturePack so the simulator-success scenario cannot occur by accident.

Synthetic fixture allowance. The sealed fixture pack may be used to prove loader, parser, CAdES, and future QES signer-certificate wiring while the real eIDAS qualified-provider pack is unavailable. It is test material only: do not mount it in production, do not ship it in Offline Kit/provider-pack distributions, and do not use it as evidence for a qualified-service claim. Real pack ingestion is documented in docs/modules/cryptography/eidas-qualified-provider-pack-ingestion.md; production QES remains fail-closed until the operator supplies a real pack through Eidas:TrustedList:OfflineTrustMaterialPackPath, an unexpired agreement through Eidas:TrustedList:QtspAgreementPath, and per-transaction evidence through Eidas:TransactionEvidence:RootPath.

Round-trip verification. Produced CAdES-T signatures are round-trip-verified against the same SealedPackEvidenceValidator used by EIDAS-EVIDENCE-018-02 (RFC 3161 CMS signature + pinned-chain walk + message-imprint match + gen-time window). Produced CAdES-LT signatures additionally OCSP-validate via SealedPackEvidenceValidator.ValidateBaselineLT. Produced CAdES-LTA signatures additionally archive-TST-validate via the same RFC 3161 validation path used for the signature TST. See CadesEmbedTests.cs for the round-trip assertions.

4.9 Master KEK lifecycle (IKekSource) — Vault flagship, on-prem first

The master key-encryption key (KEK) that wraps connector credentials, Integrations secrets, and deployment-bundle ciphertext is resolved through the IKekSourceabstraction (src/__Libraries/StellaOps.Cryptography.CredentialStore/IKekSource.cs). The operator selects the source kind via the config key Crypto:Kek:Source; allowed values are env (default), file, vault, hsm — an unrecognised value throws at registration (fail-fast over a quiet downgrade).

Vault is the flagship and the recommended production source. Operators already run HashiCorp Vault for pull-mode AuthRef; VaultKekSource reuses that surface and gates the master KEK behind Vault-managed access policy. Config keys (VaultKekSourceOptions): Crypto:Kek:Vault:Address, …:Mount, …:Path, …:Field, …:Encoding (utf8|base64|hex), …:StartupRetryWindow.

No silent fallback (compliance posture). Every IKekSource MUST throw when its source is unavailable; silently downgrading to env-var would mask the operator’s chosen posture. VaultKekSource retries with capped exponential backoff for the configured StartupRetryWindow, then fails startup with a sanitised error (it never logs KEK bytes, encoded values, or Vault auth fragments). Resolved KEK material is cached in-process for the host lifetime; InvalidateCache() forces a re-resolve during rotation.

Cloud KMS for the master KEK is deliberately out of scope. Per the IKekSource design comment (2026-05-27 decision): “Env + File + Vault + HSM are in scope. AWS / Azure KMS are deliberately out of scope (no stubs); the interface stays open so a downstream plugin can implement them if/when needed.” This is the on-prem-first posture — there is no cloud-KMS default for the master KEK.

CredentialStore is more than KEK sources. The IKekSource implementations above are only part of the StellaOps.Cryptography.CredentialStore project. It also owns the secret-provider abstraction (ISecretProvider, BuiltinSecretProvider, RoutingSecretProvider, SecretProviderServiceCollectionExtensions) and the persistence-neutral runtime provider registry contract (ISecretProviderConfigStore, SecretProviderConfigRecord). CredentialStore.Persistence supplies the Postgres implementation; Platform consumes only the neutral contract. The core project also owns the asymmetric KEK source (AsymmetricKekSource), per-tenant derived keys (DerivedTenantKeyProvider, MasterKeyProvisioner), AEAD sealing (CredentialAead), and the compliance-driven algorithm selection (CredentialAlgorithmProfileMap, TenantComplianceProfileCredentialAlgorithmSelector). The KEK-source subset is documented in full here; the secret-provider/derived-key/AEAD surfaces are owned by this library even where other module docs describe their use.

KEK versions / rotation. CredentialStore.Persistence ships the crypto.kek_versions migration (001_kek_versions.sql) and KekVersionBootstrapHostedService, which stamps the active KEK fingerprint and source (one of env|file|vault|hsm) on startup. KekMaterial carries KekId, KekVersion, the secret bytes, and an optional ExpiresAt; the rotation audit trail tracks only fingerprints + versions, never the secret.

KEK control-plane scopes (SPRINT_20260529_028 / RP-028-005). KEK read and rotation are gated by dedicated OAuth scopes distinct from crypto:admin so an operator can grant rotation capability separately from provider-catalogue mutation: crypto:kek:read (StellaOpsScopes.PlatformCryptoKekRead) and crypto:kek:rotate (StellaOpsScopes.PlatformCryptoKekRotate). The CLI exposes the stella crypto kek subgroup (and stella crypto provider set / stella crypto algorithm for installation-level provider/algorithm settings).

Signing KMS vs. master KEK (do not conflate). The separate StellaOps.Cryptography.Kms library exposes an IKmsClient signing facade (SignAsync/VerifyAsync/RotateAsync/RevokeAsync/ExportAsync) surfaced as the kms provider. Its default backends are FileKmsClient and Fido2KmsClient; AwsKmsClient/GcpKmsClient exist as optional adapters but are not wired by default and must be opted into explicitly. This is a distinct concern from the master-KEK IKekSource above.

5) Plugin Architecture

5.1 Plugin Discovery

Plugins are loaded from plugins/ directory:

plugins/
  ├─ gost/
  │   ├─ manifest.json
  │   └─ StellaOps.Cryptography.Plugin.Gost.dll
  └─ sm/
      ├─ manifest.json
      └─ StellaOps.Cryptography.Plugin.Sm.dll

5.2 Plugin Manifest

{
  "pluginId": "stellaops.crypto.gost",
  "version": "1.0.0",
  "profiles": ["gost-2012-256", "gost-2012-512"],
  "dependencies": {
    "cryptopro": "5.0+"
  },
  "platforms": ["win-x64", "linux-x64"]
}

5.3 Plugin Interface

Reconciliation note (2026-05-30). There is no ICryptoPlugin type in the codebase, and no GetSignatureProvider/GetHashProvider pair. A crypto plugin is just an ICryptoProviderimplementation (see §3.1) discovered by StellaOps.Cryptography.PluginLoader and added to the ICryptoProviderRegistry. The provider advertises support via Supports(CryptoCapability, algorithmId) and returns ICryptoSigner / ICryptoHasher instances on demand. The illustrative shape below is retained only as a conceptual sketch; the binding contract is ICryptoProvider.

// Conceptual sketch only — the real contract is ICryptoProvider (§3.1).
public interface ICryptoProvider
{
    string Name { get; }
    bool Supports(CryptoCapability capability, string algorithmId);
    ICryptoSigner GetSigner(string algorithmId, CryptoKeyReference keyReference);
    ICryptoHasher GetHasher(string algorithmId);
    // …UpsertSigningKey / RemoveSigningKey / GetSigningKeys / CreateEphemeralVerifier
}

6) Configuration (YAML)

Config keys below are grounded in the actual options types (CryptoComplianceOptions → Crypto:Compliance, KekSourceServiceCollectionExtensions

• VaultKekSourceOptions → Crypto:Kek). The active hashing/MAC algorithm set is driven by the compliance profile, not per-signature-profile toggles.

Crypto:
  # Compliance (regional hashing/MAC routing). See §4.1.
  Compliance:
    ProfileId: "world"        # world | fips | gost | sm | kcmvp | eidas (default: world)
    StrictValidation: true    # fail closed on non-compliant algorithm-for-purpose
    WarnOnNonCompliant: true  # used when StrictValidation=false
    AllowInteropOverride: true
    # PurposeOverrides: { graph: "SHA256" }   # optional per-purpose overrides
    # Env overrides: STELLAOPS_CRYPTO_COMPLIANCE_PROFILE, STELLAOPS_CRYPTO_STRICT_VALIDATION

  # Master KEK source. On-prem first; Vault is the flagship. See §4.9.
  Kek:
    Source: "vault"           # env (default) | file | vault | hsm  (unknown ⇒ fail-fast)
    Vault:                    # required when Source=vault
      Address: "https://vault.internal:8200"
      Mount: "secret"
      Path: "stellaops/kek/master"
      Field: "kek"
      Encoding: "base64"      # utf8 | base64 | hex
      StartupRetryWindow: "00:00:30"   # fails startup if Vault unreachable after window
    File:                     # required when Source=file
      Path: "/etc/stellaops/kek.key"
    # NOTE: AWS/Azure KMS are deliberately NOT a KEK source (no cloud default).

# In-process HSM provider (PKCS#11) — opt-in, no production simulation.
Hsm:
  LibraryPath: "/usr/lib/softhsm/libsofthsm2.so"  # native PKCS#11 module (required)
  SlotId: 0
  AllowSimulation: false      # true only in Development/Testing harnesses

# Signing KMS facade (IKmsClient) — distinct from the master KEK above.
# Default backends are file/FIDO2; AWS/GCP adapters are optional and NOT
# wired by default (on-prem posture).

Posture note (2026-05-30 reconciliation). A prior revision of this dossier showed Kms: Provider: "aws", Region: "us-east-1" as the configuration example. That contradicted the on-prem-first posture: cloud KMS is not a master-KEK source and is not a default. The example above leads with Vault.

7) Security considerations

• Algorithm agility: Easy migration to new algorithms
• Side-channel protection: Constant-time implementations where available
• Key isolation: Keys never exposed in memory dumps
• Determinism: Same input produces same signature (where algorithm allows)
• Audit trail: All crypto operations logged

8) Performance targets

• SHA-256: > 500 MB/s on modern hardware
• BLAKE3: > 1 GB/s on modern hardware
• ECDSA P-256 sign: < 1ms per signature
• Ed25519 sign: < 0.5ms per signature
• HSM operations: < 50ms (network latency dependent)

9) Testing matrix

• Vector tests: NIST/RFC test vectors for each algorithm
• Interoperability: Cross-platform signature verification
• Determinism: Same key + data = same signature
• Plugin tests: Load/unload, availability detection
• HSM tests: SoftHSM or simulated-HSM harness for CI, real HSM for deployment integration

10) Offline Operation

For air-gapped deployments:

1. Offline key bundles: Pre-exported public keys for verification (the offline.verification provider is verification-only).
2. Local plugins: All providers loaded from the local filesystem; no network calls in crypto paths (per src/Cryptography/AGENTS.md).
3. No external crypto-service calls: All operations use local keys, the in-process PKCS#11 HSM, or a master KEK from a local/Vault source. The KEK env/file sources need no network; the Vault source talks only to the operator’s in-estate Vault. No cloud-KMS dependency exists in any path.
4. Trust bundles: Pre-configured trust roots; eIDAS advanced evidence uses sealed offline trust-material packs (§4.8), never live trust-list lookups.

11) Compliance profile preference persistence (CLI / UI parity)

The active compliance profile (world, fips, eidas, gost, sm, kcmvp) is a per-tenant preference. As of SPRINT_20260503_007 / B-FECRYPTO-002 the profile is persisted in a distinct table from provider routing:

Scope vs. policy (2026-05-30 reconciliation). A prior revision listed the ASP.NET authorization policy names (platform.crypto.admin / platform.crypto.profile.admin) in the “Scope” column. The canonical OAuth scope strings in the scope catalog (StellaOpsScopes.PlatformCryptoAdmin / PlatformCryptoProfileAdmin) are crypto:admin and crypto:profile:admin; the colon-delimited policy constants in PlatformPolicies.cs (platform.crypto.admin, …) are the distinct policy registration keys. The read scope is crypto:read (policy platform.crypto.read). The Audited(...) filter records the audit action under the platform module (AuditActions.Platform.UpdateCryptoPreference = update_crypto_preference, etc.); the endpoint description renders it platform.update_compliance_profile when module-qualified.

The two are kept orthogonal because changing the profile changes algorithm selection across hashing/MAC/AEAD for the entire tenant, which is more sensitive than provider routing — operators may grant the routing scope to a deployment engineer while reserving profile changes for a security officer.

The compliance-profile table is single-row-per-tenant and captures the prior value into previous_profile on every upsert, powering the audit payload’s before/after fields without an extra ledger lookup. Migration 069_TenantComplianceProfile.sql auto-applies via the existing AddStartupMigrations wiring per CoC §2.7.

The Console panel under src/Web/StellaOps.Web/src/app/features/settings/crypto-providers/ calls the new endpoint after a typed-confirmation dialog (the operator must type the target profile id to enable submit), surfaces the algorithm delta between current and target profile, and warns when the target profile is not in the compatibility matrix for the currently active provider.

CLI surface (2026-05-30 reconciliation). Two profile commands now coexist in src/Cli/StellaOps.Cli/Commands/CryptoCommandGroup.cs:

• stella crypto profile set <profile> (singular profile, SPRINT_20260529_028) is the dedicated compliance-profile command. It targets the compliance-profile store via HandleTenantProfileSetAsync and supports --reseal / --reseal-kek-id to drive a KEK re-seal so existing tenant rows migrate to the new algorithm (fips→AES-256-GCM, sm→SM4-GCM, gost→GOST-GCM, else AES-256-GCM). Companion verbs: stella crypto profile show and stella crypto profile validate (the latter wired against GET /api/v1/admin/crypto/profile/validate, which currently returns an endpoint_not_implemented payload until RP-028-013 lands the server side).
• stella crypto profiles list/select/show (plural profiles, the older SPRINT_20260117_012 / RCR-001 path) historically wrote through the provider-preference endpoint, smuggling the profile id into the providerId slot — recognised tech debt to migrate to the dedicated compliance-profile endpoint. The CLI’s local-YAML fallback (~/.stellaops/appsettings.crypto.yaml) and journal (~/.stellaops/audit/crypto-profile-select.jsonl) are unchanged.

See docs/modules/cli/architecture.md §23 and the parity row in docs/modules/cli/cli-vs-ui-parity.md §5b for the CLI contract details.

Related Documentation

• Multi-profile signing: ./multi-profile-signing-specification.md
• Signer module: ../signer/architecture.md
• Attestor module: ../attestor/architecture.md
• Offline operations: ../../OFFLINE_KIT.md