save progress
This commit is contained in:
StellaOps Bot
298
docs/modules/cryptography/architecture.md
Normal file
298
docs/modules/cryptography/architecture.md
Normal file
@@ -0,0 +1,298 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user