Interface IEncryptionProvider
- Namespace
- Excalibur.Compliance
- Assembly
- Excalibur.Compliance.Abstractions.dll
Provides field-level encryption and decryption services.
public interface IEncryptionProvider
Remarks
This is the canonical encryption interface for the Excalibur framework.
Authenticated encryption is REQUIRED, and the requirement is a property rather than an algorithm. DecryptAsync(EncryptedData, EncryptionContext, CancellationToken) MUST throw EncryptionException when the ciphertext, the key metadata or the associated data has been modified since EncryptAsync(byte[], EncryptionContext, CancellationToken) returned it, and MUST NOT return plaintext for modified input. Callers rely on this: a successful DecryptAsync(EncryptedData, EncryptionContext, CancellationToken) is evidence that the data is unmodified, not merely that it was decryptable. Framework components that handle encrypted data reason from that guarantee, so an implementation which decrypts modified input silently weakens every component built on it.
Stating the property rather than naming a cipher is deliberate: AES-256-GCM, ChaCha20-Poly1305, AES-GCM-SIV and the authenticated modes offered by cloud KMS providers all satisfy it, while an unauthenticated mode such as AES-CBC without a MAC does not, whatever its key length. Implementations are free to choose any construction that keeps the requirement.
Implementations SHOULD be verified against EncryptionProviderConformanceTestKit, which exercises the
requirement directly: it modifies a ciphertext byte and asserts the failure, modifies the associated data and asserts
the failure, and pairs both with an untampered round-trip that must still succeed.
Key features: - Async-only API for cloud KMS integration - Byte array interface (callers handle serialization) - Context-based key selection and tenant isolation - Support for key rotation and FIPS 140-2 compliance
Methods
DecryptAsync(EncryptedData, EncryptionContext, CancellationToken)
Decrypts ciphertext data using the embedded key metadata.
Task<byte[]> DecryptAsync(EncryptedData encryptedData, EncryptionContext context, CancellationToken cancellationToken)
Parameters
encryptedDataEncryptedDataThe encrypted data including ciphertext and key metadata.
contextEncryptionContextThe encryption context for tenant isolation and associated data verification. Must match the context used during encryption for AAD-bound ciphertexts.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<byte[]>
The decrypted plaintext data. A successful return is evidence that the ciphertext, key metadata and associated data are unmodified since encryption; see the authenticated-encryption requirement on IEncryptionProvider.
Exceptions
- ArgumentNullException
Thrown when
encryptedDatais null.- EncryptionException
Thrown when decryption fails. Implementations MUST throw this when the ciphertext, the key metadata or the associated data has been modified, and MUST NOT return plaintext for modified input. Also thrown when the key cannot be found or the context does not match the one used during encryption.
EncryptAsync(byte[], EncryptionContext, CancellationToken)
Encrypts plaintext data using the specified context.
Task<EncryptedData> EncryptAsync(byte[] plaintext, EncryptionContext context, CancellationToken cancellationToken)
Parameters
plaintextbyte[]The data to encrypt.
contextEncryptionContextThe encryption context providing key selection, tenant isolation, and associated data. Use Default for default settings.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<EncryptedData>
The encrypted data including ciphertext and metadata required for decryption.
Exceptions
- ArgumentNullException
Thrown when
plaintextis null.- EncryptionException
Thrown when encryption fails.
ValidateFipsComplianceAsync(CancellationToken)
Validates that the provider is configured for FIPS 140-2 compliant operations.
Task<bool> ValidateFipsComplianceAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenA token to cancel the operation.