feat(api): Add Policy Registry API specification
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
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.
This commit is contained in:
StellaOps Bot
369
docs/contracts/authority-crypto-provider.md
Normal file
369
docs/contracts/authority-crypto-provider.md
Normal file
@@ -0,0 +1,369 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user