Class InMemoryKeyManagementProvider
- Namespace
- Excalibur.Compliance.Encryption
- Assembly
- Excalibur.Compliance.dll
In-memory implementation of key management for development and testing.
public sealed class InMemoryKeyManagementProvider : IKeyManagementProvider, IServiceProvider, IKeyManagementAdmin, IKeyDestructionStatusProvider, IDisposable
- Inheritance
-
InMemoryKeyManagementProvider
- Implements
- Inherited Members
Remarks
WARNING: This implementation stores key material in memory and is NOT suitable for production use. For production environments, use cloud KMS providers (AWS KMS, Azure Key Vault, Google Cloud KMS) or HSM-backed implementations.
Features supported:
- Key generation with AES-256
- Key rotation (creates new version, marks old as decrypt-only)
- Key deletion with retention period
- Key suspension
- GDPR cryptographic erasure via key destruction
Constructors
InMemoryKeyManagementProvider(ILogger<InMemoryKeyManagementProvider>, InMemoryKeyManagementOptions?)
Initializes a new instance of the InMemoryKeyManagementProvider class.
public InMemoryKeyManagementProvider(ILogger<InMemoryKeyManagementProvider> logger, InMemoryKeyManagementOptions? options = null)
Parameters
loggerILogger<InMemoryKeyManagementProvider>The logger for diagnostics.
optionsInMemoryKeyManagementOptionsOptional configuration options.
Methods
CreateKeyIfAbsentAsync(string, EncryptionAlgorithm, string?, CancellationToken)
Ensures a key exists at keyId, creating one only if none is there, and returns its
current metadata.
public 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.
DeleteKeyAsync(string, int, CancellationToken)
Schedules a key for deletion or immediately destroys it depending on the retention period.
public Task<KeyDestructionOutcome> DeleteKeyAsync(string keyId, int retentionDays, CancellationToken cancellationToken)
Parameters
keyIdstringThe key identifier.
retentionDaysintNumber of days to retain the key before destruction.
0Immediate destruction: All key material is securely zeroed (ZeroMemory(Span<byte>)) and the key is removed from the store. Data encrypted with this key becomes permanently unrecoverable. Use this for GDPR cryptographic erasure (crypto-shredding).> 0Pending destruction: All versions are moved to PendingDestruction with a scheduled deletion date. The key material remains in memory during the retention window, allowing decrypt-only operations for data migration. After the retention period, a cleanup process should call DestroyKeyImmediately(string) to complete erasure.
cancellationTokenCancellationTokenToken to monitor for cancellation requests.
Returns
- Task<KeyDestructionOutcome>
true if the key was found and processed; false if the key does not exist.
DestroyKeyImmediately(string)
Immediately destroys a key and all its versions (crypto-shredding for GDPR erasure).
public bool DestroyKeyImmediately(string keyId)
Parameters
keyIdstringThe key identifier.
Returns
- bool
True if the key was destroyed; false if not found.
Dispose()
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
public void Dispose()
GetActiveKeyAsync(string?, CancellationToken)
Gets the currently active key for encryption operations.
public 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.
public 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.
public 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.
IsKeyDestroyedAsync(string, CancellationToken)
Determines whether the backend still holds any recoverable copy of a key handle's material.
public Task<bool> IsKeyDestroyedAsync(string keyId, CancellationToken cancellationToken)
Parameters
keyIdstringThe key identifier, in the same form accepted by GetKeyAsync(string, CancellationToken).
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<bool>
true only when the backend holds no recoverable copy of the handle's material. false when the key is live, or deleted but still recoverable.
Remarks
The whole of what an implementation asserts by answering true is "I hold no recoverable copy of this handle." That is a statement about what the backend can serve or restore now. It is NOT a statement that the material was destroyed, and it is NOT a statement that this backend destroyed it -- a handle this backend never held answers true for the same reason a purged one does, and nothing here can separate the two.
Absence is never evidence of destruction. An implementation MUST NOT derive true from a lookup that merely failed to produce an answer -- a not-found response, a missing sidecar record, an absent marker, an empty cache entry. Those are states in which the question was not answered, and reporting them as "destroyed" manufactures an attestation out of a failure. The only legitimate basis for true is a backend statement that no recoverable copy remains.
An answer that cannot be obtained is thrown, never reported as either value, so a caller can never mistake "could not ask" for "destroyed" -- nor for "not destroyed", which would certify an erasure as incomplete on an outage.
ListKeysAsync(KeyStatus?, string?, CancellationToken)
Lists all keys matching the specified filter criteria.
public Task<IReadOnlyList<KeyMetadata>> ListKeysAsync(KeyStatus? status, string? purpose, CancellationToken cancellationToken)
Parameters
statusKeyStatus?Optional filter by key status. Null returns all statuses.
purposestringOptional filter by key purpose. Null returns all purposes.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<IReadOnlyList<KeyMetadata>>
A list of key metadata matching the criteria.
ReactivateKeyAsync(string, CancellationToken)
Reactivates a previously suspended key, restoring its use for cryptographic operations.
public Task<bool> ReactivateKeyAsync(string keyId, CancellationToken cancellationToken)
Parameters
keyIdstringThe unique identifier of the key to reactivate.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
Remarks
This is the inverse of SuspendKeyAsync(string, string, CancellationToken). A key that is not suspended is returned to (or left in) the active state.
RotateKeyAsync(string, EncryptionAlgorithm, string?, DateTimeOffset?, CancellationToken)
Creates a new encryption key or rotates an existing key to a new version.
public 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.
SuspendKeyAsync(string, string, CancellationToken)
Suspends a key, preventing its use for any cryptographic operations.
public Task<bool> SuspendKeyAsync(string keyId, string reason, CancellationToken cancellationToken)
Parameters
keyIdstringThe unique identifier of the key to suspend.
reasonstringThe reason for suspension (for audit purposes).
cancellationTokenCancellationTokenA token to cancel the operation.