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

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

/// <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

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

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

{
  "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

// 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:

# 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