f6c22854a4
Some checks failed
AOC Guard CI / aoc-verify (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Findings Ledger CI / build-test (push) Has been cancelled
Findings Ledger CI / migration-validation (push) Has been cancelled
Findings Ledger CI / generate-manifest (push) Has been cancelled
mock-dev-release / package-mock-release (push) Has been cancelled
- Introduced OpenAPI specification for the StellaOps Policy Registry API, covering endpoints for verification policies, policy packs, snapshots, violations, overrides, sealed mode operations, and advisory staleness tracking. - Defined schemas, parameters, and responses for comprehensive API documentation. chore(scanner): Add global usings for scanner analyzers - Created GlobalUsings.cs to simplify namespace usage across analyzer libraries. feat(scanner): Implement Surface Service Collection Extensions - Added SurfaceServiceCollectionExtensions for dependency injection registration of surface analysis services. - Included methods for adding surface analysis, surface collectors, and entry point collectors to the service collection.
370 lines
14 KiB
Markdown
370 lines
14 KiB
Markdown
# 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 |
|