Table of Contents

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

encryptedData EncryptedData

The encrypted data including ciphertext and key metadata.

context EncryptionContext

The encryption context for tenant isolation and associated data verification. Must match the context used during encryption for AAD-bound ciphertexts.

cancellationToken CancellationToken

A 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 encryptedData is 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

plaintext byte[]

The data to encrypt.

context EncryptionContext

The encryption context providing key selection, tenant isolation, and associated data. Use Default for default settings.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<EncryptedData>

The encrypted data including ciphertext and metadata required for decryption.

Exceptions

ArgumentNullException

Thrown when plaintext is 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

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<bool>

True if FIPS 140-2 compliance is validated; otherwise, false.