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
encryptedDataEncryptedDataThe encrypted data envelope containing algorithm and key metadata.
Returns
- IEncryptionProvider
The provider capable of decrypting this data, or
nullif 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
encryptedDatais 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
providerIdstringThe provider identifier.
Returns
- IEncryptionProvider
The provider instance, or
nullif not found.
Remarks
Provider lookup is case-insensitive.
Exceptions
- ArgumentNullException
Thrown when
providerIdis null.
Register(string, IEncryptionProvider)
Registers an encryption provider with a unique identifier.
void Register(string providerId, IEncryptionProvider provider)
Parameters
providerIdstringUnique provider identifier (e.g., "azure-kv-prod", "aws-kms-legacy").
providerIEncryptionProviderThe encryption provider instance.
Exceptions
- ArgumentNullException
Thrown when
providerIdorprovideris 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
providerIdstringThe 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
providerIdis null.- InvalidOperationException
Thrown if the provider ID is not registered.