Table of Contents

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

keyId string

The unique identifier of the key to backup.

keyMaterial ReadOnlyMemory<byte>

The raw key material to backup (will be encrypted).

options EscrowOptions

Configuration options for the escrow operation.

cancellationToken CancellationToken

A 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 keyId or keyMaterial is null.

ArgumentException

Thrown when keyId is 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

keyId string

The unique identifier of the escrowed key.

custodianCount int

Total number of custodians (shares to generate). Default is 5.

threshold int

Minimum shares required for recovery. Default is 3.

expiresIn TimeSpan?

Time until tokens expire. Default is 24 hours.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<RecoveryToken[]>

Array of recovery tokens to distribute to custodians.

Exceptions

ArgumentNullException

Thrown when keyId is null.

ArgumentOutOfRangeException

Thrown when threshold is greater than custodianCount or 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

keyId string

The unique identifier of the key.

cancellationToken CancellationToken

A 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

keyId string

The unique identifier of the key to recover.

token RecoveryToken

A 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.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<ReadOnlyMemory<byte>>

The recovered key material.

Exceptions

ArgumentNullException

Thrown when keyId or token is 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

keyId string

The unique identifier of the escrowed key.

reason string

The reason for revocation (for audit purposes).

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<bool>

True if the escrow was revoked; false if no escrow existed for the key.

Exceptions

ArgumentNullException

Thrown when keyId is null.