108d1c64b3
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Findings Ledger CI / build-test (push) Has been cancelled
Findings Ledger CI / migration-validation (push) Has been cancelled
Scanner Analyzers / Discover Analyzers (push) Has been cancelled
Signals Reachability Scoring & Events / reachability-smoke (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
cryptopro-linux-csp / build-and-test (push) Has been cancelled
Scanner Analyzers / Validate Test Fixtures (push) Has been cancelled
Signals CI & Image / signals-ci (push) Has been cancelled
sm-remote-ci / build-and-test (push) Has been cancelled
Findings Ledger CI / generate-manifest (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Scanner Analyzers / Build Analyzers (push) Has been cancelled
Scanner Analyzers / Test Language Analyzers (push) Has been cancelled
Scanner Analyzers / Verify Deterministic Output (push) Has been cancelled
Signals Reachability Scoring & Events / sign-and-upload (push) Has been cancelled
260 lines
11 KiB
Markdown
260 lines
11 KiB
Markdown
# 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 via the native Linux CSP service (CryptoPro deb bundles, no Wine) when customers supply the 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
|