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
keyIdstringThe unique identifier for the key.
algorithmEncryptionAlgorithmThe encryption algorithm to use if a key has to be created.
purposestringOptional purpose or scope for a key that has to be created.
cancellationTokenCancellationTokenA 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
keyIdis null or empty.
GetActiveKeyAsync(string?, CancellationToken)
Gets the currently active key for encryption operations.
Task<KeyMetadata?> GetActiveKeyAsync(string? purpose, CancellationToken cancellationToken)
Parameters
purposestringOptional purpose to filter keys.
cancellationTokenCancellationTokenA 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
keyIdstringThe unique identifier of the key.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<KeyMetadata>
The key metadata, or null if the key does not exist.
Exceptions
- ArgumentNullException
Thrown when
keyIdis 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
keyIdstringThe unique identifier of the key.
versionintThe key version to retrieve.
cancellationTokenCancellationTokenA 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
keyIdstringThe unique identifier for the key. If the key exists, creates a new version.
algorithmEncryptionAlgorithmThe encryption algorithm for this key.
purposestringOptional purpose or scope for the key.
expiresAtDateTimeOffset?Optional expiration date for the key.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<KeyRotationResult>
The result of the rotation/creation operation.