Table of Contents

Interface IElasticsearchFieldEncryptionMaintenance

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

Defines maintenance operations for field-level encryption including integrity validation and key rotation.

public interface IElasticsearchFieldEncryptionMaintenance

Methods

RotateEncryptionKeysAsync(ElasticSearchDataClassification, CancellationToken)

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

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.

ValidateIntegrityAsync(string, EncryptedFieldResult, CancellationToken)

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

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.