Table of Contents

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

canonicalContent ReadOnlyMemory<byte>

The deterministic canonical bytes of the record's integrity-covered fields.

priorTag string

The prior record's tag, or null for the genesis record.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

ValueTask<string>

The versioned integrity tag in the form v1:{keyId}:{mac}.

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

canonicalContent ReadOnlyMemory<byte>

The deterministic canonical bytes of the reloaded record's live fields.

priorTag string

The prior record's tag, or null for the genesis record.

tag string

The stored tag to verify.

cancellationToken CancellationToken

A 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.

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

chain IAsyncEnumerable<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.

anchorPriorTag string

The 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.

successor AuditChainLink?

The link of the record immediately following chain within the same partition, or null when no record follows it. Supplying it pins the right edge of the range the way anchorPriorTag pins 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.

cancellationToken CancellationToken

A 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.

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.