git.stella-ops.org/docs/contracts/crypto-provider-registry.md

# Crypto Provider Registry Contract

**Contract ID:** `CONTRACT-CRYPTO-PROVIDER-REGISTRY-010`
**Version:** 1.0
**Status:** Published
**Last Updated:** 2025-12-05

## Overview

This contract defines the ICryptoProviderRegistry interface for managing cryptographic providers across StellaOps modules. It supports pluggable crypto implementations including .NET default, FIPS 140-2, GOST (CryptoPro), and Chinese SM algorithms.

## Implementation References

- **Registry:** `src/Security/StellaOps.Security.Crypto/`
- **Providers:** `src/Security/StellaOps.Security.Crypto.Providers/`

## Interface Definition

### ICryptoProviderRegistry

```csharp
public interface ICryptoProviderRegistry
{
    /// <summary>
    /// Registers a crypto provider with the given identifier.
    /// </summary>
    void RegisterProvider(string providerId, ICryptoProvider provider);

    /// <summary>
    /// Gets a registered crypto provider by identifier.
    /// </summary>
    ICryptoProvider GetProvider(string providerId);

    /// <summary>
    /// Gets the default crypto provider.
    /// </summary>
    ICryptoProvider GetDefaultProvider();

    /// <summary>
    /// Lists all registered provider information.
    /// </summary>
    IReadOnlyList<CryptoProviderInfo> ListProviders();

    /// <summary>
    /// Checks if a provider is registered.
    /// </summary>
    bool HasProvider(string providerId);
}
```

### ICryptoProvider

```csharp
public interface ICryptoProvider
{
    /// <summary>
    /// Provider identifier.
    /// </summary>
    string ProviderId { get; }

    /// <summary>
    /// Provider display name.
    /// </summary>
    string DisplayName { get; }

    /// <summary>
    /// Supported algorithms.
    /// </summary>
    IReadOnlyList<string> SupportedAlgorithms { get; }

    /// <summary>
    /// Creates a hash algorithm instance.
    /// </summary>
    HashAlgorithm CreateHashAlgorithm(string algorithm);

    /// <summary>
    /// Creates a signature algorithm instance.
    /// </summary>
    AsymmetricAlgorithm CreateSignatureAlgorithm(string algorithm);

    /// <summary>
    /// Creates a key derivation function instance.
    /// </summary>
    KeyDerivationPrf CreateKdf(string algorithm);
}
```

### CryptoProviderInfo

```json
{
  "provider_id": "fips",
  "display_name": "FIPS 140-2 Provider",
  "version": "1.0.0",
  "supported_algorithms": [
    "SHA-256", "SHA-384", "SHA-512",
    "RSA-PSS", "ECDSA-P256", "ECDSA-P384"
  ],
  "compliance": ["FIPS 140-2"],
  "is_default": false
}
```

## Available Providers

### Default Provider

Standard .NET cryptography implementation.

| Provider ID | `default` |
|-------------|-----------|
| **Display Name** | .NET Cryptography |
| **Algorithms** | SHA-256, SHA-384, SHA-512, RSA, ECDSA, EdDSA |
| **Compliance** | None (platform default) |

### FIPS Provider

FIPS 140-2 validated cryptographic module.

| Provider ID | `fips` |
|-------------|--------|
| **Display Name** | FIPS 140-2 Provider |
| **Algorithms** | SHA-256, SHA-384, SHA-512, RSA-PSS, ECDSA-P256, ECDSA-P384 |
| **Compliance** | FIPS 140-2 |

### GOST Provider (CryptoPro)

Russian GOST cryptographic algorithms via CryptoPro CSP.

| Provider ID | `gost` |
|-------------|--------|
| **Display Name** | CryptoPro GOST |
| **Algorithms** | GOST R 34.11-2012 (Stribog), GOST R 34.10-2012 |
| **Compliance** | GOST, eIDAS (Russia) |

### SM Provider (China)

Chinese cryptographic algorithms.

| Provider ID | `sm` |
|-------------|------|
| **Display Name** | SM Crypto (China) |
| **Algorithms** | SM2 (signature), SM3 (hash), SM4 (encryption) |
| **Compliance** | GB/T (China National Standard) |

## Configuration

### Registration at Startup

```csharp
services.AddCryptoProviderRegistry(options =>
{
    options.DefaultProvider = "default";
    options.RegisterProvider<FipsCryptoProvider>("fips");
    options.RegisterProvider<GostCryptoProvider>("gost");
    options.RegisterProvider<SmCryptoProvider>("sm");
});
```

### Provider Selection

```csharp
var registry = serviceProvider.GetRequiredService<ICryptoProviderRegistry>();

// Get specific provider
var fipsProvider = registry.GetProvider("fips");

// Get default provider
var defaultProvider = registry.GetDefaultProvider();

// List all providers
var providers = registry.ListProviders();
```

## API Endpoints

### List Providers

```
GET /api/v1/crypto/providers

Response: 200 OK
{
  "providers": [
    {
      "provider_id": "default",
      "display_name": ".NET Cryptography",
      "supported_algorithms": [...],
      "is_default": true
    },
    {
      "provider_id": "fips",
      "display_name": "FIPS 140-2 Provider",
      "supported_algorithms": [...],
      "compliance": ["FIPS 140-2"]
    }
  ]
}
```

### Get Provider Details

```
GET /api/v1/crypto/providers/{provider_id}

Response: 200 OK
{
  "provider_id": "fips",
  "display_name": "FIPS 140-2 Provider",
  "version": "1.0.0",
  "supported_algorithms": [
    "SHA-256", "SHA-384", "SHA-512",
    "RSA-PSS", "ECDSA-P256", "ECDSA-P384"
  ],
  "compliance": ["FIPS 140-2"]
}
```

### Set Default Provider

```
PUT /api/v1/crypto/providers/default
Content-Type: application/json

{
  "provider_id": "fips"
}

Response: 200 OK
```

## Algorithm Mapping

### Hash Algorithms

| Algorithm | Default | FIPS | GOST | SM |
|-----------|---------|------|------|-----|
| SHA-256 | Yes | Yes | No | No |
| SHA-384 | Yes | Yes | No | No |
| SHA-512 | Yes | Yes | No | No |
| GOST R 34.11-2012 (256) | No | No | Yes | No |
| GOST R 34.11-2012 (512) | No | No | Yes | No |
| SM3 | No | No | No | Yes |

### Signature Algorithms

| Algorithm | Default | FIPS | GOST | SM |
|-----------|---------|------|------|-----|
| RSA-PSS | Yes | Yes | No | No |
| ECDSA-P256 | Yes | Yes | No | No |
| ECDSA-P384 | Yes | Yes | No | No |
| EdDSA | Yes | No | No | No |
| GOST R 34.10-2012 | No | No | Yes | No |
| SM2 | No | No | No | Yes |

## Usage Example

### Signing with GOST

```csharp
var registry = services.GetRequiredService<ICryptoProviderRegistry>();
var gostProvider = registry.GetProvider("gost");

using var algorithm = gostProvider.CreateSignatureAlgorithm("GOST R 34.10-2012");
var signature = algorithm.SignData(data, HashAlgorithmName.SHA256);
```

### Hashing with SM3

```csharp
var smProvider = registry.GetProvider("sm");
using var hash = smProvider.CreateHashAlgorithm("SM3");
var digest = hash.ComputeHash(data);
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `STELLAOPS_CRYPTO_DEFAULT_PROVIDER` | Default provider ID |
| `StellaOpsEnableCryptoPro` | Enable CryptoPro GOST (set to `true`) |
| `StellaOpsEnableSmCrypto` | Enable SM crypto (set to `true`) |
| `STELLAOPS_FIPS_MODE` | Enable FIPS mode |

## Unblocks

This contract unblocks the following tasks:

- EXCITITOR-CRYPTO-90-001

## Related Contracts

- [Verification Policy Contract](./verification-policy.md) - Algorithm selection
- [Sealed Mode Contract](./sealed-mode.md) - Offline crypto validation