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
keyProviderIKeyManagementProviderThe key management provider that resolves and rotates encryption keys, without ever exposing key material.
registryIEncryptionProviderRegistryThe encryption provider registry used to encrypt and decrypt field values.
optionsIOptions<EncryptionOptions>The encryption configuration options.
loggerILogger<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
encryptedDocumentobjectThe document containing encrypted fields to be decrypted.
cancellationTokenCancellationTokenThe 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
fieldNamestringThe name of the field being decrypted.
encryptedFieldEncryptedFieldResultThe encrypted field data containing the encrypted value and metadata.
cancellationTokenCancellationTokenThe 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
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
documentobjectThe document containing fields to be encrypted.
cancellationTokenCancellationTokenThe 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
fieldNamestringThe name of the field being encrypted.
fieldValueobjectThe value to encrypt.
classificationElasticSearchDataClassificationThe data classification level for the field.
cancellationTokenCancellationTokenThe 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
fieldNamestringThe name of the field to classify.
fieldValueobjectThe 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
classificationElasticSearchDataClassificationThe data classification level to rotate keys for.
cancellationTokenCancellationTokenThe 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
fieldNamestringThe name of the field to evaluate.
fieldValueobjectThe 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
fieldNamestringThe name of the field the encrypted value belongs to, as used when it was encrypted.
encryptedFieldEncryptedFieldResultThe encrypted field data to validate.
cancellationTokenCancellationTokenThe 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
fieldNameis null or empty.- ArgumentNullException
Thrown when
encryptedFieldis null.
Events
FieldDecrypted
Occurs when a field is decrypted, for audit and monitoring purposes.
public event EventHandler<FieldDecryptedEventArgs>? FieldDecrypted
Event Type
FieldEncrypted
Occurs when a field is encrypted, for audit and monitoring purposes.
public event EventHandler<FieldEncryptedEventArgs>? FieldEncrypted
Event Type
KeyRotated
Occurs when encryption key rotation is completed.
public event EventHandler<EncryptionKeyRotatedEventArgs>? KeyRotated