f0662dd45f
- Added DefaultCryptoHmac class implementing ICryptoHmac interface. - Introduced purpose-based HMAC computation methods. - Implemented verification methods for HMACs with constant-time comparison. - Created HmacAlgorithms and HmacPurpose classes for well-known identifiers. - Added compliance profile support for HMAC algorithms. - Included asynchronous methods for HMAC computation from streams.
235 lines
8.4 KiB
Markdown
235 lines
8.4 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 |
|
|
|
|
## 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.
|
|
|
|
## 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
|