Interface IFieldEncryptor
- Namespace
- Excalibur.Compliance
- Assembly
- Excalibur.Compliance.Abstractions.dll
Transparently encrypts and decrypts personal-data fields under a data subject's key, so that destroying the key (crypto-shredding) is sufficient to erase the subject.
public interface IFieldEncryptor
Remarks
Fields marked with PersonalDataAttribute are the intended inputs to this encryptor.
Default crypto-shredding registrations retain this collaborator in singleton services. Replacement implementations retained by that default graph must support concurrent calls and lifetime-compatible dependencies. Existing registrations are preserved; scoped replacements are not promoted or made singleton-safe by this registration.
Methods
DecryptAsync(EncryptedData, string, CancellationToken)
Decrypts a subject-bound ciphertext envelope back to plaintext.
ValueTask<byte[]?> DecryptAsync(EncryptedData envelope, string expectedTenantId, CancellationToken cancellationToken)
Parameters
envelopeEncryptedDataThe subject-bound ciphertext envelope to decrypt.
expectedTenantIdstringThe owning tenant established by the authorized request or trusted stored-record metadata. Do not derive this value from the supplied envelope. Missing or mismatched ownership is rejected before any provider or destruction-ledger lookup, including for erased generations.
cancellationTokenCancellationTokenA token that is observed for cancellation.
Returns
- ValueTask<byte[]>
A task that completes with the decrypted plaintext bytes, or null when the subject's key has been destroyed.
Remarks
This read path degrades open for shredded subjects: when the subject's key has been destroyed (the data has been crypto-erased), it returns null as a tombstone rather than throwing. Genuine integrity or algorithm failures still surface as exceptions.
A tombstone is not the only non-success outcome. Two envelopes are REFUSED rather than read, before any key is resolved: one declaring a layout version this implementation does not write, and one naming no key generation. Both raise an exception carrying InvalidCiphertext. Neither is reported as an erasure, because the material behind such an envelope cannot be identified -- and a key that was destroyed is then indistinguishable from one provisioned again at the same handle afterwards, which is the difference between stating that an erasure happened and stating one that did not.
No scope parameter, and none is needed. The envelope carries the handle of the key that produced it, so a value written under a retained aggregate type's key is decrypted under that key without the caller having to remember which type it came from.
EncryptAsync(string, RetentionScope, ReadOnlyMemory<byte>, CancellationToken)
Encrypts plaintext under the data subject's key, producing a subject-bound ciphertext envelope.
ValueTask<EncryptedData> EncryptAsync(string subjectId, RetentionScope retentionScope, ReadOnlyMemory<byte> plaintext, CancellationToken cancellationToken)
Parameters
subjectIdstringThe raw data-subject identifier whose key protects the value.
retentionScopeRetentionScopeWhere this value sits — the aggregate type and the capacity the subject holds there — or NotInAnAggregate when it is not stored inside an aggregate. It selects the subject's key unless that capacity is under a declared erasure retention, in which case it selects the capacity's own key — which is what lets a legally-retained record stay readable after the subject is erased.
plaintextReadOnlyMemory<byte>The plaintext bytes to encrypt.
cancellationTokenCancellationTokenA token that is observed for cancellation.
Returns
- ValueTask<EncryptedData>
A task that completes with the subject-bound ciphertext envelope.
Remarks
This write path fails closed: any encryption failure throws. It MUST NOT return plaintext or a partially-protected value under any circumstances. A resolved tenant context is required before key creation. The framework's single-tenant default supplies that identity; an unresolved context is refused rather than treated as the default tenant.
Exceptions
- InvalidOperationException
The tenant context has no resolved, nonblank tenant identity.