Build a tamper-evident license audit log with hash chaining
A step-by-step guide to turning Keyright's license audit trail into a hash-chained, tamper-evident log: how each entry seals the one before it, how to read and verify the chain over the admin API and the CLI, how to anchor the head hash so a deletion cannot hide, and the C# you need to prove the trail in CI.
An audit log is only worth as much as its weakest guarantee, and for a licensing system that guarantee is usually nothing at all. Most issuing services write a row per operation — key issued, seat claimed, license revoked — and trust that nobody with access ever rewrites history. But the audit trail is exactly the record someone wants to edit: a reseller who over-issued, an insider who quietly re-activated a revoked key, a dispute where the question is what did the server actually do, and when. If any party can delete or back-date a row without leaving a mark, the log proves nothing.
This is a how-to for closing that gap. We will take Keyright’s audit trail and make it tamper-evident by chaining every entry to the cryptographic hash of the one before it. The result is a log where changing, reordering, or deleting any historical entry breaks every entry after it, and where you can prove to a third party that the record is intact — without trusting the storage, the operator, or the host.
What hash chaining buys you
Tamper-proof is the wrong word; storage can always be wiped. The achievable property is tamper-evidence: any modification is detectable. Hash chaining delivers it with one rule. Each audit entry carries the hash of the previous entry’s hash. Because a SHA-256 digest depends on every bit of its input, entry N’s hash transitively commits to the entire history before it. Flip a byte in entry 5 and entry 5’s hash changes, which invalidates entry 6’s stored prevHash, which changes entry 6’s hash, and so on to the head. One verification pass over the chain catches a tamper anywhere in it.
Step 1 — Enable the audit chain
In your Keyright instance, the audit trail is written for every state-changing operation by default, but chaining is opt-in so that existing deployments are not forced to re-hash their history on upgrade. Turn it on in keyright.config.json:
{
"audit": {
"chain": {
"enabled": true,
"hashAlgorithm": "SHA-256",
"genesisLabel": "acme-prod-2026"
}
}
}
The genesisLabel is folded into the very first entry’s hash so two separate deployments that happen to log identical operations still produce different chains — it binds the chain to this instance. On the next start, Keyright seals a genesis entry (seq: 0) whose prevHash is 32 zero bytes, and every subsequent operation extends from there. Community Edition includes the chained writer; what the paid tiers add is signed checkpointing, covered in Step 4.
Step 2 — Read the chain over the admin API
Entries are exposed through the admin API in sequence order. Page forward with the after cursor so you never have to pull the whole trail at once:
GET /v1/admin/audit?after=40&limit=3 HTTP/1.1
Host: licensing.internal.acme.example
Authorization: Bearer <admin-token>
{
"entries": [
{
"seq": 41,
"ts": "2026-11-16T09:12:04.118Z",
"actor": "svc:fulfillment",
"action": "key.issued",
"subject": "KR-9QX2-7F3M-...",
"payloadHash": "sha256:1f0a9c...",
"prevHash": "sha256:a7f3e2...",
"entryHash": "sha256:3c1b88..."
}
],
"head": { "seq": 43, "entryHash": "sha256:d55a10..." }
}
Two deliberate choices make this safe to hand around. The entry carries only a payloadHash, not the payload itself — the full operation detail (licensee email, machine fingerprint) stays behind the admin boundary, so the verifiable record never leaks personal data. And the response echoes the current head, which is the single value you need to detect a truncation attack: if entries vanish off the end, the head you remember will no longer match.
Step 3 — Verify the chain yourself
Do not trust the server to tell you the chain is valid; recompute it. The only subtlety is that the hash must be taken over a canonical byte encoding — the same bytes the server hashed — so field order and formatting are fixed, not left to a JSON serializer’s whims. Keyright canonicalizes each entry as length-prefixed UTF-8 fields in a frozen order, then hashes prevHash ‖ canonicalBytes.
using System.Security.Cryptography;
using System.Text;
static byte[] Canonicalize(AuditEntry e)
{
// Frozen field order. Each field is length-prefixed so that
// ("ab","c") and ("a","bc") can never collide.
using var ms = new MemoryStream();
void Field(string s)
{
var b = Encoding.UTF8.GetBytes(s);
Span<byte> len = stackalloc byte[4];
BinaryPrimitives.WriteUInt32BigEndian(len, (uint)b.Length);
ms.Write(len);
ms.Write(b);
}
Field(e.Seq.ToString(CultureInfo.InvariantCulture));
Field(e.Ts.ToString("O", CultureInfo.InvariantCulture)); // round-trip ISO-8601
Field(e.Actor);
Field(e.Action);
Field(e.Subject);
Field(e.PayloadHash);
return ms.ToArray();
}
static byte[] ComputeHash(byte[] prevHash, AuditEntry e)
{
using var sha = SHA256.Create();
sha.TransformBlock(prevHash, 0, prevHash.Length, null, 0);
var body = Canonicalize(e);
sha.TransformFinalBlock(body, 0, body.Length);
return sha.Hash!;
}
// Walk the chain. Returns the seq of the first broken entry, or null if intact.
static long? FindBreak(IReadOnlyList<AuditEntry> entries, byte[] genesisPrev)
{
var prev = genesisPrev; // 32 zero bytes, or the hash of your last checkpoint
foreach (var e in entries) // must be contiguous and ascending by seq
{
var expected = ComputeHash(prev, e);
if (!CryptographicOperations.FixedTimeEquals(expected, Convert.FromHexString(e.EntryHash)))
return e.Seq;
prev = expected;
}
return null;
}
FindBreak is the whole security model in twenty lines. Start from a prevHash you already trust — the genesis zero-block the first time, or the hash of your last verified checkpoint on later runs — and recompute each entry’s hash from the previous one. The first entry whose stored entryHash does not match is the point of tampering, or the point where a row was deleted and the sequence no longer lines up. Note the length-prefixed fields: without them, an attacker could shuffle bytes between actor and action and leave the concatenation unchanged.
Step 4 — Anchor the head so deletion cannot hide
Hash chaining catches edits and reordering, but not the honest-looking truncation where someone lops off the tail and nobody has a copy of what used to be there. The fix is to periodically publish the head hash somewhere the operator cannot silently rewrite — a checkpoint. Keyright can emit one on a schedule:
{
"audit": {
"chain": { "enabled": true },
"checkpoint": { "everyMinutes": 60, "sign": true }
}
}
A signed checkpoint is a tiny record — { seq, entryHash, ts } signed with your issuing key — that you forward out of the system: into a separate append-only store, a compliance mailbox, a counterparty’s inbox. Once a counterparty holds a checkpoint saying “at 10:00 the head was at seq 4,210 with hash d55a…”, no later deletion can take the trail below 4,210 without contradicting a signature they already have. The chain proves internal consistency; the checkpoint pins the chain to a point in wall-clock time that an outsider witnessed.
Step 5 — Verify in CI, not just by hand
Make the verification a build step so a broken chain fails loudly instead of waiting for a dispute. The CLI pulls the range, recomputes it, and exits non-zero on the first mismatch:
$ keyright audit verify --from 0 --to head \
--expect-checkpoint checkpoints/2026-11-16T10-00.json
Verifying 4211 entries from genesis…
genesis label: acme-prod-2026
checkpoint seq 4210 hash d55a10… OK (signature valid)
Chain intact: 4211/4211 entries, head d55a10… at 2026-11-16T10:00:11Z
A tampered trail produces the opposite, naming the first entry that fails so you know exactly where history was touched:
$ keyright audit verify --from 0 --to head
Chain BROKEN at seq 42: stored hash 8e04a1… != computed 0b7cc9…
entries 0–41 verify; everything from 42 onward is unprovable
error: audit chain verification failed (exit 2)
What legitimately breaks a chain
A broken chain is not always an attack, and treating every break as a breach will teach your team to ignore the alert. Three benign causes are worth knowing. A schema migration that adds a field to the canonical encoding will change every hash after it — which is why you start a fresh chain segment at the migration boundary and checkpoint the old head rather than re-hashing history in place. A restore from backup that loses the entries written after the snapshot is a real gap, but an expected one; the checkpoint tells you precisely how many entries you are missing. And a clock that jumps backward can make timestamps non-monotonic without breaking the hash at all — the chain commits to the order you wrote entries, not to honest time, which is exactly why wall-clock trust lives in the signed checkpoint and not in the ts field.
Summary
Chaining turns a licensing audit trail from a set of editable rows into a record that defends itself. Enable the chain in config, read entries and the head over the admin API, recompute the chain with a twenty-line walk over a canonical encoding, and anchor the head with signed checkpoints so truncation cannot hide. The payoff is a trail you can hand to an auditor, a partner, or a court and prove, from first principles, that it has not been rewritten since the last point anyone witnessed it.
Try Nebula.NET
Harden your .NET code in minutes — start with the free edition.