# 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:

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

```bash
# 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 / SM2**: Software baseline (`cn.sm.soft`) plus a containerized remote microservice (`cn.sm.remote.http`) that simulates SM2 signing/verification; swap the endpoint to a hardware-backed service when licensed hardware is provided.
- **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.
  Deterministic test vectors live in `src/__Libraries/StellaOps.Cryptography.Tests/PqSoftCryptoProviderTests.cs` (fixed seeds/keys) and `etc/rootpack/pq-vectors.txt` for offline verification.

## 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

```csharp
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

```csharp
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:

```csharp
[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](password-hashing.md) - Credential storage standards
- [Trust and Signing](trust-and-signing.md) - Signing key management
- [Crypto Registry Decision](crypto-registry-decision-2025-11-18.md) - Provider architecture
- [Crypto Routing Audit](crypto-routing-audit-2025-11-07.md) - Audit trail