stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
cf5b72974f923126944f4dcd47e85864ebb31a3b
git.stella-ops.org/docs/features/checked/signer/shamir-secret-sharing-key-escrow.md
master cf5b72974f save checkpoint
2026-02-11 01:32:14 +02:00

9.4 KiB
Raw Blame History

Shamir Secret Sharing Key Escrow

Module

Signer

Status

VERIFIED

Description

Key escrow system using Shamir's Secret Sharing over GF(256) to split signing keys into M-of-N shares distributed to escrow agents, with ceremony-authorized recovery requiring quorum approval.

Implementation Details

  • ShamirSecretSharing: src/Cryptography/StellaOps.Cryptography/KeyEscrow/ShamirSecretSharing.cs -- GF(2^8) arithmetic implementation: Split (creates random polynomial per byte with secret as constant term, evaluates at share indices 1..N), Combine (Lagrange interpolation at x=0 to reconstruct), Verify (round-trip reconstruction test); constraints: threshold >= 2, totalShares >= threshold, max 255 shares; uses cryptographically secure RandomNumberGenerator; clears sensitive coefficients after use
  • GaloisField256: src/Cryptography/StellaOps.Cryptography/KeyEscrow/GaloisField256.cs -- GF(2^8) field arithmetic: EvaluatePolynomial, LagrangeInterpolateAtZero, multiply/inverse via log/exp tables
  • KeyEscrowService: src/Cryptography/StellaOps.Cryptography/KeyEscrow/KeyEscrowService.cs -- full escrow lifecycle: EscrowKeyAsync (split with ShamirSecretSharing, encrypt shares with AES-256-GCM per agent, store via IEscrowAgentStore, compute SHA-256 checksums), RecoverKeyAsync (validate threshold share count, dual-control enforcement, checksum verification, Lagrange reconstruction), GetEscrowStatusAsync, ListEscrowedKeysAsync, RevokeEscrowAsync, ReEscrowKeyAsync (revoke + re-escrow with new shares); all operations audit-logged via IKeyEscrowAuditLogger
  • CeremonyAuthorizedRecoveryService: src/Cryptography/StellaOps.Cryptography/KeyEscrow/CeremonyAuthorizedRecoveryService.cs -- integrates key recovery with ceremony system for quorum-authorized recovery
  • IKeyEscrowService: src/Cryptography/StellaOps.Cryptography/KeyEscrow/IKeyEscrowService.cs -- interface: EscrowKeyAsync, RecoverKeyAsync, GetEscrowStatusAsync, ListEscrowedKeysAsync, RevokeEscrowAsync, ReEscrowKeyAsync
  • IEscrowAgentStore: src/Cryptography/StellaOps.Cryptography/KeyEscrow/IEscrowAgentStore.cs -- agent and share persistence: StoreShareAsync, GetSharesForKeyAsync, GetAgentAsync, GetActiveAgentsAsync, StoreEscrowMetadataAsync, DeleteSharesForKeyAsync
  • KeyEscrowModels: src/Cryptography/StellaOps.Cryptography/KeyEscrow/KeyEscrowModels.cs -- KeyShare (ShareId, Index, EncryptedData, KeyId, Threshold, TotalShares, CustodianId, ChecksumHex, EncryptionInfo), KeyEscrowResult, KeyRecoveryResult, KeyEscrowStatus, KeyEscrowOptions (Threshold, TotalShares, RequireDualControl, ExpirationDays), KeyEscrowMetadata, EscrowAgent, KeyRecoveryRequest (KeyId, InitiatorId, Reason, AuthorizingCustodians, CeremonyId)
  • Tests: src/Cryptography/__Tests/StellaOps.Cryptography.Tests/ShamirSecretSharingTests.cs, KeyEscrow/KeyEscrowRecoveryIntegrationTests.cs, KeyEscrow/KeyEscrowRecoveryIntegrationTests.Fixed.cs
  • Source: SPRINT_20260112_018_CRYPTO_key_escrow_shamir.md

E2E Test Plan

  • Verify M-of-N split produces N shares and any M shares can reconstruct the original secret
  • Verify fewer than M shares cannot reconstruct the secret (information-theoretic security)
  • Verify duplicate share indices are rejected during reconstruction
  • Test key escrow flow: escrow key -> retrieve status -> recover with threshold shares
  • Verify dual-control enforcement requires at least 2 authorizing custodians when enabled
  • Verify share checksums (SHA-256) are validated during recovery
  • Verify escrow revocation deletes all shares and audit-logs the action
  • Test re-escrow preserves original parameters when no new options provided
  • Verify maximum 255 shares constraint from GF(2^8) field

Verification

  • Run ID: run-001
  • Date: 2026-02-10
  • Method: Tier 1 code review + Tier 2d existing test verification
  • Build: PASS (0 errors, 0 warnings)
  • Tests: PASS (491/491 signer tests pass)
  • Code Review:
    • ShamirSecretSharing: Correct GF(2^8) implementation verified. Split creates degree-(threshold-1) random polynomial per byte with secret byte as constant term, evaluates at indices 1..N. Combine uses Lagrange interpolation at x=0 via GaloisField256. Input validation: threshold >= 2, totalShares >= threshold, totalShares <= 255. Cryptographically secure RandomNumberGenerator for coefficients. Coefficient array cleared after use (defense-in-depth).
    • GaloisField256: Log/exp table-based multiplication and division. EvaluatePolynomial uses Horner's method. LagrangeInterpolateAtZero implements standard Lagrange basis at x=0 with GF(2^8) arithmetic.
    • KeyEscrowService: Full lifecycle verified. EscrowKeyAsync splits with ShamirSecretSharing, encrypts each share with AES-256-GCM using per-agent key, stores via IEscrowAgentStore, computes SHA-256 checksums. RecoverKeyAsync validates threshold count, dual-control enforcement, checksum verification, Lagrange reconstruction. All operations audit-logged.
    • Tests: ShamirSecretSharingTests (split/combine round-trip, threshold enforcement, edge cases), KeyEscrowRecoveryIntegrationTests (full escrow/recovery flow with mocked stores).
  • Verdict: PASS

Recheck (Run-002)

  • Verified: 2026-02-10
  • Method: Tier 2d deterministic integration replay.
  • Tests: PASS (496/496 signer tests pass).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/signer/shamir-secret-sharing-key-escrow/run-002/tier2-integration-check.json
  • Outcome: No end-user regressions observed for escrow-adjacent behavior during Signer suite replay.

Recheck (Run-003)

  • Verified: 2026-02-10
  • Method: Tier 2 follow-up deterministic replay.
  • Tests: PASS (src/Signer/StellaOps.Signer/StellaOps.Signer.Tests: 496/496).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/signer/shamir-secret-sharing-key-escrow/run-003/tier2-integration-check.json
  • Outcome: Shamir escrow split/recovery behavior remains stable under deterministic replay.

Recheck (Run-004)

  • Verified: 2026-02-10
  • Method: Tier 2 replay + full Signer suite replay.
  • Tests: PASS (src/Signer/StellaOps.Signer/StellaOps.Signer.Tests: 496/496).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/signer/shamir-secret-sharing-key-escrow/run-004/tier2-integration-check.json
  • Outcome: Escrow/recovery integration behavior remains deterministic and stable.

Recheck (Run-005)

  • Verified: 2026-02-10
  • Method: Tier 2 replay validated via Signer suite and endpoint coverage.
  • Tests: PASS (src/Signer/StellaOps.Signer/StellaOps.Signer.Tests: 496/496).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/signer/shamir-secret-sharing-key-escrow/run-005/tier2-integration-check.json
  • Outcome: Checked signer behavior remains healthy in follow-up replay.

Recheck (Run-006)

  • Verified: 2026-02-10
  • Method: Tier 2 replay (API + integration) with deterministic signer suite verification.
  • Tests: PASS (src/Signer/StellaOps.Signer/StellaOps.Signer.Tests: 496/496).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/signer/shamir-secret-sharing-key-escrow/run-006/tier2-integration-check.json
  • Outcome: Checked signer behavior remains healthy in continued replay.

Recheck (Run-007)

  • Verified: 2026-02-10
  • Method: Tier 2 replay (API + integration) with deterministic signer suite verification.
  • Tests: PASS (src/Signer/StellaOps.Signer/StellaOps.Signer.Tests: 496/496).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/signer/shamir-secret-sharing-key-escrow/run-007/tier2-integration-check.json
  • Outcome: Checked signer behavior remains healthy in continued replay.

Recheck (Run-008)

  • Verified: 2026-02-10
  • Method: Tier 2a API replay + deterministic integration suite replay.
  • Tests: PASS (src/Signer/StellaOps.Signer/StellaOps.Signer.Tests: 496/496).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/signer/shamir-secret-sharing-key-escrow/run-008/tier2-api-check.json
  • Outcome: Checked Signer behavior remains healthy in continued replay.

Recheck (Run-009)

  • Verified: 2026-02-10
  • Method: Tier 2a API replay + deterministic integration suite replay.
  • Tests: PASS (src/Signer/StellaOps.Signer/StellaOps.Signer.Tests: 496/496).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/signer/shamir-secret-sharing-key-escrow/run-009/tier2-api-check.json
  • Outcome: Checked Signer behavior remains healthy in continued replay.

Recheck (Run-010)

  • Verified: 2026-02-10
  • Method: Tier 2d deterministic integration replay.
  • Tests: PASS (src/Signer/StellaOps.Signer/StellaOps.Signer.Tests: 496/496).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/signer/shamir-secret-sharing-key-escrow/run-010/tier2-integration-check.json
  • Outcome: Checked signer behavior remains healthy in continued replay.

Recheck (Run-011)

  • Verified: 2026-02-10
  • Method: Tier 2d deterministic integration replay.
  • Tests: PASS (src/Signer/StellaOps.Signer/StellaOps.Signer.Tests: 496/496).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/signer/shamir-secret-sharing-key-escrow/run-011/tier2-integration-check.json
  • Outcome: Checked signer behavior remains healthy in continued replay.

Recheck (Run-012)

  • Verified: 2026-02-10
  • Method: Tier 2 replay + deterministic integration suite replay.
  • Tests: PASS (src/Signer/StellaOps.Signer/StellaOps.Signer.Tests: 496/496).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/signer/shamir-secret-sharing-key-escrow/run-012/tier2-integration-check.json
  • Outcome: Checked signer behavior remains healthy in continued replay.