Table of Contents

Class KeyCache

Namespace
Excalibur.Compliance.Encryption
Assembly
Excalibur.Compliance.dll

Provides in-memory caching for encryption key metadata with configurable TTL.

public sealed class KeyCache : IKeyCache, IKeyCacheAdmin, IDisposable
Inheritance
KeyCache
Implements
Inherited Members
Extension Methods

Remarks

This implementation uses MemoryCache for thread-safe caching with automatic expiration. It supports both sliding and absolute expiration based on configuration.

The cache stores only key metadata, never actual key material. Telemetry is reported for cache hits and misses to enable monitoring.

Constructors

KeyCache()

Initializes a new instance of the KeyCache class with default options.

public KeyCache()

KeyCache(KeyCacheOptions, IEncryptionTelemetry?)

Initializes a new instance of the KeyCache class.

public KeyCache(KeyCacheOptions options, IEncryptionTelemetry? telemetry = null)

Parameters

options KeyCacheOptions

The cache options.

telemetry IEncryptionTelemetry

Optional telemetry for reporting cache hits/misses.

KeyCache(IOptions<KeyCacheOptions>, IEncryptionTelemetry?)

Initializes a new instance of the KeyCache class.

public KeyCache(IOptions<KeyCacheOptions> options, IEncryptionTelemetry? telemetry = null)

Parameters

options IOptions<KeyCacheOptions>

The cache options from dependency injection.

telemetry IEncryptionTelemetry

Optional telemetry for reporting cache hits/misses.

Properties

Count

Gets the current number of cached entries.

public int Count { get; }

Property Value

int

Remarks

This diagnostic count reflects the backing cache. Expired entries may remain counted until they are accessed or expiration scanning removes them. Returns zero after disposal.

Methods

Clear()

Clears all cached key metadata.

public void Clear()

Remarks

Clears the current backing cache state. A factory already in flight can publish into the cache afterward; this operation does not fence factories or revoke key access.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

GetOrAddAsync(string, Func<string, CancellationToken, Task<KeyMetadata?>>, CancellationToken)

Retrieves key metadata from the cache, or fetches and caches it if not present.

public Task<KeyMetadata?> GetOrAddAsync(string keyId, Func<string, CancellationToken, Task<KeyMetadata?>> factory, CancellationToken cancellationToken)

Parameters

keyId string

The key identifier.

factory Func<string, CancellationToken, Task<KeyMetadata>>

A factory function to retrieve the key if not in cache.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<KeyMetadata>

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

GetOrAddAsync(string, TimeSpan, Func<string, CancellationToken, Task<KeyMetadata?>>, CancellationToken)

Gets or adds key metadata with a custom TTL.

public Task<KeyMetadata?> GetOrAddAsync(string keyId, TimeSpan ttl, Func<string, CancellationToken, Task<KeyMetadata?>> factory, CancellationToken cancellationToken)

Parameters

keyId string
ttl TimeSpan
factory Func<string, CancellationToken, Task<KeyMetadata>>
cancellationToken CancellationToken

Returns

Task<KeyMetadata>

Invalidate(string)

Invalidates all cached entries for a specific key.

public void Invalidate(string keyId)

Parameters

keyId string

Remarks

Removes the base key and entries whose identifiers start with the ordinal prefix keyId + ":v". Concurrent writes and factories can publish entries after invalidation.

Remove(string)

Removes key metadata from the cache.

public void Remove(string keyId)

Parameters

keyId string

The key identifier to remove.

Set(KeyMetadata)

Adds or updates key metadata in the cache.

public void Set(KeyMetadata keyMetadata)

Parameters

keyMetadata KeyMetadata

The key metadata to cache.

Set(KeyMetadata, TimeSpan)

Adds or updates key metadata with a custom TTL.

public void Set(KeyMetadata keyMetadata, TimeSpan ttl)

Parameters

keyMetadata KeyMetadata
ttl TimeSpan

TryGet(string)

Attempts to retrieve key metadata from the cache.

public KeyMetadata? TryGet(string keyId)

Parameters

keyId string

The key identifier.

Returns

KeyMetadata

The cached key metadata, or null if not in cache.