299 lines
8.2 KiB
Markdown
299 lines
8.2 KiB
Markdown
# 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
|
|
|
|
```csharp
|
|
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
|
|
|
|
```csharp
|
|
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
|
|
|
|
```csharp
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```csharp
|
|
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)
|
|
|
|
```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:
|
|
|
|
1. **Offline key bundles**: Pre-exported public keys for verification
|
|
2. **Local plugins**: All plugins loaded from local filesystem
|
|
3. **No KMS calls**: All operations use local keys or HSM
|
|
4. **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`
|