Table of Contents

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

logger ILogger<InMemoryKeyManagementProvider>

The logger for diagnostics.

options InMemoryKeyManagementOptions

Optional 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

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.

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

keyId string

The key identifier.

retentionDays int

Number of days to retain the key before destruction.

  • 0 Immediate 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).
  • > 0 Pending 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.
cancellationToken CancellationToken

Token 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

keyId string

The 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

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.

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

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

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

keyId string

The key identifier, in the same form accepted by GetKeyAsync(string, CancellationToken).

cancellationToken CancellationToken

A 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

status KeyStatus?

Optional filter by key status. Null returns all statuses.

purpose string

Optional filter by key purpose. Null returns all purposes.

cancellationToken CancellationToken

A 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

keyId string

The unique identifier of the key to reactivate.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<bool>

True if the key was reactivated; false if the key was not found.

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

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.

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

keyId string

The unique identifier of the key to suspend.

reason string

The reason for suspension (for audit purposes).

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<bool>

True if the key was suspended; false if the key was not found.