Interface IKeyEscrowService
- Namespace
- Excalibur.Compliance
- Assembly
- Excalibur.Compliance.Abstractions.dll
Provides key escrow operations for secure key backup and recovery.
public interface IKeyEscrowService
Remarks
This service manages user/tenant key escrow (NOT master keys). Key escrow enables disaster recovery while maintaining security through:
- Encrypted key storage — the escrowed key is encrypted with the master key
- A Shamir threshold (M-of-N) authorization quorum that gates recovery
- Time-limited recovery tokens
- Full audit logging for all operations
Recovery guarantee — read carefully. Recovery requires a combined quorum of at least the configured threshold of custodian shares and fails closed below that threshold, or on a tampered or forged share set: no key material is released. This threshold is an authorization control over the recovery workflow. It is not an information-theoretic split of the key itself: the escrowed key is encrypted with the master key, so the master key — not the share quorum — is the cryptographic protection of the stored material. A holder of the master key can therefore decrypt the escrowed key without assembling the quorum. Treat the quorum as fail-closed recovery authorization; do not rely on it as split-knowledge protection of the key.
This service is designed for user-level and tenant-level encryption keys. For master key backup, see IMasterKeyBackupService.
Methods
BackupKeyAsync(string, ReadOnlyMemory<byte>, EscrowOptions?, CancellationToken)
Creates an encrypted backup of a key in escrow storage.
Task<EscrowReceipt> BackupKeyAsync(string keyId, ReadOnlyMemory<byte> keyMaterial, EscrowOptions? options, CancellationToken cancellationToken)
Parameters
keyIdstringThe unique identifier of the key to backup.
keyMaterialReadOnlyMemory<byte>The raw key material to backup (will be encrypted).
optionsEscrowOptionsConfiguration options for the escrow operation.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<EscrowReceipt>
A receipt confirming the escrow operation.
Remarks
Recovery is gated by an M-of-N custodian quorum only once recovery tokens have been generated (see GenerateRecoveryTokensAsync(string, int, int, TimeSpan?, CancellationToken)). A key that has been backed up but has no recovery tokens yet is recoverable with the escrow master key alone — there is no custodian quorum to enforce until custodians are provisioned.
Generating recovery tokens binds the key to the quorum (each token batch wraps the key under a key-encryption key derived from that batch's quorum secret) and removes the master-only copy, after which the master key alone can no longer recover the key. Provision custodians (generate recovery tokens) as part of setup to activate quorum-gated recovery.
Exceptions
- ArgumentNullException
Thrown when
keyIdorkeyMaterialis null.- ArgumentException
Thrown when
keyIdis empty or whitespace.- KeyEscrowException
Thrown when the escrow operation fails.
GenerateRecoveryTokensAsync(string, int, int, TimeSpan?, CancellationToken)
Generates the per-custodian recovery tokens for the M-of-N recovery-authorization quorum (genuine Shamir threshold shares of a fresh quorum secret).
Task<RecoveryToken[]> GenerateRecoveryTokensAsync(string keyId, int custodianCount, int threshold, TimeSpan? expiresIn, CancellationToken cancellationToken)
Parameters
keyIdstringThe unique identifier of the escrowed key.
custodianCountintTotal number of custodians (shares to generate). Default is 5.
thresholdintMinimum shares required for recovery. Default is 3.
expiresInTimeSpan?Time until tokens expire. Default is 24 hours.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<RecoveryToken[]>
Array of recovery tokens to distribute to custodians.
Exceptions
- ArgumentNullException
Thrown when
keyIdis null.- ArgumentOutOfRangeException
Thrown when
thresholdis greater thancustodianCountor when either value is less than 2.- KeyEscrowException
Thrown when token generation fails.
GetEscrowStatusAsync(string, CancellationToken)
Gets the escrow status for a specific key.
Task<EscrowStatus?> GetEscrowStatusAsync(string keyId, CancellationToken cancellationToken)
Parameters
keyIdstringThe unique identifier of the key.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<EscrowStatus>
The escrow status, or null if no escrow exists for the key.
RecoverKeyAsync(string, RecoveryToken, CancellationToken)
Recovers a key from escrow storage using a valid recovery token.
Task<ReadOnlyMemory<byte>> RecoverKeyAsync(string keyId, RecoveryToken token, CancellationToken cancellationToken)
Parameters
keyIdstringThe unique identifier of the key to recover.
tokenRecoveryTokenA combined recovery token assembled from at least the threshold number of custodian shares (see Combine(IEnumerable<RecoveryToken>)). A single-custodian or below-threshold token fails closed and recovers nothing.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<ReadOnlyMemory<byte>>
The recovered key material.
Exceptions
- ArgumentNullException
Thrown when
keyIdortokenis null.- KeyEscrowException
Thrown when recovery fails (invalid token, expired, or key not found).
- UnauthorizedAccessException
Thrown when the token is invalid or expired.
RevokeEscrowAsync(string, string?, CancellationToken)
Revokes all escrow data and recovery tokens for a key.
Task<bool> RevokeEscrowAsync(string keyId, string? reason, CancellationToken cancellationToken)
Parameters
keyIdstringThe unique identifier of the escrowed key.
reasonstringThe reason for revocation (for audit purposes).
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
Exceptions
- ArgumentNullException
Thrown when
keyIdis null.