Interface IAuditIntegrityStrategy
- Namespace
- Excalibur.AuditLogging
- Assembly
- Excalibur.AuditLogging.Abstractions.dll
The single shared tamper-evidence contract for audit trails: a keyed message authentication code (HMAC) chained across records, so neither forging a record's contents nor inserting, deleting, or reordering records can go undetected by an actor without the signing key.
public interface IAuditIntegrityStrategy
Remarks
The strategy operates on opaque, backend-produced canonicalContent (see
AuditRecordCanonicalizer) so a single implementation serves every audit sink regardless
of its concrete record type. Each backend canonicalizes its own record's integrity-covered fields to
bytes, then drives this strategy.
Security invariants (load-bearing):
- The MAC is keyed (HMAC, key from the signing-key provider held outside the audit store). Producing a tag without the key is impossible — there is no unkeyed fallback. When the key cannot be obtained, tag computation and verification fail closed (throw / report invalid), never emitting or accepting an unprotected tag.
- The chain link's MAC covers the canonical content and the prior record's tag, so insert/delete/reorder breaks the chain.
- Verification uses a constant-time comparison; a missing, malformed, or unknown-key tag is treated as a violation, never as valid.
- Tags are versioned (
v1:{keyId}:{mac}) to support key rotation and algorithm agility.
Verification re-canonicalizes the live reloaded fields (never a persisted canonical blob) so it checks the queryable record that an attacker could tamper with.
Methods
ComputeTagAsync(ReadOnlyMemory<byte>, string?, CancellationToken)
Computes the versioned, keyed integrity tag for a record's canonical content, chained to the prior record's tag.
ValueTask<string> ComputeTagAsync(ReadOnlyMemory<byte> canonicalContent, string? priorTag, CancellationToken cancellationToken)
Parameters
canonicalContentReadOnlyMemory<byte>The deterministic canonical bytes of the record's integrity-covered fields.
priorTagstringThe prior record's tag, or null for the genesis record.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
Exceptions
- InvalidOperationException
Thrown (fail-closed) when no signing key is available.
VerifyAsync(ReadOnlyMemory<byte>, string?, string, CancellationToken)
Verifies a single record's integrity tag against its live canonical content and prior tag.
ValueTask<bool> VerifyAsync(ReadOnlyMemory<byte> canonicalContent, string? priorTag, string tag, CancellationToken cancellationToken)
Parameters
canonicalContentReadOnlyMemory<byte>The deterministic canonical bytes of the reloaded record's live fields.
priorTagstringThe prior record's tag, or null for the genesis record.
tagstringThe stored tag to verify.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- ValueTask<bool>
true only if the tag is well-formed, its key is known, and the keyed MAC matches; otherwise false.
VerifyChainAsync(IAsyncEnumerable<AuditChainLink>, string?, AuditChainLink?, CancellationToken)
Verifies an ordered chain of records, detecting forgery, insertion, deletion, or reordering, and reporting which of those the break was.
ValueTask<AuditChainVerificationResult> VerifyChainAsync(IAsyncEnumerable<AuditChainLink> chain, string? anchorPriorTag, AuditChainLink? successor, CancellationToken cancellationToken)
Parameters
chainIAsyncEnumerable<AuditChainLink>The ordered links of one chain partition, in the order they were written, streamed. All links must belong to the same partition: a chain assembled from interleaved partitions reports violations on an intact trail. The sequence is enumerated once, and only as far as the first break.
anchorPriorTagstringThe stored tag of the record immediately preceding
chain's first link within the same partition, or null to assert that the first link is the partition's genesis record.successorAuditChainLink?The link of the record immediately following
chainwithin the same partition, or null when no record follows it. Supplying it pins the right edge of the range the wayanchorPriorTagpins the left: the successor was written to follow the range's last record, so its keyed MAC no longer verifies once records are removed from the end of the range. Passing null when a successor does exist silently forfeits that detection.cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- ValueTask<AuditChainVerificationResult>
A result whose IsValid is true only if every link verifies, chains to its predecessor, and — when a successor is supplied — is followed by it; otherwise the index of the first broken link and what kind of break it was.
Remarks
Each link's MAC is verified against the prior tag taken from the preceding link, never from the record's own stored claim about its predecessor. That is what makes deletion detectable: a record's own claim survives the removal of the record it names, whereas the preceding link does not.
The stored claim is nonetheless checked, separately, against the predecessor actually present. That is what makes the claim a verified value rather than an unread one: altering it alone moves no MAC input, so without this check it passes unnoticed while auditor-facing exports may still read it. The two checks together also separate the two failures a bare MAC mismatch cannot tell apart — a record whose contents were rewritten from a record whose predecessor is missing.
anchorPriorTag is required rather than optional because the left edge of a verified
range is a decision the caller must make. Supplying null for a range whose first link
is not the genesis record reports that link broken — which is the intended detection of records deleted
from the front of the range.
The chain is an IAsyncEnumerable<T> rather than a materialized list because verification is a fold carrying exactly one accumulator — the prior tag — and so needs constant space however long the range is. A list-shaped parameter would make the space cost of a compliance pass grow without bound in the history it examines, and a compliance pass that exhausts memory on a year of records is one that gets switched off.