Table of Contents

Class FieldEncryptor

Namespace
Excalibur.Data.ElasticSearch.Security
Assembly
Excalibur.Data.ElasticSearch.dll

Production implementation of field-level encryption for Elasticsearch documents with enterprise-grade security features and comprehensive audit capabilities.

public sealed class FieldEncryptor : IElasticsearchFieldEncryptor, IElasticsearchFieldEncryption, IElasticsearchFieldEncryptionPolicy, IElasticsearchFieldEncryptionMaintenance, IElasticsearchFieldEncryptorEvents, IDisposable, IAsyncDisposable
Inheritance
FieldEncryptor
Implements
Inherited Members

Remarks

Field-encryption key material never crosses into this package. Every key resolution, algorithm choice, and cryptographic operation is delegated to IKeyManagementProvider and IEncryptionProviderRegistry -- this class never sees a raw key byte. That is the same envelope-encryption model Excalibur.Compliance.CryptoShredding.FieldEncryptor already uses; a cloud KMS or HSM-backed provider can therefore back Elasticsearch field encryption without ever exporting key material to this process.

Constructors

FieldEncryptor(IKeyManagementProvider, IEncryptionProviderRegistry, IOptions<EncryptionOptions>, ILogger<FieldEncryptor>)

Initializes a new instance of the FieldEncryptor class.

public FieldEncryptor(IKeyManagementProvider keyProvider, IEncryptionProviderRegistry registry, IOptions<EncryptionOptions> options, ILogger<FieldEncryptor> logger)

Parameters

keyProvider IKeyManagementProvider

The key management provider that resolves and rotates encryption keys, without ever exposing key material.

registry IEncryptionProviderRegistry

The encryption provider registry used to encrypt and decrypt field values.

options IOptions<EncryptionOptions>

The encryption configuration options.

logger ILogger<FieldEncryptor>

The logger for security and operational events.

Exceptions

ArgumentNullException

Thrown when required dependencies are null.

Properties

SupportedAlgorithms

Gets the encryption algorithms supported by this encryptor.

public IReadOnlyCollection<string> SupportedAlgorithms { get; }

Property Value

IReadOnlyCollection<string>

A collection of supported encryption algorithm names.

SupportsIntegrityValidation

Gets a value indicating whether this encryptor supports integrity validation.

public bool SupportsIntegrityValidation { get; }

Property Value

bool

True if the encryptor provides data integrity checking, false otherwise.

SupportsKeyRotation

Gets a value indicating whether this encryptor supports key rotation.

public bool SupportsKeyRotation { get; }

Property Value

bool

True if the encryptor supports automatic key rotation, false otherwise.

Methods

DecryptDocumentAsync(object, CancellationToken)

Decrypts encrypted field values within an Elasticsearch document to restore original data.

[RequiresUnreferencedCode("This method uses reflection and may not work correctly with trimming")]
[RequiresDynamicCode("This method uses dynamic code generation and may not work correctly with AOT")]
public Task<object> DecryptDocumentAsync(object encryptedDocument, CancellationToken cancellationToken)

Parameters

encryptedDocument object

The document containing encrypted fields to be decrypted.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<object>

A task that represents the asynchronous operation. The task result contains the document with encrypted fields decrypted to their original values.

Exceptions

SecurityException

Thrown when decryption fails due to security constraints.

ArgumentNullException

Thrown when the document is null.

DecryptFieldAsync(string, EncryptedFieldResult, CancellationToken)

Decrypts a specific encrypted field value to restore the original data.

[RequiresUnreferencedCode("JSON deserialization may require unreferenced types for reflection-based operations")]
[RequiresDynamicCode("JSON deserialization uses reflection to dynamically create and populate types")]
public Task<object> DecryptFieldAsync(string fieldName, EncryptedFieldResult encryptedField, CancellationToken cancellationToken)

Parameters

fieldName string

The name of the field being decrypted.

encryptedField EncryptedFieldResult

The encrypted field data containing the encrypted value and metadata.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<object>

A task that represents the asynchronous operation. The task result contains the decrypted original value.

Exceptions

SecurityException

Thrown when field decryption fails due to security constraints.

ArgumentException

Thrown when field name or encrypted data is invalid.

Dispose()

Releases all resources used by the FieldEncryptor.

public void Dispose()

DisposeAsync()

Asynchronously releases resources, ensuring tracked timer callbacks have completed.

public ValueTask DisposeAsync()

Returns

ValueTask

EncryptDocumentAsync(object, CancellationToken)

Encrypts sensitive field values within an Elasticsearch document based on data classification rules.

[RequiresUnreferencedCode("JSON serialization may require unreferenced types for reflection-based operations")]
[RequiresDynamicCode("JSON serialization uses reflection to dynamically access and serialize types")]
public Task<object> EncryptDocumentAsync(object document, CancellationToken cancellationToken)

Parameters

document object

The document containing fields to be encrypted.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<object>

A task that represents the asynchronous operation. The task result contains the document with sensitive fields encrypted according to security policies.

Exceptions

SecurityException

Thrown when encryption fails due to security constraints.

ArgumentNullException

Thrown when the document is null.

EncryptFieldAsync(string, object, ElasticSearchDataClassification, CancellationToken)

Encrypts a specific field value using the appropriate encryption algorithm and key.

[RequiresUnreferencedCode("JSON serialization may require unreferenced types for reflection-based operations")]
[RequiresDynamicCode("JSON serialization uses reflection to dynamically access and serialize types")]
public Task<EncryptedFieldResult> EncryptFieldAsync(string fieldName, object fieldValue, ElasticSearchDataClassification classification, CancellationToken cancellationToken)

Parameters

fieldName string

The name of the field being encrypted.

fieldValue object

The value to encrypt.

classification ElasticSearchDataClassification

The data classification level for the field.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<EncryptedFieldResult>

A task that represents the asynchronous operation. The task result contains the encrypted field result including the encrypted value and metadata.

Exceptions

SecurityException

Thrown when field encryption fails due to security constraints.

ArgumentException

Thrown when field name or value is invalid.

GetFieldClassification(string, object?)

Gets the data classification level for a specific field based on security rules.

public ElasticSearchDataClassification GetFieldClassification(string fieldName, object? fieldValue)

Parameters

fieldName string

The name of the field to classify.

fieldValue object

The value of the field to classify.

Returns

ElasticSearchDataClassification

The data classification level for the field, or Public if no specific classification applies.

RotateEncryptionKeysAsync(ElasticSearchDataClassification, CancellationToken)

Rotates encryption keys for a specific data classification level, re-encrypting affected data.

public Task<EncryptionKeyRotationResult> RotateEncryptionKeysAsync(ElasticSearchDataClassification classification, CancellationToken cancellationToken)

Parameters

classification ElasticSearchDataClassification

The data classification level to rotate keys for.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<EncryptionKeyRotationResult>

A task that represents the asynchronous operation. The task result contains the key rotation result including success status and affected document count.

Exceptions

SecurityException

Thrown when key rotation fails due to security constraints.

ShouldEncryptField(string, object?)

Determines whether a specific field should be encrypted based on security rules and data classification.

public bool ShouldEncryptField(string fieldName, object? fieldValue)

Parameters

fieldName string

The name of the field to evaluate.

fieldValue object

The value of the field to evaluate.

Returns

bool

True if the field should be encrypted according to security policies, false otherwise.

ValidateIntegrityAsync(string, EncryptedFieldResult, CancellationToken)

Verifies the authentication tag of an encrypted field against its ciphertext, detecting tampering without exposing the plaintext.

public Task<bool> ValidateIntegrityAsync(string fieldName, EncryptedFieldResult encryptedField, CancellationToken cancellationToken)

Parameters

fieldName string

The name of the field the encrypted value belongs to, as used when it was encrypted.

encryptedField EncryptedFieldResult

The encrypted field data to validate.

cancellationToken CancellationToken

The cancellation token to monitor for cancellation requests.

Returns

Task<bool>

A task that represents the asynchronous operation. The task result contains true only when the authentication tag verifies against the ciphertext. It contains false when tampering is detected, and also whenever integrity cannot be established at all -- an envelope with no authentication tag, an unrecognized envelope format, an unavailable key version, or an unsupported algorithm. A false result therefore means "not established as intact", never "confirmed tampered".

Remarks

The tag is verified cryptographically: the field's key is resolved by the version stamped on the envelope, the authenticated associated data is reconstructed from fieldName and the envelope's own crypto context, and the AEAD tag is checked against the ciphertext. A substituted, truncated, or recomputed tag does not verify, and neither does a ciphertext moved between fields.

fieldName is required because it is bound into the associated data at encryption time. The envelope alone cannot authenticate itself: it carries the key version, algorithm, and classification, but not the name of the field it belongs to, and all four are needed to reconstruct what the tag actually covers. Pass the same field name that was used to encrypt the value.

The plaintext recovered during verification is discarded and its buffer zeroed; use DecryptFieldAsync when the value itself is needed.

Exceptions

ArgumentException

Thrown when fieldName is null or empty.

ArgumentNullException

Thrown when encryptedField is null.

Events

FieldDecrypted

Occurs when a field is decrypted, for audit and monitoring purposes.

public event EventHandler<FieldDecryptedEventArgs>? FieldDecrypted

Event Type

EventHandler<FieldDecryptedEventArgs>

FieldEncrypted

Occurs when a field is encrypted, for audit and monitoring purposes.

public event EventHandler<FieldEncryptedEventArgs>? FieldEncrypted

Event Type

EventHandler<FieldEncryptedEventArgs>

KeyRotated

Occurs when encryption key rotation is completed.

public event EventHandler<EncryptionKeyRotatedEventArgs>? KeyRotated

Event Type

EventHandler<EncryptionKeyRotatedEventArgs>