# Authority Crypto Provider Contract

> **Status:** APPROVED
> **Version:** 1.0.0
> **Last Updated:** 2025-12-06
> **Owner:** Authority Core Guild
> **Unblocks:** AUTH-CRYPTO-90-001, SEC-CRYPTO-90-014, SCANNER-CRYPTO-90-001, ATTESTOR-CRYPTO-90-001

## Overview

This contract defines the Authority signing provider interface for StellaOps, enabling pluggable cryptographic backends including:
- **Software keys** (default) — ECDSA P-256/P-384, RSA, EdDSA
- **HSM integration** — PKCS#11, Cloud KMS (AWS, GCP, Azure)
- **Regional compliance** — CryptoPro GOST (R1), SM2/SM3 (CN), eIDAS (EU), FIPS 140-2

## Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                        Authority Crypto Provider                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │                     ISigningProvider Interface                           ││
│  │                                                                          ││
│  │  + Sign(data: byte[], keyId: string) → SignatureResult                  ││
│  │  + Verify(data: byte[], signature: byte[], keyId: string) → bool        ││
│  │  + GetPublicKey(keyId: string) → PublicKeyInfo                          ││
│  │  + ListKeys(filter: KeyFilter) → KeyInfo[]                              ││
│  │  + CreateKey(spec: KeySpec) → KeyInfo                                   ││
│  │  + RotateKey(keyId: string) → KeyInfo                                   ││
│  │  + ExportJWKS(keyIds: string[]) → JWKS                                  ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│                              │                                               │
│        ┌────────────────────┼────────────────────┐                          │
│        ▼                    ▼                    ▼                          │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐                    │
│  │   Software   │   │    PKCS#11   │   │   Cloud KMS  │                    │
│  │   Provider   │   │   Provider   │   │   Provider   │                    │
│  │              │   │              │   │              │                    │
│  │ • File keys  │   │ • HSM        │   │ • AWS KMS    │                    │
│  │ • Memory     │   │ • SmartCard  │   │ • GCP KMS    │                    │
│  │ • Vault      │   │ • CryptoPro  │   │ • Azure KV   │                    │
│  └──────────────┘   └──────────────┘   └──────────────┘                    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
```

## 1. ISigningProvider Interface

### 1.1 Core Methods

```csharp
/// <summary>
/// Pluggable cryptographic signing provider for Authority service.
/// </summary>
public interface ISigningProvider
{
    /// <summary>Provider identifier (e.g., "software", "pkcs11", "aws-kms")</summary>
    string ProviderId { get; }

    /// <summary>Supported algorithms by this provider</summary>
    IReadOnlyList<string> SupportedAlgorithms { get; }

    /// <summary>Sign data with the specified key</summary>
    Task<SignatureResult> SignAsync(
        byte[] data,
        string keyId,
        SigningOptions? options = null,
        CancellationToken ct = default);

    /// <summary>Verify a signature</summary>
    Task<bool> VerifyAsync(
        byte[] data,
        byte[] signature,
        string keyId,
        CancellationToken ct = default);

    /// <summary>Get public key information</summary>
    Task<PublicKeyInfo> GetPublicKeyAsync(
        string keyId,
        CancellationToken ct = default);

    /// <summary>List available keys</summary>
    Task<IReadOnlyList<KeyInfo>> ListKeysAsync(
        KeyFilter? filter = null,
        CancellationToken ct = default);

    /// <summary>Create a new key pair</summary>
    Task<KeyInfo> CreateKeyAsync(
        KeySpec spec,
        CancellationToken ct = default);

    /// <summary>Rotate a key (create new version)</summary>
    Task<KeyInfo> RotateKeyAsync(
        string keyId,
        CancellationToken ct = default);

    /// <summary>Export keys as JWKS for distributed verification</summary>
    Task<JsonWebKeySet> ExportJwksAsync(
        IEnumerable<string>? keyIds = null,
        CancellationToken ct = default);

    /// <summary>Import a public key for verification</summary>
    Task<KeyInfo> ImportPublicKeyAsync(
        byte[] keyData,
        string format,
        KeyMetadata? metadata = null,
        CancellationToken ct = default);
}
```

### 1.2 Supporting Types

```csharp
public record SignatureResult(
    byte[] Signature,
    string Algorithm,
    string KeyId,
    string? KeyVersion,
    DateTimeOffset Timestamp);

public record SigningOptions(
    string? Algorithm = null,
    bool IncludeTimestamp = true,
    string? Nonce = null);

public record PublicKeyInfo(
    string KeyId,
    string Algorithm,
    byte[] PublicKey,
    string Format,  // "PEM", "DER", "JWK"
    string? Fingerprint,
    DateTimeOffset? ExpiresAt);

public record KeyInfo(
    string KeyId,
    string Algorithm,
    KeyState State,
    DateTimeOffset CreatedAt,
    DateTimeOffset? ExpiresAt,
    string? CurrentVersion,
    IReadOnlyDictionary<string, string>? Metadata);

public enum KeyState
{
    Active,
    Disabled,
    PendingDeletion,
    Deleted
}

public record KeySpec(
    string Algorithm,
    int? KeySize = null,
    string? Purpose = null,  // "signing", "attestation", "authority"
    IReadOnlyDictionary<string, string>? Metadata = null,
    DateTimeOffset? ExpiresAt = null);

public record KeyFilter(
    string? Purpose = null,
    KeyState? State = null,
    string? Algorithm = null);
```

## 2. Supported Algorithms

### 2.1 Algorithm Registry

| Algorithm | OID | Key Size | Compliance | Provider Support |
|-----------|-----|----------|------------|------------------|
| **ES256** | 1.2.840.10045.4.3.2 | P-256 | FIPS, eIDAS | All |
| **ES384** | 1.2.840.10045.4.3.3 | P-384 | FIPS, eIDAS | All |
| **RS256** | 1.2.840.113549.1.1.11 | 2048+ | FIPS, eIDAS | All |
| **RS384** | 1.2.840.113549.1.1.12 | 2048+ | FIPS, eIDAS | All |
| **EdDSA** | 1.3.101.112 | Ed25519 | — | Software, some HSM |
| **PS256** | 1.2.840.113549.1.1.10 | 2048+ | FIPS | All |
| **GOST R 34.10-2012** | 1.2.643.7.1.1.1.1 | 256/512 | R1 | PKCS#11 (CryptoPro) |
| **SM2** | 1.2.156.10197.1.301 | 256 | CN | PKCS#11 |

### 2.2 Default Configuration

```yaml
# etc/authority.yaml
crypto:
  provider: software  # or: pkcs11, aws-kms, gcp-kms, azure-keyvault

  software:
    keys_path: /var/lib/stellaops/keys
    default_algorithm: ES256

  pkcs11:
    library_path: /usr/lib/libpkcs11.so
    slot_id: 0
    pin_env: AUTHORITY_HSM_PIN
    # For CryptoPro:
    # library_path: /opt/cprocsp/lib/amd64/libcapi20.so

  aws_kms:
    region: us-east-1
    key_alias_prefix: stellaops/

  azure_keyvault:
    vault_url: https://stellaops.vault.azure.net/

  gcp_kms:
    project: stellaops-prod
    location: global
    key_ring: attestation-keys

  # Regional compliance overrides
  compliance:
    ru:
      provider: pkcs11
      algorithms: [GOST-R-34.10-2012-256, GOST-R-34.10-2012-512]
      library_path: /opt/cprocsp/lib/amd64/libcapi20.so
    cn:
      provider: pkcs11
      algorithms: [SM2]
```

## 3. JWKS Export Requirements

### 3.1 JWKS Endpoint

The Authority service MUST expose a JWKS endpoint for distributed verification:

```
GET /.well-known/jwks.json
```

Response format:

```json
{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "x": "base64url-encoded-x",
      "y": "base64url-encoded-y",
      "kid": "attestation-key-001",
      "alg": "ES256",
      "use": "sig",
      "key_ops": ["verify"],
      "x5t#S256": "sha256-fingerprint"
    }
  ]
}
```

### 3.2 Key Rotation

When keys are rotated:
1. New key becomes `Active`, old key becomes `Disabled` (verification-only)
2. JWKS includes both keys during transition period
3. Old key removed after `rotation_grace_period` (default: 7 days)
4. All consuming services refresh JWKS on schedule or via webhook

### 3.3 Key Discovery Flow

```
┌──────────┐     ┌──────────┐     ┌──────────┐
│  Scanner │     │ Authority │    │ Attestor │
└────┬─────┘     └────┬─────┘     └────┬─────┘
     │                │                 │
     │  GET /jwks.json│                 │
     │───────────────>│                 │
     │<───────────────│                 │
     │    JWKS        │                 │
     │                │                 │
     │  Sign(SBOM)    │                 │
     │───────────────>│                 │
     │<───────────────│                 │
     │  Signature     │                 │
     │                │                 │
     │                │  GET /jwks.json │
     │                │<────────────────│
     │                │────────────────>│
     │                │     JWKS        │
     │                │                 │
     │                │  Verify(SBOM)   │
     │                │<────────────────│
     │                │  ✓ Valid        │
```

## 4. Provider Registration

### 4.1 Service Registration

```csharp
// Program.cs
services.AddAuthoritySigningProvider(options =>
{
    options.Provider = configuration["Crypto:Provider"];
    options.Configuration = configuration.GetSection("Crypto");
});

// Extension method
public static IServiceCollection AddAuthoritySigningProvider(
    this IServiceCollection services,
    Action<CryptoProviderOptions> configure)
{
    var options = new CryptoProviderOptions();
    configure(options);

    return options.Provider switch
    {
        "software" => services.AddSingleton<ISigningProvider, SoftwareSigningProvider>(),
        "pkcs11" => services.AddSingleton<ISigningProvider, Pkcs11SigningProvider>(),
        "aws-kms" => services.AddSingleton<ISigningProvider, AwsKmsSigningProvider>(),
        "gcp-kms" => services.AddSingleton<ISigningProvider, GcpKmsSigningProvider>(),
        "azure-keyvault" => services.AddSingleton<ISigningProvider, AzureKeyVaultSigningProvider>(),
        _ => throw new ArgumentException($"Unknown provider: {options.Provider}")
    };
}
```

### 4.2 Regional Provider Registry

For multi-region deployments with compliance requirements:

```yaml
# Regional key registry
key_registry:
  attestation-sbom:
    default:
      key_id: "stellaops/attestation-sbom-001"
      algorithm: ES256
      provider: aws-kms
    ru:
      key_id: "ru/attestation-sbom-gost"
      algorithm: GOST-R-34.10-2012-256
      provider: pkcs11
    cn:
      key_id: "cn/attestation-sbom-sm2"
      algorithm: SM2
      provider: pkcs11
```

## 5. Error Codes

| Code | Name | Description |
|------|------|-------------|
| `CRYPTO_001` | `KEY_NOT_FOUND` | Requested key does not exist |
| `CRYPTO_002` | `KEY_DISABLED` | Key is disabled and cannot sign |
| `CRYPTO_003` | `ALGORITHM_UNSUPPORTED` | Algorithm not supported by provider |
| `CRYPTO_004` | `HSM_UNAVAILABLE` | HSM/PKCS#11 device not available |
| `CRYPTO_005` | `SIGNATURE_FAILED` | Signing operation failed |
| `CRYPTO_006` | `VERIFICATION_FAILED` | Signature verification failed |
| `CRYPTO_007` | `KEY_EXPIRED` | Key has expired |
| `CRYPTO_008` | `COMPLIANCE_VIOLATION` | Algorithm not allowed by compliance profile |

## 6. Tasks Unblocked

This contract unblocks:

| Task ID | Description | Status |
|---------|-------------|--------|
| AUTH-CRYPTO-90-001 | Authority signing provider contract | ✅ UNBLOCKED |
| SEC-CRYPTO-90-014 | Security Guild crypto integration | ✅ UNBLOCKED |
| SCANNER-CRYPTO-90-001 | Scanner SBOM signing | ✅ UNBLOCKED |
| ATTESTOR-CRYPTO-90-001 | Attestor DSSE signing | ✅ UNBLOCKED |

## 7. Changelog

| Date | Version | Change |
|------|---------|--------|
| 2025-12-06 | 1.0.0 | Initial contract with interface, algorithms, JWKS, regional support |