8.2 KiB
8.2 KiB
component_architecture_cryptography.md - Stella Ops Cryptography (2025Q4)
Pluggable cryptographic primitives supporting regional standards.
Scope. Library architecture for Cryptography: pluggable cryptographic primitives enabling sovereign operation with regional crypto requirements (eIDAS, FIPS, GOST, SM, PQ) while maintaining deterministic signing operations.
0) Mission & boundaries
Mission. Provide algorithm-agile cryptographic primitives that support regional compliance requirements while ensuring deterministic, reproducible signing operations across all StellaOps services.
Boundaries.
- Cryptography is a library layer, not a standalone service.
- Cryptography does not manage keys. Key storage is handled by KMS, HSM, or Signer.
- All cryptographic operations are deterministic for reproducibility.
- Supports offline operation without external crypto services.
1) Solution & project layout
src/Cryptography/
├─ StellaOps.Cryptography/ # Core abstractions and plugin loader
│ ├─ ICryptoHash.cs # Hash computation interface
│ ├─ ISignatureProvider.cs # Signature interface
│ ├─ IKeyProvider.cs # Key loading interface
│ ├─ CryptoProfileLoader.cs # Profile plugin loader
│ └─ DefaultCryptoHash.cs # Default SHA-256/BLAKE3 implementation
│
├─ StellaOps.Cryptography.Profiles.Ecdsa/ # ECDSA signing profile
│ ├─ EcdsaSignatureProvider.cs
│ └─ Curves/
│ ├─ P256Provider.cs # NIST P-256
│ ├─ P384Provider.cs # NIST P-384
│ └─ Secp256k1Provider.cs # Bitcoin curve
│
├─ StellaOps.Cryptography.Profiles.EdDsa/ # EdDSA signing profile
│ ├─ EdDsaSignatureProvider.cs
│ └─ Curves/
│ ├─ Ed25519Provider.cs
│ └─ Ed448Provider.cs
│
├─ plugins/ # External crypto plugins
│ ├─ gost/ # GOST R 34.10-2012 (Russia)
│ ├─ sm/ # SM2/SM3/SM4 (China)
│ ├─ eidas/ # eIDAS qualified signatures (EU)
│ └─ pq/ # Post-quantum (experimental)
│
└─ StellaOps.Cryptography.sln
Library projects under src/__Libraries/:
src/__Libraries/
├─ StellaOps.Cryptography.Tests/
├─ StellaOps.Cryptography.Plugin.CryptoPro/ # GOST via CryptoPro CSP
├─ StellaOps.Cryptography.Plugin.EIDAS/ # eIDAS qualified signatures
├─ StellaOps.Cryptography.Plugin.SmSoft/ # SM2 software implementation
├─ StellaOps.Cryptography.Plugin.SmRemote/ # SM2 via remote HSM
├─ StellaOps.Cryptography.Plugin.OfflineVerification/
├─ StellaOps.Cryptography.PluginLoader/
└─ StellaOps.Cryptography.Kms/ # KMS integration
2) External dependencies
- .NET Cryptography APIs - Built-in crypto primitives
- BouncyCastle (optional) - Extended algorithm support
- CryptoPro CSP (optional) - GOST support on Windows
- HSM/TPM (optional) - Hardware security modules
- KMS (optional) - Cloud key management services
3) Contracts & data model
3.1 Hash Computation
public interface ICryptoHash
{
string ComputeSha256(ReadOnlySpan<byte> data);
string ComputeBlake3(ReadOnlySpan<byte> data);
string ComputeHash(ReadOnlySpan<byte> data, HashAlgorithm algorithm);
}
public enum HashAlgorithm
{
Sha256,
Sha384,
Sha512,
Blake3_256,
Blake3_512,
Sm3, // China
Streebog256, // Russia (GOST R 34.11-2012)
Streebog512
}
3.2 Signature Provider
public interface ISignatureProvider
{
string AlgorithmId { get; }
string CurveId { get; }
Task<byte[]> SignAsync(
ReadOnlyMemory<byte> data,
IKeyProvider keyProvider,
CancellationToken ct);
Task<bool> VerifyAsync(
ReadOnlyMemory<byte> data,
ReadOnlyMemory<byte> signature,
ReadOnlyMemory<byte> publicKey,
CancellationToken ct);
}
3.3 Crypto Profile
public sealed record CryptoProfile
{
public required string ProfileId { get; init; }
public required string DisplayName { get; init; }
public required HashAlgorithm PreferredHash { get; init; }
public required string SignatureAlgorithm { get; init; }
public required string KeyType { get; init; }
public bool RequiresHsm { get; init; }
public IReadOnlyList<string>? AllowedCurves { get; init; }
}
4) Supported Profiles
4.1 Built-in Profiles
| Profile | Hash | Signature | Use Case |
|---|---|---|---|
ecdsa-p256 |
SHA-256 | ECDSA P-256 | Default, FIPS 140-2 |
ecdsa-p384 |
SHA-384 | ECDSA P-384 | Higher security |
eddsa-ed25519 |
SHA-512 | Ed25519 | Performance |
ecdsa-secp256k1 |
SHA-256 | ECDSA secp256k1 | Blockchain compat |
4.2 Plugin Profiles
| Profile | Hash | Signature | Region |
|---|---|---|---|
gost-2012 |
Streebog-256 | GOST R 34.10-2012 | Russia |
sm2 |
SM3 | SM2 | China |
eidas-rsa |
SHA-256 | RSA-PSS | EU (qualified) |
eidas-ecdsa |
SHA-256 | ECDSA P-256 | EU (qualified) |
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
public interface ICryptoPlugin
{
string PluginId { get; }
IReadOnlyList<CryptoProfile> Profiles { get; }
ISignatureProvider GetSignatureProvider(string profileId);
ICryptoHash GetHashProvider(string profileId);
Task<bool> IsAvailableAsync(CancellationToken ct);
}
6) Configuration (YAML)
Cryptography:
DefaultProfile: "ecdsa-p256"
Profiles:
ecdsa-p256:
Enabled: true
PreferredHash: "sha256"
eddsa-ed25519:
Enabled: true
PreferredHash: "sha512"
gost-2012:
Enabled: false # Requires CryptoPro
RequiresHsm: false
sm2:
Enabled: false
HsmEndpoint: "https://hsm.example.cn"
Plugins:
Directory: "/opt/stellaops/plugins/crypto"
AutoLoad: true
Hsm:
Provider: "pkcs11" # or "kms", "tpm"
LibraryPath: "/usr/lib/softhsm/libsofthsm2.so"
SlotId: 0
Kms:
Provider: "aws" # or "azure", "gcp", "vault"
Region: "us-east-1"
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: Mock HSM for CI, real HSM for integration
10) Offline Operation
For air-gapped deployments:
- Offline key bundles: Pre-exported public keys for verification
- Local plugins: All plugins loaded from local filesystem
- No KMS calls: All operations use local keys or HSM
- Trust bundles: Pre-configured trust roots
Related Documentation
- Multi-profile signing:
./multi-profile-signing-specification.md - Signer module:
../signer/architecture.md - Attestor module:
../attestor/architecture.md - Offline operations:
../../24_OFFLINE_KIT.md