Interface ISubjectKeyManager
- Namespace
- Excalibur.Compliance
- Assembly
- Excalibur.Compliance.Abstractions.dll
Manages the lifecycle of per-subject encryption keys that underpin crypto-shredding.
public interface ISubjectKeyManager
Remarks
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.
Each data subject IN EACH TENANT is assigned its own key handle — the tenant is part of the key's identity, not a filter applied around it, because a handle is a name in a key store with no row beside it to carry a tenant column. Encrypting a subject's personal data under that key makes the data recoverable only while the key exists, so erasing the subject's key erases the subject irreversibly (crypto-shredding) without mutating every stored record. Key destruction is not performed through this interface: it is an erasure operation, and the erasure service owns it so that legal holds are honoured before any key is destroyed.
Subject identifiers are pseudonymized through the registered data-subject hasher before being used as key handles, so raw identifiers never leak into the key store.
The "one subject, one handle" sentence above holds for every value EXCEPT one, and the exception is the point of it. An aggregate type the deployment has declared it must keep through an erasure — because the law requires the data kept — resolves to a handle of its own, so that destroying the subject's handle leaves the retained record readable rather than surviving as ciphertext nobody can open. A subject therefore has one handle plus one per declared retention their data touches, and an erasure destroys the first and, by design, not the rest. A deployment that declares no retention has exactly one handle per subject, as before.
Key material MUST be produced by a cryptographically secure random number generator (RandomNumberGenerator) via the underlying key provider — never from Guid or Random. This is a security invariant of crypto-shredding: predictable key material would allow shredded data to be reconstructed.
Methods
GetOrCreateKeyAsync(TenantId, string, RetentionScope, CancellationToken)
Returns the key handle for a data subject IN A TENANT, creating a new cryptographically-random key if that tenant's subject does not yet have one.
ValueTask<SubjectKey> GetOrCreateKeyAsync(TenantId tenant, string subjectId, RetentionScope retentionScope, CancellationToken cancellationToken)
Parameters
tenantTenantIdThe tenant that owns the data being protected.
It is part of the key's identity, and it is a parameter rather than ambient state for a reason. Data-subject identifiers are consumer-supplied from consumer entities, so they repeat across tenants in ordinary multi-tenant deployments. A handle constant in the tenant would give two such tenants ONE key, and either tenant's erasure would destroy it for both — the victim reading an erasure tombstone over data that was never erased and is no longer recoverable. The tenant is supplied explicitly because the erasure path's authoritative tenant is the one its own request recorded, not whatever ambient scope the background processor running it happens to have.
A single-tenant deployment passes
TenantDefaults.DefaultTenantId. There is no absent tenant: the parameter is required so that omitting it is a compile error rather than a silent default.subjectIdstringThe raw data-subject identifier. It is pseudonymized through the registered data-subject hasher before being resolved to a key handle.
retentionScopeRetentionScopeWhere the value being protected sits — the aggregate type and the capacity the subject holds there — or NotInAnAggregate when it is not stored inside an aggregate.
It selects WHICH key, and it matters only for a capacity under a declared erasure retention. Such a capacity is legally required to survive an erasure of the subject, so its personal fields cannot share the key the erasure destroys: they get a handle of their own, and the retained record stays readable. Every other value resolves to the subject's own handle, unchanged.
cancellationTokenCancellationTokenA token that is observed for cancellation.
Returns
- ValueTask<SubjectKey>
A task that completes with the subject's key handle AND the identifier of the generation of material currently provisioned there. Both are returned by the one call because a writer that looked the generation up separately could be overtaken between the two reads and bind a generation that no longer matches the material it encrypts under.