git.stella-ops.org/docs/security/crypto-compliance.md

Cryptographic Compliance Profiles

This document describes the cryptographic compliance profile system in StellaOps, which enables region-specific cryptographic algorithm selection while maintaining interoperability with external systems.

Overview

StellaOps supports multiple cryptographic compliance profiles to meet regional regulatory requirements:

Profile	Standard	Region	Use Case
world	ISO/Default	International	Default profile, uses BLAKE3 for graph hashing
fips	FIPS 140-3	US Federal	US government and contractors
gost	GOST R 34.11-2012	Russia	Russian Federation compliance
sm	GB/T 32905-2016	China	Chinese national standards
kcmvp	KCMVP	South Korea	Korean cryptographic validation
eidas	eIDAS/ETSI TS 119 312	European Union	EU digital identity and trust

Certification caveats (current baselines)

• fips and eidas now route through software allow-listed providers (fips.ecdsa.soft, eu.eidas.soft) and are labeled non-certified until a CMVP/QSCD module is attached (set FIPS_SOFT_ALLOWED=1 / EIDAS_SOFT_ALLOWED=1).
• kcmvp is covered by a hash-only baseline provider (kr.kcmvp.hash, SHA-256) with the KCMVP_HASH_ALLOWED gate; ARIA/SEED/KCDSA remain pending.
• gost has a Linux-ready OpenSSL baseline plus a Wine sidecar for CryptoPro CSP (ru.winecsp.http); native Windows CSP stays blocked on licensed runners.
• sm uses software SM2/SM3 (cn.sm.soft, gate SM_SOFT_ALLOWED=1); hardware PKCS#11 validation remains pending.
• pq uses software-only Dilithium3 and Falcon512 (pq.soft, gate PQ_SOFT_ALLOWED=1); certified PQ modules are not available.

Provider identifiers (registry names)

• FIPS: fips.ecdsa.soft
• eIDAS: eu.eidas.soft
• KCMVP hash baseline: kr.kcmvp.hash
• PQ (Dilithium3/Falcon512): pq.soft
• RU GOST (Wine sidecar): ru.winecsp.http
• CN SM software: cn.sm.soft

Configuration

Set the compliance profile via environment variable or configuration:

# appsettings.yaml
Crypto:
  ProfileId: "world"  # Options: world, fips, gost, sm, kcmvp, eidas

# Environment variable
export STELLAOPS_CRYPTO_PROFILE=fips

Hash Algorithm Mapping

Each profile maps hash purposes to specific algorithms:

Hash Purposes

Purpose	Description	Typical Usage
Graph	Content-addressed graph nodes	Advisory deduplication, SBOM nodes
Symbol	Symbol/identifier hashing	Package identifiers, CVE IDs
Content	General content hashing	File digests, payload hashes
Merkle	Merkle tree construction	Attestation verification
Attestation	in-toto/DSSE attestation	Provenance statements
Interop	External tool compatibility	Sigstore, Rekor, external APIs
Secret	Password/secret hashing	User credentials

Algorithm Selection by Profile

Purpose	world	fips	gost	sm	kcmvp	eidas
Graph	BLAKE3-256	SHA-256	GOST-3411-256	SM3	SHA-256	SHA-256
Symbol	SHA-256	SHA-256	GOST-3411-256	SM3	SHA-256	SHA-256
Content	SHA-256	SHA-256	GOST-3411-256	SM3	SHA-256	SHA-256
Merkle	SHA-256	SHA-256	GOST-3411-256	SM3	SHA-256	SHA-256
Attestation	SHA-256	SHA-256	GOST-3411-256	SM3	SHA-256	SHA-256
Interop	SHA-256	SHA-256	SHA-256	SHA-256	SHA-256	SHA-256
Secret	Argon2id	PBKDF2-SHA256	Argon2id	Argon2id	Argon2id	Argon2id

Note: The Interop purpose always uses SHA-256 regardless of profile to ensure compatibility with external tools.

HMAC Algorithm Mapping

HMAC operations use purpose-based selection similar to hashing:

HMAC Purposes

Purpose	Description	Typical Usage
Signing	DSSE envelope signing	Attestations, manifests, bundles
Authentication	Token/URL authentication	Signed URLs, ack tokens
WebhookInterop	External webhook compatibility	Third-party webhook receivers

HMAC Algorithm Selection by Profile

Purpose	world	fips	gost	sm	kcmvp	eidas
Signing	HMAC-SHA256	HMAC-SHA256	HMAC-GOST3411	HMAC-SM3	HMAC-SHA256	HMAC-SHA256
Authentication	HMAC-SHA256	HMAC-SHA256	HMAC-GOST3411	HMAC-SM3	HMAC-SHA256	HMAC-SHA256
WebhookInterop	HMAC-SHA256	HMAC-SHA256	HMAC-SHA256	HMAC-SHA256	HMAC-SHA256	HMAC-SHA256

Note: The WebhookInterop purpose always uses HMAC-SHA256 regardless of profile. This is required for compatibility with external webhook receivers (Slack, Teams, GitHub, etc.) that expect SHA-256 signatures.

Simulation paths when hardware is missing

• RU / GOST: Linux baseline uses ru.openssl.gost; CryptoPro CSP can be exercised from Linux via the Wine sidecar service (ru.winecsp.http) built from scripts/crypto/setup-wine-csp-service.sh when customers supply the CSP installer. Windows CSP remains blocked until licensed runners are available.
• CN / SM: Software-only SM2/SM3 provider (cn.sm.soft) backed by BouncyCastle; enable with SM_SOFT_ALLOWED=1. Hardware PKCS#11 tokens can be added later without changing feature code because hosts resolve via ICryptoProviderRegistry.
• FIPS / eIDAS: Software allow-lists (fips.ecdsa.soft, eu.eidas.soft) enforce ES256/ES384 + SHA-2. They are labeled non-certified until a CMVP/QSCD module is supplied.
• KCMVP: Hash-only baseline (kr.kcmvp.hash) keeps SHA-256 available when ARIA/SEED/KCDSA hardware is absent.
• PQ (Dilithium3/Falcon512): Software-only pq.soft provider using BouncyCastle PQC primitives; gated by PQ_SOFT_ALLOWED=1. Certified PQ hardware is not yet available.

Interoperability Exceptions

Certain operations must use SHA-256 regardless of compliance profile to maintain external compatibility:

Hash Interop Exceptions

Component	File	Reason
Sigstore/Rekor	Various attestation paths	Transparency log compatibility
OCI Registry	Image digest computation	Registry API specification
SBOM Export	CycloneDX/SPDX export	Standard requires SHA-256
External APIs	Webhook payloads	Third-party API requirements

HMAC Interop Exceptions

Component	File	Reason
Webhook Signatures	DefaultWebhookSecurityService.cs	External receiver compatibility
Third-party Integrations	Various	API specification requirements

Code Usage

Using ICryptoHash

public class MyService
{
    private readonly ICryptoHash _cryptoHash;

    public MyService(ICryptoHash cryptoHash)
    {
        _cryptoHash = cryptoHash;
    }

    public string ComputeContentHash(byte[] data)
    {
        // Uses profile-appropriate algorithm (SHA-256, GOST, SM3, etc.)
        return _cryptoHash.ComputeHashHexForPurpose(data, HashPurpose.Content);
    }

    public string ComputeInteropHash(byte[] data)
    {
        // Always SHA-256 for external compatibility
        return _cryptoHash.ComputeHashHexForPurpose(data, HashPurpose.Interop);
    }
}

Using ICryptoHmac

public class MySigningService
{
    private readonly ICryptoHmac _cryptoHmac;

    public MySigningService(ICryptoHmac cryptoHmac)
    {
        _cryptoHmac = cryptoHmac;
    }

    public string SignEnvelope(byte[] key, byte[] payload)
    {
        // Uses profile-appropriate algorithm (HMAC-SHA256, HMAC-GOST3411, HMAC-SM3)
        return _cryptoHmac.ComputeHmacBase64ForPurpose(key, payload, HmacPurpose.Signing);
    }

    public string SignWebhook(byte[] key, byte[] payload)
    {
        // Always HMAC-SHA256 for external webhook compatibility
        return _cryptoHmac.ComputeHmacHexForPurpose(key, payload, HmacPurpose.WebhookInterop);
    }

    public bool VerifyToken(byte[] key, byte[] data, byte[] expectedHmac)
    {
        // Constant-time comparison
        return _cryptoHmac.VerifyHmacForPurpose(key, data, expectedHmac, HmacPurpose.Authentication);
    }
}

Test Usage

For unit tests, use the factory methods:

[Fact]
public void TestHashComputation()
{
    var cryptoHash = DefaultCryptoHash.CreateForTests();
    var hash = cryptoHash.ComputeHashHexForPurpose(data, HashPurpose.Content);
    Assert.NotEmpty(hash);
}

[Fact]
public void TestHmacComputation()
{
    var cryptoHmac = DefaultCryptoHmac.CreateForTests();
    var hmac = cryptoHmac.ComputeHmacHexForPurpose(key, data, HmacPurpose.Signing);
    Assert.NotEmpty(hmac);
}

Supported Algorithms

Hash Algorithms

Algorithm	Output Size	Standard	Profiles
BLAKE3-256	32 bytes	BLAKE3 spec	world (Graph only)
SHA-256	32 bytes	FIPS 180-4	world, fips, kcmvp, eidas
SHA-384	48 bytes	FIPS 180-4	Available for future use
SHA-512	64 bytes	FIPS 180-4	Available for future use
GOST R 34.11-2012 (Stribog-256)	32 bytes	GOST R 34.11-2012	gost
SM3	32 bytes	GB/T 32905-2016	sm

HMAC Algorithms

Algorithm	Output Size	Standard	Profiles
HMAC-SHA256	32 bytes	FIPS 198-1	world, fips, kcmvp, eidas
HMAC-SHA384	48 bytes	FIPS 198-1	Available for future use
HMAC-SHA512	64 bytes	FIPS 198-1	Available for future use
HMAC-GOST3411	32 bytes	RFC 6986	gost
HMAC-SM3	32 bytes	GB/T 32905-2016	sm

Password Hashing Algorithms

Algorithm	Standard	Profiles
Argon2id	RFC 9106	world, gost, sm, kcmvp, eidas
PBKDF2-SHA256	FIPS 140-3	fips

Security Considerations

1. Algorithm Agility: The purpose-based abstraction allows algorithm upgrades without code changes.

2. Constant-Time Comparison: All HMAC verification uses CryptographicOperations.FixedTimeEquals() to prevent timing attacks.

3. Key Derivation: HKDF is used where appropriate for deriving keys from shared secrets.

4. Interop Safety: External-facing operations are locked to SHA-256/HMAC-SHA256 to prevent protocol confusion.

5. Profile Isolation: Each deployment uses exactly one profile; mixed-profile operation is not supported.

Related Documents

• Password Hashing - Credential storage standards
• Trust and Signing - Signing key management
• Crypto Registry Decision - Provider architecture
• Crypto Routing Audit - Audit trail