# 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`