Table of Contents

Class RotatingEncryptionProvider

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

Provides encryption with automatic key rotation support and backward compatibility.

public sealed class RotatingEncryptionProvider : IEncryptionProvider, IDisposable
Inheritance
RotatingEncryptionProvider
Implements
Inherited Members

Remarks

This provider wraps an underlying IEncryptionProvider and adds:

  • Automatic key rotation via the key management provider
  • Backward compatibility - decrypts with any previous key version
  • Transparent re-encryption during read operations (optional)

For encryption, always uses the current active key. For decryption, uses the key version embedded in the EncryptedData metadata.

Constructors

RotatingEncryptionProvider(IEncryptionProvider, IKeyManagementProvider, ILogger<RotatingEncryptionProvider>, RotatingEncryptionOptions?)

Initializes a new instance of the RotatingEncryptionProvider class.

public RotatingEncryptionProvider(IEncryptionProvider inner, IKeyManagementProvider keyManagement, ILogger<RotatingEncryptionProvider> logger, RotatingEncryptionOptions? options = null)

Parameters

inner IEncryptionProvider

The underlying encryption provider.

keyManagement IKeyManagementProvider

The key management provider for rotation operations.

logger ILogger<RotatingEncryptionProvider>

The logger for diagnostics.

options RotatingEncryptionOptions

Optional configuration options.

Methods

DecryptAsync(EncryptedData, EncryptionContext, CancellationToken)

Decrypts ciphertext data using the embedded key metadata.

public 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.

Dispose()

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

public void Dispose()

EncryptAsync(byte[], EncryptionContext, CancellationToken)

Encrypts plaintext data using the specified context.

public 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.

ReEncryptAsync(EncryptedData, EncryptionContext, CancellationToken)

Re-encrypts data with the current active key.

public Task<EncryptedData> ReEncryptAsync(EncryptedData encryptedData, EncryptionContext context, CancellationToken cancellationToken)

Parameters

encryptedData EncryptedData

The existing encrypted data.

context EncryptionContext

The encryption context.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<EncryptedData>

The data re-encrypted with the current active key, or the original data if already using the active key.

RotateKeyAsync(string, EncryptionAlgorithm, string?, DateTimeOffset?, CancellationToken)

Rotates the encryption key for the specified purpose.

public Task<KeyRotationResult> RotateKeyAsync(string keyId, EncryptionAlgorithm algorithm, string? purpose, DateTimeOffset? expiresAt, CancellationToken cancellationToken)

Parameters

keyId string

The key identifier to rotate.

algorithm EncryptionAlgorithm

The encryption algorithm for the new key.

purpose string

Optional purpose for the key.

expiresAt DateTimeOffset?

Optional expiration date for the new key.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<KeyRotationResult>

The result of the rotation operation.

ValidateFipsComplianceAsync(CancellationToken)

Validates that the provider is configured for FIPS 140-2 compliant operations.

public 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.