Table of Contents

Interface IEncryptionProviderRegistry

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

Registry for managing multiple encryption providers with primary/legacy support.

public interface IEncryptionProviderRegistry

Remarks

Enables zero-downtime provider migration by maintaining:

  • One primary provider for new encryption operations
  • Zero or more legacy providers for decrypting old data

Thread-safe for concurrent access. Implementations must use appropriate synchronization for all mutable operations.

Methods

FindDecryptionProvider(EncryptedData)

Finds the appropriate provider to decrypt the given encrypted data.

IEncryptionProvider? FindDecryptionProvider(EncryptedData encryptedData)

Parameters

encryptedData EncryptedData

The encrypted data envelope containing algorithm and key metadata.

Returns

IEncryptionProvider

The provider capable of decrypting this data, or null if no registered provider supports the algorithm or has access to the required key.

Remarks

Routes based on algorithm and key metadata. Tries primary provider first (fast path for 99% of cases), then iterates through legacy providers.

This method checks if a provider supports the algorithm. Actual key availability is verified during decryption.

Exceptions

ArgumentNullException

Thrown when encryptedData is null.

GetAll()

Gets all registered providers (primary + legacy).

IReadOnlyList<IEncryptionProvider> GetAll()

Returns

IReadOnlyList<IEncryptionProvider>

Read-only list of all registered providers.

GetLegacyProviders()

Gets all legacy providers that can decrypt old data.

IReadOnlyList<IEncryptionProvider> GetLegacyProviders()

Returns

IReadOnlyList<IEncryptionProvider>

Read-only list of legacy providers, ordered by preference (most recently added first). Returns an empty list if no legacy providers are registered.

Remarks

Legacy providers are used during provider migration to decrypt data encrypted with previous providers. New encryption always uses the primary provider.

GetPrimary()

Gets the primary provider used for new encryption operations.

IEncryptionProvider GetPrimary()

Returns

IEncryptionProvider

The primary provider instance.

Remarks

All new encryption operations should use the primary provider. Legacy providers are only used for decryption of existing data.

Exceptions

InvalidOperationException

Thrown if no primary provider is configured. Call SetPrimary(string) or configure via DI first.

GetProvider(string)

Gets a provider by its unique identifier.

IEncryptionProvider? GetProvider(string providerId)

Parameters

providerId string

The provider identifier.

Returns

IEncryptionProvider

The provider instance, or null if not found.

Remarks

Provider lookup is case-insensitive.

Exceptions

ArgumentNullException

Thrown when providerId is null.

Register(string, IEncryptionProvider)

Registers an encryption provider with a unique identifier.

void Register(string providerId, IEncryptionProvider provider)

Parameters

providerId string

Unique provider identifier (e.g., "azure-kv-prod", "aws-kms-legacy").

provider IEncryptionProvider

The encryption provider instance.

Exceptions

ArgumentNullException

Thrown when providerId or provider is null.

InvalidOperationException

Thrown if a provider with the same ID is already registered.

SetPrimary(string)

Sets the primary provider for new encryption operations.

void SetPrimary(string providerId)

Parameters

providerId string

The provider ID to promote to primary.

Remarks

This operation is atomic and thread-safe. The previous primary provider (if any) is automatically demoted but remains available for decryption.

At runtime, use this for dynamic provider switching. For startup configuration, prefer the fluent API (UseKeyManagement<T>).

Exceptions

ArgumentNullException

Thrown when providerId is null.

InvalidOperationException

Thrown if the provider ID is not registered.