Table of Contents

Interface IKeyManagementProvider

Namespace
Excalibur.Compliance
Assembly
Excalibur.Compliance.Abstractions.dll

Provides core key management operations including retrieval, rotation, and active key lookup.

public interface IKeyManagementProvider : IServiceProvider
Inherited Members

Remarks

Key management is separated from encryption to support: - Cloud KMS integration (AWS KMS, Azure Key Vault, Google Cloud KMS) - HSM-backed key storage - Automated key rotation policies

Implementations must ensure key material is never exposed in logs or errors.

Administrative operations (listing, deletion, suspension) are defined in IKeyManagementAdmin. Implementations typically implement both interfaces.

Optional capabilities — including durability, discovered via IDurableKeyProvider — are resolved through GetService(Type), never by casting the provider. A provider answers for the capabilities it supplies; decorators MUST forward GetService to the wrapped provider.

Methods

CreateKeyIfAbsentAsync(string, EncryptionAlgorithm, string?, CancellationToken)

Ensures a key exists at keyId, creating one only if none is there, and returns its current metadata.

Task<KeyMetadata> CreateKeyIfAbsentAsync(string keyId, EncryptionAlgorithm algorithm, string? purpose, CancellationToken cancellationToken)

Parameters

keyId string

The unique identifier for the key.

algorithm EncryptionAlgorithm

The encryption algorithm to use if a key has to be created.

purpose string

Optional purpose or scope for a key that has to be created.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<KeyMetadata>

The metadata of the key now at keyId. Never null.

Remarks

This is not a rotation and must never behave like one. If a key already exists at keyId, this call adds no version, changes no version's status, and alters no attribute of the key: it returns what GetKeyAsync(string, CancellationToken) returns for it. A caller that wanted a key to exist has no reason to retire the one that already does, and RotateKeyAsync(string, EncryptionAlgorithm, string?, DateTimeOffset?, CancellationToken) is create-OR-rotate, so using it to mean "create" demotes a live key whenever two callers race.

A lost creation race is a no-op that yields the winner's key, never an error. Two callers that both find the key absent must both come away with the same key.

What atomicity a backend can offer is the backend's to state, and it varies. A store with a conditional insert creates at most one key. A store whose only create operation also adds a version -- Azure Key Vault's key-create endpoint is the same request either way, with no conditional form -- may, under a genuinely concurrent lost race, leave more than one version behind. That is permitted. What is NOT permitted, on any backend, is demoting or retiring a version that was already there, because that is the harm this operation exists to avoid.

The returned metadata may differ from the arguments. An existing key keeps the algorithm and purpose it was created with; a caller that requires a particular algorithm must check the result rather than assume the arguments were applied.

Failure is thrown, never returned, and the result is never null. A caller cannot proceed without the value, so it cannot mistake a failed provisioning for a usable key handle -- which a result object reporting success by property makes easy to do and easy to miss.

Exceptions

ArgumentException

Thrown when keyId is null or empty.

GetActiveKeyAsync(string?, CancellationToken)

Gets the currently active key for encryption operations.

Task<KeyMetadata?> GetActiveKeyAsync(string? purpose, CancellationToken cancellationToken)

Parameters

purpose string

Optional purpose to filter keys.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<KeyMetadata>

The active key metadata, or null if no active key exists.

GetKeyAsync(string, CancellationToken)

Retrieves metadata for a specific encryption key.

Task<KeyMetadata?> GetKeyAsync(string keyId, CancellationToken cancellationToken)

Parameters

keyId string

The unique identifier of the key.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<KeyMetadata>

The key metadata, or null if the key does not exist.

Exceptions

ArgumentNullException

Thrown when keyId is null or empty.

GetKeyVersionAsync(string, int, CancellationToken)

Retrieves metadata for a specific version of an encryption key.

Task<KeyMetadata?> GetKeyVersionAsync(string keyId, int version, CancellationToken cancellationToken)

Parameters

keyId string

The unique identifier of the key.

version int

The key version to retrieve.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<KeyMetadata>

The key metadata for the specified version, or null if not found.

RotateKeyAsync(string, EncryptionAlgorithm, string?, DateTimeOffset?, CancellationToken)

Creates a new encryption key or rotates an existing key to a new version.

Task<KeyRotationResult> RotateKeyAsync(string keyId, EncryptionAlgorithm algorithm, string? purpose, DateTimeOffset? expiresAt, CancellationToken cancellationToken)

Parameters

keyId string

The unique identifier for the key. If the key exists, creates a new version.

algorithm EncryptionAlgorithm

The encryption algorithm for this key.

purpose string

Optional purpose or scope for the key.

expiresAt DateTimeOffset?

Optional expiration date for the key.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<KeyRotationResult>

The result of the rotation/creation operation.