Add property-based tests for SBOM/VEX document ordering and Unicode normalization determinism
- Implement `SbomVexOrderingDeterminismProperties` for testing component list and vulnerability metadata hash consistency. - Create `UnicodeNormalizationDeterminismProperties` to validate NFC normalization and Unicode string handling. - Add project file for `StellaOps.Testing.Determinism.Properties` with necessary dependencies. - Introduce CI/CD template validation tests including YAML syntax checks and documentation content verification. - Create validation script for CI/CD templates ensuring all required files and structures are present.
This commit is contained in:
StellaOps Bot
@@ -0,0 +1,56 @@
|
||||
# Sprint 20251226 · CI/CD Release Gate Integration
|
||||
|
||||
## Topic & Scope
|
||||
- Wire existing `DriftGateEvaluator` into CI/CD pipelines for automated release gating.
|
||||
- Provide webhook endpoint for Zastava/registry triggers, scheduler job integration, and CI exit codes.
|
||||
- Deliver example workflows for GitHub Actions and GitLab CI.
|
||||
- **Working directory:** `src/Policy/StellaOps.Policy.Engine`, `src/Scheduler/StellaOps.Scheduler`
|
||||
|
||||
## Dependencies & Concurrency
|
||||
- Depends on: `DriftGateEvaluator` (complete), `DeltaComputer` (complete), `DeltaVerdict` (complete).
|
||||
- Can run in parallel with: SPRINT_20251226_005_SCANNER (reachability extractors).
|
||||
- Blocks: SPRINT_20251226_004_FE (dashboard needs API endpoints from this sprint).
|
||||
|
||||
## Documentation Prerequisites
|
||||
- `docs/modules/policy/architecture.md`
|
||||
- `docs/modules/scheduler/architecture.md`
|
||||
- `docs/modules/zastava/architecture.md`
|
||||
- `CLAUDE.md` (project conventions)
|
||||
|
||||
## Delivery Tracker
|
||||
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 1 | CICD-GATE-01 | DONE | None | Policy Guild | Create `POST /api/v1/policy/gate/evaluate` endpoint accepting image digest + baseline ref; returns `DeltaVerdict` with Pass/Warn/Fail status |
|
||||
| 2 | CICD-GATE-02 | DONE | CICD-GATE-01 | Policy Guild | Add webhook handler for Zastava image-push events; trigger async gate evaluation job |
|
||||
| 3 | CICD-GATE-03 | TODO | CICD-GATE-01 | Scheduler Guild | Create `GateEvaluationJob` in Scheduler; wire to Policy Engine gate endpoint |
|
||||
| 4 | CICD-GATE-04 | DONE | CICD-GATE-01 | Policy Guild | Define CI exit codes: 0=Pass, 1=Warn (configurable pass-through), 2=Fail/Block |
|
||||
| 5 | CICD-GATE-05 | DONE | CICD-GATE-04 | Policy Guild | CLI command `stella gate evaluate --image <digest> --baseline <ref>` with exit code support |
|
||||
| 6 | CICD-GATE-06 | DONE | CICD-GATE-02 | Policy Guild | Gate bypass audit logging: record who/when/why for any override; persist to audit table |
|
||||
| 7 | CICD-GATE-07 | DONE | CICD-GATE-05 | DevOps Guild | GitHub Actions example workflow using `stella gate evaluate` |
|
||||
| 8 | CICD-GATE-08 | DONE | CICD-GATE-05 | DevOps Guild | GitLab CI example workflow using `stella gate evaluate` |
|
||||
| 9 | CICD-GATE-09 | TODO | CICD-GATE-03 | Policy Guild + Zastava Guild | Integration tests: Zastava webhook -> Scheduler -> Policy Engine -> verdict |
|
||||
| 10 | CICD-GATE-10 | TODO | CICD-GATE-09 | Policy Guild | Documentation: update `docs/modules/policy/architecture.md` with gate API section |
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2025-12-26 | Sprint created from product advisory analysis; consolidates diff-aware release gate requirements. | Project Mgmt |
|
||||
| 2025-12-26 | CICD-GATE-01, CICD-GATE-04 DONE. Created GateEndpoints.cs and GateContracts.cs with POST /api/v1/policy/gate/evaluate endpoint. Defined GateStatus enum and GateExitCodes constants (0=Pass, 1=Warn, 2=Fail). | Impl |
|
||||
| 2025-12-26 | BLOCKED: Policy.Gateway build fails due to pre-existing errors in PostgresBudgetStore.cs (missing RiskBudget, BudgetEntry, IBudgetStore types from incomplete sprint). New gate files compile successfully when isolated. | Impl |
|
||||
| 2025-12-26 | UNBLOCKED: Fixed pre-existing build errors in Policy.Storage.Postgres (ServiceCollectionExtensions interface alias), Telemetry.Core (TagList using), Replay.Core (duplicate CompressionAlgorithm, missing interface methods, Span conversions), and Policy.Engine (OperationalContext/MitigationFactors property mapping). Policy.Gateway now builds successfully. | Impl |
|
||||
| 2025-12-26 | CICD-GATE-02 DONE. Created RegistryWebhookEndpoints.cs with Docker Registry v2, Harbor, and generic webhook handlers at /api/v1/webhooks/registry/*. Created InMemoryGateEvaluationQueue.cs with Channel-based async queue and GateEvaluationWorker background service. Fixed duplicate IBudgetStore interface (consolidated in BudgetLedger.cs with ListAsync method). | Impl |
|
||||
| 2025-12-26 | CICD-GATE-05 DONE. Created GateCommandGroup.cs with `stella gate evaluate` and `stella gate status` commands. Supports --image, --baseline, --policy, --allow-override, --justification options. Returns GateExitCodes (0=Pass, 1=Warn, 2=Fail, 10+=errors). Outputs table/JSON formats via Spectre.Console. Registered in CommandFactory.cs. | Impl |
|
||||
| 2025-12-26 | CICD-GATE-06 DONE. Created GateBypassAuditEntry, IGateBypassAuditRepository, InMemoryGateBypassAuditRepository, and GateBypassAuditor service. Integrated into GateEndpoints to record bypasses with actor, justification, IP, and CI context. Includes rate limiting support. | Impl |
|
||||
| 2025-12-26 | CICD-GATE-07, CICD-GATE-08 DONE. Created GitHub Actions example workflow (.github/workflows/stellaops-gate-example.yml) and GitLab CI example (deploy/gitlab/stellaops-gate-example.gitlab-ci.yml). Both demonstrate gate evaluation, baseline strategies, override workflows, and deployment gating. | Impl |
|
||||
| 2025-12-26 | Sprint archived. Core gate endpoint, CLI, webhook handlers, audit logging, and CI examples complete. Remaining tasks (CICD-GATE-03, 09, 10) are Scheduler integration and documentation - can be done in follow-up sprint. | Impl |
|
||||
|
||||
## Decisions & Risks
|
||||
- Decision needed: Should Warn status block CI by default or pass-through? Recommend: configurable per-environment.
|
||||
- Decision needed: Gate evaluation timeout for long-running reachability analysis. Recommend: 60s default, configurable.
|
||||
- Risk: High evaluation latency may slow CI pipelines. Mitigation: async evaluation with cached baseline snapshots.
|
||||
- Risk: Gate bypass abuse. Mitigation: audit logging + Authority scope enforcement for bypass permission.
|
||||
|
||||
## Next Checkpoints
|
||||
- 2025-12-30 | CICD-GATE-01 complete | Gate endpoint accepting requests |
|
||||
- 2026-01-03 | CICD-GATE-05 complete | CLI integration verified |
|
||||
- 2026-01-06 | CICD-GATE-09 complete | End-to-end integration tested |
|
||||
@@ -0,0 +1,507 @@
|
||||
# SPRINT_20251226_001_SIGNER_fulcio_keyless_client
|
||||
|
||||
**Sprint ID:** 20251226_001_SIGNER
|
||||
**Topic:** Fulcio Keyless Signing Client Implementation
|
||||
**Status:** PARTIAL (Core implementation complete, remaining tasks are integration tests and docs)
|
||||
**Priority:** P0 (Critical Path)
|
||||
**Created:** 2025-12-26
|
||||
**Working Directory:** `src/Signer/`
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Implement Sigstore Fulcio integration for keyless signing in CI/CD pipelines. This enables ephemeral X.509 certificates (~10 min TTL) obtained via OIDC identity tokens, eliminating the need for persistent signing keys in CI environments while maintaining cryptographic non-repudiation through Rekor transparency logging.
|
||||
|
||||
**Business Value:**
|
||||
- Zero key management overhead in CI pipelines
|
||||
- Eliminates credential sprawl and secret rotation complexity
|
||||
- Enables audit-grade non-repudiation via OIDC identity binding
|
||||
- Aligns with Sigstore industry standard (adopted by Kubernetes, npm, PyPI)
|
||||
|
||||
**Dependencies:**
|
||||
- Attestor module for Rekor submission (Sprint 20251226_002)
|
||||
- Authority module for OIDC token minting (existing)
|
||||
- RFC 8785 canonicalization (existing in `StellaOps.Canonicalization`)
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
**Required Reading (complete before DOING):**
|
||||
- [ ] `docs/modules/signer/architecture.md` - Signer architecture dossier
|
||||
- [ ] `docs/modules/attestor/architecture.md` - Attestor architecture (§2.1 for Rekor)
|
||||
- [ ] `CLAUDE.md` - Project coding standards
|
||||
- [ ] `src/Signer/AGENTS.md` - Module charter (if exists, create if not)
|
||||
- [ ] Sigstore Fulcio documentation: https://docs.sigstore.dev/certificate_authority/overview/
|
||||
|
||||
**Technical Prerequisites:**
|
||||
- [ ] Authority OIDC endpoint operational (`/oauth/token`)
|
||||
- [ ] BouncyCastle crypto library available for ECDSA/Ed25519
|
||||
- [ ] HTTP/2 client infrastructure for Fulcio API calls
|
||||
|
||||
---
|
||||
|
||||
## Scope & Boundaries
|
||||
|
||||
### In Scope
|
||||
- Fulcio OIDC client implementation
|
||||
- Ephemeral keypair generation (ECDSA P-256, Ed25519)
|
||||
- Certificate chain handling and validation
|
||||
- Integration with existing `IDsseSigner` interface
|
||||
- Configuration schema for Fulcio endpoints
|
||||
- Unit and integration tests
|
||||
|
||||
### Out of Scope
|
||||
- Rekor submission (handled by Attestor - Sprint 002)
|
||||
- Bundle rotation workflows (Sprint 002)
|
||||
- CLI integration (Sprint 003)
|
||||
- CI/CD templates (Sprint 004)
|
||||
|
||||
### Guardrails
|
||||
- No hard-coded external URLs; all endpoints configurable
|
||||
- Ephemeral keys MUST NOT persist to disk
|
||||
- Certificate chains MUST validate to configured Fulcio roots
|
||||
- All timestamps in UTC ISO-8601
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Component Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Signer Service │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ │
|
||||
│ │ SignerPipeline │───▶│ IDsseSigner │ │
|
||||
│ └──────────────────┘ └────────┬─────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────────────────────┼───────────────────────┐ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌────────────────┐ ┌──────────────────┐ ┌──────────────┐ │
|
||||
│ │ CryptoDsseSigner│ │ KeylessDsseSigner│ │ KmsDsseSigner │ │
|
||||
│ │ (existing) │ │ (NEW) │ │ (existing) │ │
|
||||
│ └────────────────┘ └────────┬─────────┘ └──────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────┴────────────┐ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ │
|
||||
│ │ IFulcioClient │ │ IEphemeralKeyGen │ │
|
||||
│ │ (NEW) │ │ (NEW) │ │
|
||||
│ └────────┬─────────┘ └──────────────────┘ │
|
||||
│ │ │
|
||||
└────────────────────┼────────────────────────────────────────────┘
|
||||
│
|
||||
▼ HTTPS (mTLS optional)
|
||||
┌──────────────────┐
|
||||
│ Fulcio CA │
|
||||
│ (external) │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
### New Interfaces
|
||||
|
||||
```csharp
|
||||
// src/Signer/__Libraries/StellaOps.Signer.Keyless/IFulcioClient.cs
|
||||
public interface IFulcioClient
|
||||
{
|
||||
Task<FulcioCertificateResult> GetCertificateAsync(
|
||||
FulcioCertificateRequest request,
|
||||
CancellationToken cancellationToken = default);
|
||||
}
|
||||
|
||||
public record FulcioCertificateRequest(
|
||||
byte[] PublicKey,
|
||||
string Algorithm, // "ECDSA_P256" | "Ed25519"
|
||||
string OidcIdentityToken,
|
||||
string? ProofOfPossession); // Optional signed challenge
|
||||
|
||||
public record FulcioCertificateResult(
|
||||
byte[] Certificate,
|
||||
byte[][] CertificateChain,
|
||||
string SignedCertificateTimestamp,
|
||||
DateTimeOffset NotBefore,
|
||||
DateTimeOffset NotAfter,
|
||||
FulcioIdentity Identity);
|
||||
|
||||
public record FulcioIdentity(
|
||||
string Issuer,
|
||||
string Subject,
|
||||
string? SubjectAlternativeName);
|
||||
```
|
||||
|
||||
```csharp
|
||||
// src/Signer/__Libraries/StellaOps.Signer.Keyless/IEphemeralKeyGenerator.cs
|
||||
public interface IEphemeralKeyGenerator
|
||||
{
|
||||
EphemeralKeyPair Generate(string algorithm);
|
||||
void Dispose(EphemeralKeyPair keyPair); // Secure erasure
|
||||
}
|
||||
|
||||
public sealed class EphemeralKeyPair : IDisposable
|
||||
{
|
||||
public byte[] PublicKey { get; }
|
||||
public byte[] PrivateKey { get; } // In-memory only, never persisted
|
||||
public string Algorithm { get; }
|
||||
public DateTimeOffset CreatedAt { get; }
|
||||
|
||||
public void Dispose(); // Zeros memory
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Delivery Tracker
|
||||
|
||||
| ID | Task | Owner | Status | Dependencies | Acceptance Criteria |
|
||||
|----|------|-------|--------|--------------|---------------------|
|
||||
| 0001 | Create `StellaOps.Signer.Keyless` library project | — | DONE | — | Project compiles, referenced by Signer.Infrastructure |
|
||||
| 0002 | Implement `IEphemeralKeyGenerator` interface | — | DONE | 0001 | Generates ECDSA P-256 and Ed25519 keypairs |
|
||||
| 0003 | Implement `EphemeralKeyPair` with secure disposal | — | DONE | 0002 | Memory zeroed on Dispose(), finalizer backup |
|
||||
| 0004 | Implement `IFulcioClient` interface | — | DONE | 0001 | Contract defined, mockable |
|
||||
| 0005 | Implement `HttpFulcioClient` | — | DONE | 0004 | HTTP/2 client, retries, circuit breaker |
|
||||
| 0006 | Add Fulcio response parsing (X.509 chain) | — | DONE | 0005 | PEM/DER parsing, chain ordering |
|
||||
| 0007 | Implement `KeylessDsseSigner` | — | DONE | 0003, 0006 | Signs DSSE with ephemeral key + Fulcio cert |
|
||||
| 0008 | Add `verdict.stella/v1` predicate type | — | DONE | — | PredicateTypes.cs updated, schema defined |
|
||||
| 0009 | Add configuration schema `SignerKeylessOptions` | — | DONE | 0005 | YAML/JSON config, validation |
|
||||
| 0010 | Wire DI registration in `ServiceCollectionExtensions` | — | DONE | 0007, 0009 | `services.AddKeylessSigning()` |
|
||||
| 0011 | Implement certificate chain validation | — | DONE | 0006 | Validates to configured Fulcio roots |
|
||||
| 0012 | Add OIDC token acquisition from Authority | — | DONE | — | Client credentials flow, caching |
|
||||
| 0013 | Unit tests: EphemeralKeyGenerator | — | DONE | 0003 | Key generation, disposal, algorithm coverage |
|
||||
| 0014 | Unit tests: HttpFulcioClient (mocked) | — | TODO | 0005 | Happy path, error handling, retries |
|
||||
| 0015 | Unit tests: KeylessDsseSigner | — | DONE | 0007 | Signing roundtrip, cert attachment |
|
||||
| 0016 | Unit tests: Certificate chain validation | — | TODO | 0011 | Valid chain, expired cert, untrusted root |
|
||||
| 0017 | Integration test: Full keyless signing flow | — | TODO | 0010 | End-to-end with mock Fulcio |
|
||||
| 0018 | Integration test: Verify signed bundle | — | TODO | 0017 | Signature verification, cert chain |
|
||||
| 0019 | Documentation: Keyless signing guide | — | TODO | 0017 | `docs/modules/signer/guides/keyless-signing.md` |
|
||||
| 0020 | Update `src/Signer/AGENTS.md` | — | TODO | 0019 | Add keyless components to charter |
|
||||
|
||||
---
|
||||
|
||||
## Technical Specifications
|
||||
|
||||
### Configuration Schema
|
||||
|
||||
```yaml
|
||||
# etc/signer.yaml
|
||||
signer:
|
||||
signing:
|
||||
mode: "keyless" # "keyless" | "kms" | "hybrid"
|
||||
keyless:
|
||||
enabled: true
|
||||
fulcio:
|
||||
url: "https://fulcio.sigstore.dev"
|
||||
# For private deployments:
|
||||
# url: "https://fulcio.internal.example.com"
|
||||
timeout: 30s
|
||||
retries: 3
|
||||
backoffBase: 1s
|
||||
backoffMax: 30s
|
||||
oidc:
|
||||
# Use Authority as OIDC provider
|
||||
issuer: "https://authority.internal"
|
||||
clientId: "signer-keyless"
|
||||
clientSecretRef: "env:SIGNER_OIDC_CLIENT_SECRET"
|
||||
# Alternative: use ambient OIDC (CI runner tokens)
|
||||
useAmbientToken: false
|
||||
ambientTokenPath: "/var/run/secrets/tokens/oidc"
|
||||
algorithms:
|
||||
preferred: "ECDSA_P256"
|
||||
allowed: ["ECDSA_P256", "Ed25519"]
|
||||
certificate:
|
||||
# Fulcio roots for validation
|
||||
rootBundlePath: "/etc/stellaops/fulcio-roots.pem"
|
||||
# Allow additional roots for private Fulcio instances
|
||||
additionalRoots: []
|
||||
validateChain: true
|
||||
requireSCT: true # Require Signed Certificate Timestamp
|
||||
identity:
|
||||
# Expected OIDC issuer for verification
|
||||
expectedIssuers:
|
||||
- "https://authority.internal"
|
||||
- "https://token.actions.githubusercontent.com"
|
||||
- "https://gitlab.com"
|
||||
# Expected SAN patterns (regex)
|
||||
expectedSubjectPatterns:
|
||||
- "^https://github\\.com/stella-ops/.*$"
|
||||
- "^urn:stellaops:signer$"
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
```csharp
|
||||
public abstract class KeylessSigningException : SignerException
|
||||
{
|
||||
protected KeylessSigningException(string message, Exception? inner = null)
|
||||
: base(message, inner) { }
|
||||
}
|
||||
|
||||
public class FulcioUnavailableException : KeylessSigningException
|
||||
{
|
||||
public string FulcioUrl { get; }
|
||||
public int HttpStatus { get; }
|
||||
}
|
||||
|
||||
public class OidcTokenAcquisitionException : KeylessSigningException
|
||||
{
|
||||
public string Issuer { get; }
|
||||
public string Reason { get; }
|
||||
}
|
||||
|
||||
public class CertificateChainValidationException : KeylessSigningException
|
||||
{
|
||||
public string[] ChainSubjects { get; }
|
||||
public string ValidationError { get; }
|
||||
}
|
||||
|
||||
public class EphemeralKeyGenerationException : KeylessSigningException
|
||||
{
|
||||
public string Algorithm { get; }
|
||||
}
|
||||
```
|
||||
|
||||
### Metrics
|
||||
|
||||
```csharp
|
||||
// Prometheus metrics
|
||||
signer.keyless.cert_requests_total{result="success|failure|timeout"}
|
||||
signer.keyless.cert_latency_seconds{quantile="0.5|0.9|0.99"}
|
||||
signer.keyless.oidc_token_refresh_total{result="success|failure"}
|
||||
signer.keyless.ephemeral_keys_generated_total{algorithm="ECDSA_P256|Ed25519"}
|
||||
signer.keyless.cert_chain_validation_total{result="valid|expired|untrusted"}
|
||||
```
|
||||
|
||||
### OpenTelemetry Traces
|
||||
|
||||
```
|
||||
signer.keyless.sign
|
||||
├── signer.keyless.generate_ephemeral_key
|
||||
├── signer.keyless.acquire_oidc_token
|
||||
├── signer.keyless.request_certificate
|
||||
│ ├── http.request POST /api/v2/signingCert
|
||||
│ └── signer.keyless.parse_certificate_chain
|
||||
├── signer.keyless.validate_certificate_chain
|
||||
└── signer.keyless.sign_payload
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
### Unit Test Coverage
|
||||
|
||||
| Component | Test File | Coverage Target |
|
||||
|-----------|-----------|-----------------|
|
||||
| EphemeralKeyGenerator | `EphemeralKeyGeneratorTests.cs` | 100% |
|
||||
| HttpFulcioClient | `HttpFulcioClientTests.cs` | 95% |
|
||||
| KeylessDsseSigner | `KeylessDsseSignerTests.cs` | 95% |
|
||||
| CertificateChainValidator | `CertificateChainValidatorTests.cs` | 100% |
|
||||
| SignerKeylessOptions | `SignerKeylessOptionsTests.cs` | 100% |
|
||||
|
||||
### Integration Tests
|
||||
|
||||
```csharp
|
||||
[Fact]
|
||||
public async Task KeylessSigning_WithMockFulcio_ProducesValidDsse()
|
||||
{
|
||||
// Arrange: Mock Fulcio server returning valid cert chain
|
||||
// Act: Sign a verdict payload
|
||||
// Assert: DSSE envelope contains valid signature + cert chain
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task KeylessSigning_CertificateExpired_ThrowsValidationException()
|
||||
{
|
||||
// Arrange: Mock Fulcio returning expired certificate
|
||||
// Act/Assert: CertificateChainValidationException thrown
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task KeylessSigning_FulcioUnavailable_RetriesWithBackoff()
|
||||
{
|
||||
// Arrange: Mock Fulcio returning 503 then 200
|
||||
// Act: Sign payload
|
||||
// Assert: Success after retry, metrics recorded
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task KeylessSigning_OidcTokenInvalid_ThrowsAcquisitionException()
|
||||
{
|
||||
// Arrange: Authority returns 401
|
||||
// Act/Assert: OidcTokenAcquisitionException thrown
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task EphemeralKeyPair_Disposal_ZerosMemory()
|
||||
{
|
||||
// Arrange: Generate keypair
|
||||
// Act: Dispose
|
||||
// Assert: Private key memory is zeroed (via reflection/unsafe)
|
||||
}
|
||||
```
|
||||
|
||||
### Property-Based Tests
|
||||
|
||||
```csharp
|
||||
[Property]
|
||||
public void KeylessSigning_SamePayload_DifferentSignatures(byte[] payload)
|
||||
{
|
||||
// Ephemeral keys mean different signatures each time
|
||||
var sig1 = await signer.SignAsync(payload);
|
||||
var sig2 = await signer.SignAsync(payload);
|
||||
Assert.NotEqual(sig1.Signature, sig2.Signature);
|
||||
Assert.NotEqual(sig1.Certificate, sig2.Certificate);
|
||||
}
|
||||
|
||||
[Property]
|
||||
public void KeylessSigning_SignatureDeterminism_SameKeyPair(
|
||||
byte[] payload, EphemeralKeyPair keyPair)
|
||||
{
|
||||
// Same ephemeral key produces same signature for same payload
|
||||
var sig1 = Sign(payload, keyPair);
|
||||
var sig2 = Sign(payload, keyPair);
|
||||
Assert.Equal(sig1, sig2);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Threat Model
|
||||
|
||||
| Threat | Mitigation |
|
||||
|--------|------------|
|
||||
| Private key theft | Keys exist only in memory, zeroed on disposal |
|
||||
| Fulcio impersonation | TLS certificate validation, root pinning |
|
||||
| OIDC token replay | Short-lived tokens, audience validation |
|
||||
| Certificate forgery | Chain validation to trusted Fulcio roots |
|
||||
| Timing attacks | Constant-time comparison for signatures |
|
||||
|
||||
### Security Checklist
|
||||
|
||||
- [ ] Ephemeral keys never written to disk or logs
|
||||
- [ ] Private key memory zeroed in Dispose() and finalizer
|
||||
- [ ] Fulcio TLS certificate validated
|
||||
- [ ] OIDC token audience matches expected value
|
||||
- [ ] Certificate chain validates to configured roots
|
||||
- [ ] SCT (Signed Certificate Timestamp) verified when required
|
||||
- [ ] No secrets in configuration (use refs: `env:`, `file:`, `vault:`)
|
||||
|
||||
---
|
||||
|
||||
## Decisions & Risks
|
||||
|
||||
| ID | Decision/Risk | Status | Owner | Notes |
|
||||
|----|---------------|--------|-------|-------|
|
||||
| D001 | Use ECDSA P-256 as default algorithm | DECIDED | — | Widest compatibility, Fulcio default |
|
||||
| D002 | Support Ed25519 as alternative | DECIDED | — | Better performance, growing adoption |
|
||||
| R001 | Fulcio availability dependency | OPEN | — | Mitigate with retries, circuit breaker, fallback to KMS |
|
||||
| R002 | OIDC token acquisition latency | OPEN | — | Cache tokens, refresh proactively |
|
||||
| R003 | Air-gap incompatibility | ACCEPTED | — | Keyless requires network; use KMS mode for air-gap |
|
||||
|
||||
---
|
||||
|
||||
## Upcoming Checkpoints
|
||||
|
||||
| Date | Milestone | Exit Criteria |
|
||||
|------|-----------|---------------|
|
||||
| +3 days | Core interfaces complete | 0001-0004 DONE |
|
||||
| +7 days | Fulcio client working | 0005-0006 DONE, manual test passing |
|
||||
| +10 days | Keyless signer integrated | 0007-0012 DONE |
|
||||
| +14 days | Full test coverage | 0013-0018 DONE |
|
||||
| +15 days | Documentation complete | 0019-0020 DONE, sprint DONE |
|
||||
|
||||
---
|
||||
|
||||
## Execution Log
|
||||
|
||||
| Date | Role | Action | Notes |
|
||||
|------|------|--------|-------|
|
||||
| 2025-12-26 | PM | Sprint created | Initial planning from keyless signing advisory |
|
||||
| 2025-12-26 | Impl | Tasks 0001-0006, 0009-0010 DONE | Created StellaOps.Signer.Keyless library with IEphemeralKeyGenerator, EphemeralKeyPair, IFulcioClient, HttpFulcioClient, SignerKeylessOptions, and DI extensions. Library compiles successfully. |
|
||||
| 2025-12-26 | Impl | Tasks 0007, 0012 DONE | Implemented KeylessDsseSigner (IDsseSigner) with full DSSE envelope creation, PAE encoding, and in-toto statement generation. Created IOidcTokenProvider interface and AmbientOidcTokenProvider for CI runner ambient tokens. All new code compiles successfully. |
|
||||
| 2025-12-26 | Impl | Tasks 0008, 0011 DONE | Added CertificateChainValidator with Fulcio root validation, identity verification, and expected issuer/subject pattern matching. Added StellaOpsVerdict and StellaOpsVerdictAlt predicate types to PredicateTypes.cs with IsVerdictType() helper. |
|
||||
| 2025-12-26 | Impl | Tasks 0013, 0015 DONE | Created comprehensive unit tests for EphemeralKeyGenerator (14 tests) and KeylessDsseSigner (14 tests) in src/Signer/StellaOps.Signer/StellaOps.Signer.Tests/Keyless/. Fixed pre-existing build errors: added X509Certificates using to SigstoreSigningService.cs, fixed IList-to-IReadOnlyList conversion in KeyRotationService.cs, added KeyManagement project reference to WebService. Note: Pre-existing test files (TemporalKeyVerificationTests.cs, KeyRotationWorkflowIntegrationTests.cs) have stale entity references blocking full test build. |
|
||||
| 2025-12-26 | Impl | Pre-existing test fixes | Fixed stale entity references in TemporalKeyVerificationTests.cs and KeyRotationWorkflowIntegrationTests.cs (Id→AnchorId, KeyHistories→KeyHistory, TrustAnchorId→AnchorId, added PublicKey property). Signer.Tests now builds successfully with 0 errors. |
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- **Parent Advisory:** `docs/product-advisories/25-Dec-2025 - Planning Keyless Signing for Verdicts.md`
|
||||
- **Related Advisory:** `docs/product-advisories/25-Dec-2025 - Building a Deterministic Verdict Engine.md`
|
||||
- **Signer Architecture:** `docs/modules/signer/architecture.md`
|
||||
- **Attestor Architecture:** `docs/modules/attestor/architecture.md`
|
||||
- **Successor Sprint:** `SPRINT_20251226_002_ATTESTOR_bundle_rotation.md`
|
||||
|
||||
---
|
||||
|
||||
## Appendix A: Fulcio API Contract
|
||||
|
||||
### Request: POST /api/v2/signingCert
|
||||
|
||||
```json
|
||||
{
|
||||
"credentials": {
|
||||
"oidcIdentityToken": "eyJhbGciOiJSUzI1NiIs..."
|
||||
},
|
||||
"publicKeyRequest": {
|
||||
"publicKey": {
|
||||
"algorithm": "ECDSA",
|
||||
"content": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..."
|
||||
},
|
||||
"proofOfPossession": "MEUCIQD..." // Optional
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response: 200 OK
|
||||
|
||||
```json
|
||||
{
|
||||
"signedCertificateEmbeddedSct": {
|
||||
"chain": {
|
||||
"certificates": [
|
||||
"-----BEGIN CERTIFICATE-----\nMIIC...",
|
||||
"-----BEGIN CERTIFICATE-----\nMIIB..."
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Appendix B: DSSE Bundle with Keyless Certificate
|
||||
|
||||
```json
|
||||
{
|
||||
"payloadType": "application/vnd.in-toto+json",
|
||||
"payload": "eyJfdHlwZSI6Imh0dHBzOi8vaW4tdG90by5pby9TdGF0ZW1lbnQvdjEi...",
|
||||
"signatures": [
|
||||
{
|
||||
"keyid": "",
|
||||
"sig": "MEUCIQDx5z...",
|
||||
"cert": "-----BEGIN CERTIFICATE-----\nMIIC..."
|
||||
}
|
||||
],
|
||||
"certificateChain": [
|
||||
"-----BEGIN CERTIFICATE-----\nMIIC...",
|
||||
"-----BEGIN CERTIFICATE-----\nMIIB..."
|
||||
],
|
||||
"signedCertificateTimestamp": "AO3W9T...",
|
||||
"signingMode": "keyless",
|
||||
"signingIdentity": {
|
||||
"issuer": "https://authority.internal",
|
||||
"subject": "signer@stella-ops.org",
|
||||
"san": "urn:stellaops:signer"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*End of Sprint Document*
|
||||
Reference in New Issue
Block a user