Skip to Content
Cloud Engineering Academy
5. Security for Banking & Finance

Transaction integrity and non-repudiation

Protect payment and ledger data from duplication, loss and tampering with idempotency keys, atomic double-entry postings in DynamoDB, hash-chained audit records and digital signatures from AWS KMS asymmetric keys, and explain what non-repudiation can and cannot prove.

advanced⏱ 2 h 30 min🟡 Low costSCS-C03DVA-C03SAA-C03

Assumes: .NET 10 LTS · AWS SDK for .NET v4 (AWSSDK.KeyManagementService, AWSSDK.DynamoDBv2 4.x) · AWS CLI v2 · CDK v2 (Amazon.CDK.Lib 2.277.0) · Terraform AWS provider v6 · Region us-east-1. Verified against official sources on 2026-11-18.

Learning objectives

By the end of this lesson you can:

  • Define integrity, idempotency, atomicity, authenticity and non-repudiation, and say which control provides which property.
  • Make a payment API safe to retry with an Idempotency-Key and a conditional write in DynamoDB.
  • Post a double-entry transaction atomically with TransactWriteItems, so money is never created or lost by a partial write.
  • Detect tampering in stored records with a hash chain, and with HMACs from AWS KMS.
  • Sign and verify a payment instruction with a KMS asymmetric key (ECDSA P-256) from .NET, including offline verification with the public key.
  • Explain honestly what a digital signature proves in a dispute, and what else (logs, key policy, identity proofing) the bank needs.

Prerequisites

  • Threat modelling with STRIDE — threats T05 (duplicates) and T10 (forged messages) are solved here
  • AWS KMS lesson in this module (customer managed keys, key policies)
  • Module 6: Databases is helpful for DynamoDB basics, but not required
  • Tools: .NET 10 SDK, AWS CLI v2 with the learn-sandbox profile (only for the optional KMS part), Docker (optional, for DynamoDB Local)

Why this matters in banking

A bank's ledger is a promise: every pound that leaves one account arrives in another, every payment happens exactly once, and nobody can quietly change history. Three real failure patterns show what happens when that promise breaks:

  1. Duplicates. A mobile app times out after 10 seconds, the user taps "Send" again, and the payment is made twice. If the bank cannot prove which request was the original, it refunds the customer and eats the cost, and the regulator asks why the system allowed it.
  2. Partial writes. A debit is written, the process crashes before the credit, and GBP 4,000 disappears from the books until reconciliation finds it the next morning. Meanwhile the customer's balance is wrong.
  3. Disputes. A corporate customer's treasurer approves a CHAPS payment of GBP 750,000 to a new supplier, which turns out to be a fraudster. The customer says, "We never authorised that." The bank needs evidence that stands up: who approved it, when, what exactly they approved, and proof the record hasn't been altered since.

This lesson builds the controls for all three. It also teaches you to be careful with the word non-repudiation: a cryptographic signature is strong evidence, but whether it settles a dispute is a legal question, decided with payment-scheme rules, contract terms and the Payment Services Regulations — not by your code alone.

The idea in plain language

Five properties, five controls:

PropertyQuestion it answersControl in this lesson
IdempotencyIf the same request arrives twice, does it take effect once?Idempotency-Key + conditional write
AtomicityDo all parts of a transaction happen, or none?DynamoDB TransactWriteItems (or a database transaction)
IntegrityHas this data been changed since it was written?Hashes, hash chains, HMACs
AuthenticityDid this data come from who it claims?HMAC (shared key) or digital signature (private key)
Non-repudiationCan the originator credibly deny it later?Digital signature with a key only they control, plus logs that tie the key use to a person

The key distinction is between HMAC and signature:

  • An HMAC (hash-based message authentication code) uses one secret key shared by sender and verifier. It proves the data was produced by someone holding the key. Because the verifier also holds the key, it could have produced the HMAC itself, so an HMAC cannot prove to a third party which of them created it. Good for integrity between your own services; no good for non-repudiation.
  • A digital signature uses a private key to sign and a public key to verify. Only the private-key holder can sign; anyone can verify. If the private key never leaves an HSM and only one principal can use it, a valid signature is strong evidence that principal signed. That is the basis of non-repudiation.

Analogy: an HMAC is like a wax seal made with a stamp that you and the recipient both own: it proves the letter wasn't opened, but not which of you sealed it. A digital signature is like a notarised signature: only you can make it, anyone can check it, and the notary (here, KMS and CloudTrail) keeps a record of when you signed.

A hash chain links records so that each one includes the hash of the one before it. Changing or deleting any record breaks every hash after it, like a sealed numbered logbook where each page quotes the last line of the previous page.

What problem the AWS services solve

Service / featureWhat it gives youLimits and sharp edges (checked 2026-11-18)
AWS KMS asymmetric keys (SIGN_VERIFY)Private keys generated and used only inside FIPS-validated HSMs; Sign, Verify, GetPublicKey APIs; every call logged in CloudTrailMessages up to 4,096 bytes, or send a precomputed digest (MessageType = DIGEST); asymmetric requests are not in the KMS free tier and cost USD 0.15 per 10,000 in us-east-1; automatic rotation is not supported for asymmetric keys
AWS KMS HMAC keys (GENERATE_VERIFY_MAC)GenerateMac/VerifyMac with a key that never leaves KMSMessage up to 4,096 bytes; a symmetric scheme, so integrity/authenticity between trusted parties only
DynamoDB conditional writesConditionExpression such as attribute_not_exists(pk) makes "insert if absent" atomicFailure surfaces as ConditionalCheckFailedException
DynamoDB transactionsTransactWriteItems: up to 100 actions across tables in one Region, all-or-nothingItems must be in the same account and Region; costs twice the write capacity of a normal write; ClientRequestToken makes the transaction call itself idempotent for 10 minutes
S3 Object LockWORM storage for signed records and audit chainsCompliance mode cannot be shortened — use governance mode in labs
CloudTrailRecords who called kms:Sign, with which role and sessionManagement events, including KMS Sign, are logged; data plane volume can be high in busy systems
Amazon QLDBWas AWS's managed ledger database with a verifiable journalReached end of support on 2025-07-31; AWS's migration guidance points to Amazon Aurora PostgreSQL. Do not design new systems on it

Microsoft / Azure comparison

You know (Microsoft/Azure)AWS equivalentWhat's different
Key Vault keys with sign/verify operations, Managed HSMKMS asymmetric keys (SIGN_VERIFY); CloudHSM for full controlSame idea; KMS uses key policies as the primary access control and logs every use in CloudTrail
System.Security.Cryptography.HMACSHA256 with a secret from Key VaultKMS HMAC keys (GenerateMac/VerifyMac)The HMAC key never leaves KMS, so you can't leak it from app memory
SQL Server transactions (BEGIN TRAN … COMMIT)DynamoDB TransactWriteItems, or Aurora/RDS transactionsDynamoDB transactions are a single API call with up to 100 actions, not an open session
SQL Server Ledger tables / Azure confidential ledgerHash chains you build + S3 Object Lock; Aurora/RDS with your own ledger tablesNo managed ledger database after QLDB's end of support; build verification yourself
Azure Service Bus duplicate detectionSQS FIFO deduplication (5-minute window) + application idempotencyBroker deduplication is time-limited; your API still needs idempotency keys

Architecture

Security-boundary view

AssetWhere it livesWho can change itIntegrity control
Signing private keyKMS HSMs, never exportableNobody can read it; key policy limits kms:Sign to the payments roleKey policy, SCP, CloudTrail
Ledger entriesDynamoDB, CMK-encryptedPayments API role only (conditional, transactional writes)Transactions + invariants + hash chain
Audit chainS3 bucket with Object Lock in the log-archive accountWrite-once role; no deleteObject Lock, chain verification job
Public keyAnywhere — it is publicn/aPublished with its key ARN and validity dates

Step-by-step implementation

Define a canonical form for every record you hash or sign

A signature covers bytes, not objects. If the API serialises 100.5 and the verifier serialises 100.50, the signature fails. Fix property order, number formatting (two decimal places for money, as a string), date formats and UTC timestamps. The lab code PaymentInstruction.ToCanonicalJson() in labs/m05-secure-banking-api does exactly this. For ISO 20022 XML messages, use the canonicalisation rules your scheme specifies.

Make the create-payment endpoint idempotent

Require an Idempotency-Key header (a client-generated UUID) on POST /payments. Store the key with a hash of the request body using a conditional PutItem (attribute_not_exists). If the key exists with the same body hash, return the stored response. If it exists with a different body, return 422 — a client bug or an attack. Expire keys with a DynamoDB TTL after, say, 24 hours.

Post double-entry transactions atomically

A payment of GBP 120.00 creates two ledger entries: −120.00 on the debtor account and +120.00 on a settlement (clearing) account. Write both, plus the payment record and the balance updates, in one TransactWriteItems call, with a condition that the debtor's available balance is sufficient. Enforce the invariant in code before you call: the sum of entries in a transaction is zero.

Sign high-value or externally sent instructions with KMS

Create a KMS key with key spec ECC_NIST_P256 and key usage SIGN_VERIFY. Allow kms:Sign only to the role that approves or submits payments; allow kms:Verify and kms:GetPublicKey more widely. Compute SHA-256 locally and call Sign with MessageType = DIGEST, so the payment data never leaves your service and the 4 KB limit is irrelevant. Store the signature, key ARN, algorithm and time with the payment.

Chain audit records and store them immutably

Each audit_events record includes prev_hash (the hash of the previous record) and its own hash. Write batches to an S3 bucket with Object Lock in the log-archive account. A scheduled job recomputes the chain daily and alerts if a break is found. Periodically "anchor" the latest hash somewhere independent — for example, include it in a signed daily report or in the CloudTrail-validated digest flow of your organisation.

Reconcile

Integrity controls prevent and detect; reconciliation proves. Daily, check that every account's balance equals the sum of its entries, that settlement accounts net to the scheme's settlement report, and that the chain verifies. Reconciliation breaks are incidents.

AWS Console instructions

Creating the signing key (credits: about USD 1 per month prorated, plus USD 0.15 per 10,000 sign/verify calls):

  1. Console → Key Management Service → Customer managed keys → Create key.
  2. Key type: Asymmetric. Key usage: Sign and verify. Key spec: ECC_NIST_P256. Choose Next.
  3. Alias: hl-m05-payment-signing. Add the four mandatory tags (Project=cea-lab, Lab=m05-integrity, Environment=learn, Owner=<you>).
  4. Key administrators: your admin role only. Do not tick "Allow key administrators to delete this key" in production; in the lab it's fine.
  5. Key users: your learn-sandbox role for the lab. In production, the payment-approval role gets kms:Sign and a broader set of roles get kms:Verify.
  6. Review the key policy, then Finish.
  7. Open the key → Public key tab → Download to save the PEM public key for offline verification.

To see evidence of signing, go to Console → CloudTrail → Event history, filter Event source = kms.amazonaws.com and Event name = Sign. Each event shows the role session that signed, the key ARN, and the signing algorithm — but not the message, which is exactly what you want.

AWS CLI

# 1. Create an ECC P-256 signing key with tags.
KEY_ID=$(aws kms create-key \
  --key-spec ECC_NIST_P256 --key-usage SIGN_VERIFY \
  --description "hl-m05 payment instruction signing (lab)" \
  --tags TagKey=Project,TagValue=cea-lab TagKey=Lab,TagValue=m05-integrity \
         TagKey=Environment,TagValue=learn TagKey=Owner,TagValue=you \
  --query KeyMetadata.KeyId --output text --profile learn-sandbox)
aws kms create-alias --alias-name alias/hl-m05-payment-signing --target-key-id "$KEY_ID" --profile learn-sandbox

# 2. Make a canonical payment file and its SHA-256 digest (binary).
printf '%s' '{"paymentId":"PAY-0193a5c2-7d4e-7b11-9a00-000000000001","amount":"120.00","currency":"GBP"}' > payment.json
openssl dgst -sha256 -binary payment.json > payment.sha256

# 3. Sign the digest. KMS returns the DER-encoded signature as Base64; decode it to a file.
aws kms sign --key-id alias/hl-m05-payment-signing \
  --message fileb://payment.sha256 --message-type DIGEST \
  --signing-algorithm ECDSA_SHA_256 \
  --query Signature --output text --profile learn-sandbox | base64 --decode > payment.sig

# 4. Verify with KMS (logged in CloudTrail). SignatureValid=true on success.
aws kms verify --key-id alias/hl-m05-payment-signing \
  --message fileb://payment.sha256 --message-type DIGEST \
  --signing-algorithm ECDSA_SHA_256 --signature fileb://payment.sig --profile learn-sandbox

# 5. Verify offline with OpenSSL using the public key: no AWS call needed.
aws kms get-public-key --key-id alias/hl-m05-payment-signing \
  --query PublicKey --output text --profile learn-sandbox | base64 --decode > public.der
openssl dgst -sha256 -verify public.der -keyform DER -signature payment.sig payment.json

# 6. Tamper with the payment (amount 120.00 -> 920.00) and verify again: both checks must fail.
sed -i 's/120.00/920.00/' payment.json
openssl dgst -sha256 -verify public.der -keyform DER -signature payment.sig payment.json

Notes: with the AWS CLI v2, fileb:// passes raw bytes. When KMS Verify rejects a signature it returns an KMSInvalidSignatureException error rather than SignatureValid: false. On Windows, run these in Git Bash, where base64, openssl and sed are available.

Infrastructure as Code

The signing key with a least-privilege key policy: administrators can manage but not use the key, only the payments approval role can sign, and verification is open to a verifier role.

SigningKeyStack.cs
using Amazon.CDK;
using Amazon.CDK.AWS.IAM;
using Amazon.CDK.AWS.KMS;
using Constructs;

namespace Harbourline.Payments.Infra;

public sealed class SigningKeyStack : Stack
{
    public SigningKeyStack(Construct scope, string id, IStackProps? props = null) : base(scope, id, props)
    {
        var signerRole = Role.FromRoleName(this, "Signer", "hl-m05-payment-approver");
        var verifierRole = Role.FromRoleName(this, "Verifier", "hl-m05-payment-verifier");

        var key = new Key(this, "PaymentSigningKey", new KeyProps
        {
            Alias = "alias/hl-m05-payment-signing",
            Description = "Signs canonical payment instructions (ECDSA P-256)",
            KeySpec = KeySpec.ECC_NIST_P256,
            KeyUsage = KeyUsage.SIGN_VERIFY,
            // Asymmetric keys do not support automatic rotation: rotate by creating a new key and alias.
            PendingWindow = Duration.Days(7),      // learning shortcut: production uses 30
            RemovalPolicy = RemovalPolicy.DESTROY, // learning shortcut: production uses RETAIN
        });

        // Only the approver role may sign.
        key.AddToResourcePolicy(new PolicyStatement(new PolicyStatementProps
        {
            Sid = "AllowSignByApproverOnly",
            Principals = new IPrincipal[] { signerRole },
            Actions = new[] { "kms:Sign" },
            Resources = new[] { "*" },
            Conditions = new Dictionary<string, object>
            {
                ["StringEquals"] = new Dictionary<string, object> { ["kms:SigningAlgorithm"] = "ECDSA_SHA_256" },
            },
        }));

        // Verifiers and auditors may verify and fetch the public key.
        key.AddToResourcePolicy(new PolicyStatement(new PolicyStatementProps
        {
            Sid = "AllowVerify",
            Principals = new IPrincipal[] { verifierRole, signerRole },
            Actions = new[] { "kms:Verify", "kms:GetPublicKey", "kms:DescribeKey" },
            Resources = new[] { "*" },
        }));

        foreach (var (k, v) in new[] { ("Project", "cea-lab"), ("Lab", "m05-integrity"), ("Environment", "learn"), ("Owner", "you") })
        {
            Amazon.CDK.Tags.Of(this).Add(k, v);
        }

        _ = new CfnOutput(this, "SigningKeyArn", new CfnOutputProps { Value = key.KeyArn });
    }
}

Add using System.Collections.Generic; if your project does not enable implicit usings. The CDK Key construct's default policy grants the account root principal full access, which lets IAM policies in the account delegate key use; in production, review this default against your key-policy standard.

Complete code

The signing code is already in the module lab: labs/m05-secure-banking-api/src/Harbourline.Security.Crypto/PaymentInstructionSigner.cs (signing with MessageType.DIGEST, KMS verification, and offline verification with ECDsa and DSASignatureFormat.Rfc3279DerSequence). This lesson adds the other three controls: an idempotent, atomic double-entry posting and a hash-chained audit log.

src/Harbourline.Payments.Ledger/LedgerPosting.cs
using System.Globalization;

namespace Harbourline.Payments.Ledger;

/// <summary>One side of a double-entry posting. Negative = debit, positive = credit.</summary>
public sealed record LedgerEntry(string AccountId, decimal Amount, string Currency);

/// <summary>A balanced set of entries that must be written together or not at all.</summary>
public sealed record LedgerPosting(string PostingId, string PaymentId, IReadOnlyList<LedgerEntry> Entries)
{
    /// <summary>Throws if the posting would create or destroy money.</summary>
    public void EnsureBalanced()
    {
        if (Entries.Count < 2)
            throw new InvalidOperationException("A posting needs at least two entries.");
        if (Entries.Select(e => e.Currency).Distinct(StringComparer.Ordinal).Count() != 1)
            throw new InvalidOperationException("All entries in a posting must use one currency (FX postings use a separate pair per currency).");
        if (Entries.Any(e => e.Amount == 0m || decimal.Round(e.Amount, 2) != e.Amount))
            throw new InvalidOperationException("Entry amounts must be non-zero with at most two decimal places.");

        var sum = Entries.Sum(e => e.Amount);
        if (sum != 0m)
            throw new InvalidOperationException($"Posting {PostingId} is unbalanced by {sum.ToString("0.00", CultureInfo.InvariantCulture)}.");
    }
}
src/Harbourline.Payments.Ledger/DynamoLedgerWriter.cs
using System.Globalization;
using System.Security.Cryptography;
using System.Text;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.Model;

namespace Harbourline.Payments.Ledger;

public enum PostingOutcome { Posted, Replayed, IdempotencyKeyReused, InsufficientFunds }

/// <summary>
/// Writes an idempotent, atomic double-entry posting:
/// one TransactWriteItems call claims the idempotency key, debits and credits balances
/// with conditions, and stores the entries. Either all of it happens or none of it does.
/// </summary>
public sealed class DynamoLedgerWriter(IAmazonDynamoDB dynamo, string idempotencyTable, string balancesTable, string entriesTable)
{
    public async Task<PostingOutcome> PostAsync(
        LedgerPosting posting, string idempotencyKey, string requestBody, CancellationToken ct = default)
    {
        posting.EnsureBalanced();
        ArgumentException.ThrowIfNullOrWhiteSpace(idempotencyKey);
        var bodyHash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(requestBody)));

        var items = new List<TransactWriteItem>
        {
            // 1. Claim the idempotency key: fails if it was already used.
            new()
            {
                Put = new Put
                {
                    TableName = idempotencyTable,
                    Item = new Dictionary<string, AttributeValue>
                    {
                        ["pk"] = new() { S = idempotencyKey },
                        ["bodyHash"] = new() { S = bodyHash },
                        ["paymentId"] = new() { S = posting.PaymentId },
                        ["expiresAt"] = new() { N = DateTimeOffset.UtcNow.AddHours(24).ToUnixTimeSeconds().ToString(CultureInfo.InvariantCulture) },
                    },
                    ConditionExpression = "attribute_not_exists(pk)",
                },
            },
        };

        foreach (var entry in posting.Entries)
        {
            var amount = entry.Amount.ToString(CultureInfo.InvariantCulture);
            // 2. Update the balance. Debits require sufficient funds, checked atomically.
            items.Add(new TransactWriteItem
            {
                Update = new Update
                {
                    TableName = balancesTable,
                    Key = new Dictionary<string, AttributeValue> { ["accountId"] = new() { S = entry.AccountId } },
                    UpdateExpression = "SET balance = balance + :amt",
                    ConditionExpression = entry.Amount < 0
                        ? "attribute_exists(accountId) AND currency = :ccy AND balance >= :needed"
                        : "attribute_exists(accountId) AND currency = :ccy",
                    ExpressionAttributeValues = entry.Amount < 0
                        ? new Dictionary<string, AttributeValue>
                        {
                            [":amt"] = new() { N = amount },
                            [":ccy"] = new() { S = entry.Currency },
                            [":needed"] = new() { N = (-entry.Amount).ToString(CultureInfo.InvariantCulture) },
                        }
                        : new Dictionary<string, AttributeValue>
                        {
                            [":amt"] = new() { N = amount },
                            [":ccy"] = new() { S = entry.Currency },
                        },
                },
            });

            // 3. Record the immutable entry itself.
            items.Add(new TransactWriteItem
            {
                Put = new Put
                {
                    TableName = entriesTable,
                    Item = new Dictionary<string, AttributeValue>
                    {
                        ["postingId"] = new() { S = posting.PostingId },
                        ["accountId"] = new() { S = entry.AccountId },
                        ["paymentId"] = new() { S = posting.PaymentId },
                        ["amount"] = new() { N = amount },
                        ["currency"] = new() { S = entry.Currency },
                    },
                    ConditionExpression = "attribute_not_exists(postingId)",
                },
            });
        }

        try
        {
            await dynamo.TransactWriteItemsAsync(new TransactWriteItemsRequest
            {
                TransactItems = items,
                // Makes this API call itself idempotent for 10 minutes (SDK-level retries).
                ClientRequestToken = idempotencyKey,
            }, ct).ConfigureAwait(false);
            return PostingOutcome.Posted;
        }
        catch (TransactionCanceledException ex) when (ex.CancellationReasons?.Count > 0)
        {
            // Reason order matches TransactItems order. Index 0 = idempotency key.
            if (ex.CancellationReasons[0].Code == "ConditionalCheckFailed")
                return await ClassifyReplayAsync(idempotencyKey, bodyHash, ct).ConfigureAwait(false);
            if (ex.CancellationReasons.Any(r => r.Code == "ConditionalCheckFailed"))
                return PostingOutcome.InsufficientFunds;
            throw;
        }
    }

    private async Task<PostingOutcome> ClassifyReplayAsync(string key, string bodyHash, CancellationToken ct)
    {
        var existing = await dynamo.GetItemAsync(new GetItemRequest
        {
            TableName = idempotencyTable,
            Key = new Dictionary<string, AttributeValue> { ["pk"] = new() { S = key } },
            ConsistentRead = true,
        }, ct).ConfigureAwait(false);

        return existing.Item?.TryGetValue("bodyHash", out var stored) == true && stored.S == bodyHash
            ? PostingOutcome.Replayed              // same request again: return the original result
            : PostingOutcome.IdempotencyKeyReused; // different body, same key: reject with 422
    }
}
src/Harbourline.Payments.Ledger/AuditChain.cs
using System.Globalization;
using System.Security.Cryptography;
using System.Text;

namespace Harbourline.Payments.Ledger;

/// <summary>An audit_events record (CONVENTIONS.md schema) plus chain fields.</summary>
public sealed record AuditEvent(
    string EventId, DateTimeOffset OccurredAt, string Actor, string Action,
    string Resource, string Outcome, string SourceIp, string CorrelationId,
    string PrevHash, string Hash);

public static class AuditChain
{
    public const string Genesis = "0000000000000000000000000000000000000000000000000000000000000000";

    /// <summary>Creates the next event, binding it to the previous event's hash.</summary>
    public static AuditEvent Append(AuditEvent? previous, string eventId, DateTimeOffset occurredAt,
        string actor, string action, string resource, string outcome, string sourceIp, string correlationId)
    {
        var prevHash = previous?.Hash ?? Genesis;
        var hash = ComputeHash(prevHash, eventId, occurredAt, actor, action, resource, outcome, sourceIp, correlationId);
        return new AuditEvent(eventId, occurredAt, actor, action, resource, outcome, sourceIp, correlationId, prevHash, hash);
    }

    /// <summary>Returns the index of the first broken record, or -1 if the chain is intact.</summary>
    public static int FindFirstBreak(IReadOnlyList<AuditEvent> events)
    {
        var expectedPrev = Genesis;
        for (var i = 0; i < events.Count; i++)
        {
            var e = events[i];
            var recomputed = ComputeHash(e.PrevHash, e.EventId, e.OccurredAt, e.Actor, e.Action,
                e.Resource, e.Outcome, e.SourceIp, e.CorrelationId);
            if (e.PrevHash != expectedPrev || e.Hash != recomputed)
                return i;
            expectedPrev = e.Hash;
        }
        return -1;
    }

    private static string ComputeHash(string prevHash, string eventId, DateTimeOffset occurredAt, string actor,
        string action, string resource, string outcome, string sourceIp, string correlationId)
    {
        // Length-prefix each field so "ab"+"c" and "a"+"bc" can never collide.
        var sb = new StringBuilder();
        foreach (var field in new[]
        {
            prevHash, eventId,
            occurredAt.UtcDateTime.ToString("yyyy-MM-dd'T'HH:mm:ss.fffffff'Z'", CultureInfo.InvariantCulture),
            actor, action, resource, outcome, sourceIp, correlationId,
        })
        {
            sb.Append(field.Length.ToString(CultureInfo.InvariantCulture)).Append(':').Append(field).Append('|');
        }
        return Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(sb.ToString())));
    }
}
tests/Harbourline.Payments.Ledger.Tests/IntegrityTests.cs
using Harbourline.Payments.Ledger;
using Xunit;

public class IntegrityTests
{
    [Fact]
    public void Unbalanced_posting_is_rejected()
    {
        var posting = new LedgerPosting("PST-1", "PAY-1", new[]
        {
            new LedgerEntry("ACC-0000000001", -120.00m, "GBP"),
            new LedgerEntry("ACC-9000000001", 119.99m, "GBP"),
        });
        var ex = Assert.Throws<InvalidOperationException>(posting.EnsureBalanced);
        Assert.Contains("unbalanced by -0.01", ex.Message);
    }

    [Fact]
    public void Editing_any_audit_record_breaks_the_chain_from_that_point()
    {
        var t0 = new DateTimeOffset(2026, 11, 18, 9, 0, 0, TimeSpan.Zero);
        var e1 = AuditChain.Append(null, "evt-1", t0, "role/hl-payments-api", "payment.create", "PAY-1", "success", "198.51.100.7", "corr-1");
        var e2 = AuditChain.Append(e1, "evt-2", t0.AddSeconds(1), "role/hl-payments-api", "payment.approve", "PAY-1", "success", "198.51.100.7", "corr-1");
        var e3 = AuditChain.Append(e2, "evt-3", t0.AddSeconds(2), "role/hl-payments-api", "payment.submit", "PAY-1", "success", "198.51.100.7", "corr-1");
        Assert.Equal(-1, AuditChain.FindFirstBreak(new[] { e1, e2, e3 }));

        var tampered = e2 with { Outcome = "failure" };   // someone edits history
        Assert.Equal(1, AuditChain.FindFirstBreak(new[] { e1, tampered, e3 }));

        Assert.Equal(1, AuditChain.FindFirstBreak(new[] { e1, e3 })); // someone deletes a record
    }
}

The test project follows the platform pattern (xunit.v3 4.0.3, Microsoft.Testing.Platform, OutputType Exe). The DynamoLedgerWriter can be tested with a mocked IAmazonDynamoDB that throws a TransactionCanceledException with the cancellation reasons you want, or against DynamoDB Local in Docker (amazon/dynamodb-local), which supports transactions.

Code explained line by line

LedgerPosting

  1. LedgerEntry(… decimal Amount …) — money is always decimal; a double cannot represent 0.10 exactly, and rounding errors in a ledger are integrity failures.
  2. EnsureBalanced — the double-entry invariant: entries sum to exactly zero. This is checked before anything is written, so a bug in fee calculation can't create money.
  3. Single currency per posting — mixing GBP and EUR in one balanced set would hide an FX error; FX uses separate balanced pairs per currency.

DynamoLedgerWriter

  1. Primary constructor (IAmazonDynamoDB dynamo, …) — the client is injected (registered with AddAWSService<IAmazonDynamoDB>()), so tests can pass a mock.
  2. bodyHash — the SHA-256 of the request body is stored with the key. This is how you tell a genuine retry from a client reusing a key for a different payment.
  3. First Put with attribute_not_exists(pk) — claims the idempotency key inside the same transaction as the money movement. If the posting fails, the key claim is rolled back too, so the client can retry safely.
  4. expiresAt — a Unix epoch number for DynamoDB TTL; keys disappear after 24 hours so the table doesn't grow forever. Choose the window to exceed your clients' maximum retry period.
  5. The balance Update with balance >= :needed — the funds check and the debit happen atomically, which closes the race where two concurrent payments both see sufficient funds.
  6. currency = :ccy — prevents posting EUR to a GBP account.
  7. The entry Put with attribute_not_exists(postingId) — entries are append-only; an entry can never be overwritten. In this simplified schema postingId is the partition key and accountId the sort key.
  8. ClientRequestToken = idempotencyKey — DynamoDB's own idempotency for the API call: if the SDK retries after a network error, DynamoDB won't apply the transaction twice within 10 minutes. It complements, not replaces, the application key.
  9. catch (TransactionCanceledException …) — DynamoDB reports per-action reasons in CancellationReasons, in the same order as TransactItems. Index 0 failing means the key exists.
  10. ClassifyReplayAsync — a strongly consistent read of the stored hash decides between Replayed (return the original response) and IdempotencyKeyReused (respond 422 with ProblemDetails).

AuditChain

  1. Genesis — a fixed starting value for the first record's PrevHash.
  2. ComputeHash length-prefixes every field — without this, field boundaries are ambiguous and two different records could hash the same.
  3. Timestamps are normalised to UTC with seven fractional digits — the same canonicalisation rule as the signed payment.
  4. FindFirstBreak — recomputes every hash and checks each PrevHash links to the previous Hash. An edit breaks the edited record; a deletion breaks the record after the gap.

Limits of a hash chain: someone who can rewrite the whole chain from the edit onwards can recompute all the hashes. That is why the chain must be stored with write-once controls (Object Lock in a separate account) and its latest hash anchored somewhere the attacker cannot reach — for example signed with the KMS key daily.

Security considerations

⚠ Learning shortcut — not for production

In the lab your learn-sandbox role is both key administrator and key user, the key has a 7-day deletion window, and the audit chain is in memory. In production: separate the key administrator (can manage, cannot sign) from the user (can sign, cannot manage); deny kms:ScheduleKeyDeletion on signing keys with an SCP outside a break-glass role; use a 30-day deletion window; keep the public key and key ARN in a published, versioned register so signatures can be verified for as long as records are retained; and store audit chains in the log-archive account with Object Lock.

  • Signatures prove key use, not human intent. kms:Sign is logged with the IAM role session. To tie that to a person, the role session must come from a strongly authenticated individual (Identity Center with MFA, session tags carrying the user ID) and the UI must show the user exactly what is being signed ("what you see is what you sign").
  • Don't delete signing keys while signatures must remain verifiable. If the key is deleted, kms:Verify stops working. Keep the exported public key so offline verification remains possible, and prefer disabling old keys over deleting them.
  • Asymmetric KMS keys don't rotate automatically. Rotate by creating a new key, pointing the alias at it, and recording the validity period of each key. Verifiers must use the key ARN stored with each signature, not the alias.
  • Hashes are not secrets. Never hash low-entropy personal data (a date of birth, a sort code) and treat the hash as anonymised — it can be brute-forced. Use HMAC with a KMS key for pseudonymous identifiers.
  • Don't put personal data in KMS calls or CloudTrail. Send digests, not payment bodies; encryption context and other request parameters appear in CloudTrail.

Banking use case

Harbourline's corporate banking portal requires two approvals for CHAPS payments above GBP 250,000. When an approver clicks Approve, the portal shows the canonical payment (creditor, IBAN, amount, execution date) and the approver re-authenticates with a FIDO2 key. The approval service, running under a role whose session carries the approver's user ID as a session tag, calls kms:Sign on the digest. The signature, key ARN and approver ID are stored with the payment. The payment gateway verifies both signatures with kms:Verify before sending the ISO 20022 message to the scheme.

Months later a customer disputes a payment. The operations team produces: the canonical payment and both signatures (verified offline with the archived public key), the CloudTrail Sign events showing the approver's role sessions, the Identity Center sign-in events with MFA, and the hash-chained audit records from the Object Lock bucket. Legal and the complaints team decide what this evidence means under the customer contract and payment regulations; engineering's job was to make it trustworthy and complete.

Common mistakes

  • Treating the HTTP retry as safe because "the database has a unique index" → the second request fails with a 500 and the client retries forever, or worse, the index is on the wrong column. Return the original response for genuine retries.
  • Idempotency key stored outside the transaction → the key is claimed but the posting fails, so the customer's retry is rejected as a duplicate. Claim the key inside the same transaction, or release it on failure.
  • Signing a re-serialised object → verification fails intermittently because property order or number formats differ. Sign canonical bytes and store exactly those bytes, or a canonical form you can reproduce.
  • Using an HMAC and calling it non-repudiation → both parties hold the key; either could have made the MAC.
  • Verifying with the alias → after rotation, old signatures fail. Store and use the key ARN.
  • Checking funds with a read, then writing → race condition under concurrency. Put the check in the write's condition expression.
  • Logging the payment body next to the signature in CloudWatch → personal data in logs; log IDs and digests instead.

Troubleshooting

SymptomLikely causeFix
KMSInvalidSignatureException on VerifyData changed, wrong algorithm, wrong MessageType (signed as DIGEST, verified as RAW or vice versa), or wrong keyRecompute the canonical digest; match MessageType and SigningAlgorithm; use the key ARN stored with the signature
.NET ECDsa.VerifyHash returns false but KMS says validSignature format mismatchKMS returns DER (RFC 3279); pass DSASignatureFormat.Rfc3279DerSequence
ValidationException on Sign: message too longSending a message over 4,096 bytes as RAWHash locally and send MessageType = DIGEST
AccessDeniedException on kms:SignKey policy doesn't allow the role, or the algorithm condition doesn't matchCheck the key policy statement and kms:SigningAlgorithm condition
TransactionCanceledException with TransactionConflictAnother transaction touched the same item concurrentlyRetry with backoff; the idempotency key makes retries safe
Every second request returns 422Client generates a new body (e.g. timestamp) but reuses the keyFix the client: the key identifies one logical request with one body
Chain verification fails after a deploymentCanonicalisation changed (time format, field order)Version the hash format; never change it in place

Cost and cleanup

  • Hash chain, ledger logic and tests: free, local.
  • KMS signing key: USD 1 per month, prorated hourly (about USD 0.03 for a day), plus USD 0.15 per 10,000 Sign/Verify/GetPublicKey requests — asymmetric requests are not covered by the KMS free tier. Doing every CLI step in this lesson costs well under USD 0.05 if you schedule deletion the same day.
  • DynamoDB (optional): on-demand tables with a few hundred writes cost fractions of a cent; DynamoDB Local is free.
# Schedule the signing key for deletion (minimum 7 days; no charge while pending deletion)
aws kms delete-alias --alias-name alias/hl-m05-payment-signing --profile learn-sandbox
aws kms schedule-key-deletion --key-id "$KEY_ID" --pending-window-in-days 7 --profile learn-sandbox

# Remove local artefacts
rm -f payment.json payment.sha256 payment.sig public.der

# Confirm nothing tagged for this lab is still active
aws resourcegroupstaggingapi get-resources --tag-filters Key=Lab,Values=m05-integrity --profile learn-sandbox

A key pending deletion still appears in the tagging API until it is deleted; check KeyState is PendingDeletion with aws kms describe-key.

Exercises

  • 🟢 Guided: Run the CLI sequence to sign and verify payment.json, then tamper with it and show both KMS and OpenSSL verification fail. Find the Sign event in CloudTrail and note which role session signed.
  • 🟡 Challenge: Add a ReverseAsync method that reverses a posting: it must create a new balanced posting with opposite amounts, refuse to reverse the same posting twice, and never modify the original entries.
  • 🔴 Live problem: Reconciliation reports that account ACC-0000004711 is GBP 35.00 higher than the sum of its entries. There are no errors in the logs. What could cause this given the code above, how do you investigate, and what do you change?

Assignment

Add a Harbourline.Payments.Ledger project and tests to your portfolio repository with: the balanced-posting invariant, the hash-chained audit log, and a DynamoDB writer tested with a mocked IAmazonDynamoDB for the three outcomes (posted, replayed, key reused). Write a one-page INTEGRITY.md that explains, for a non-technical auditor, how a duplicate, a partial write, and an edited record would each be prevented or detected.

Solutions

Knowledge check

Interview questions

  • "How do you make a payment API idempotent?" — A client-supplied Idempotency-Key stored with a hash of the request, claimed with an atomic conditional write in the same transaction as the business change; replays return the stored response; a different body with the same key returns 422; keys expire after a window longer than client retries.
  • "What does non-repudiation mean, and can AWS give it to you?" — The originator can't credibly deny an action. KMS gives you a private key that never leaves HSMs and a CloudTrail record of every use; combined with strong authentication of the person behind the role, canonical "what you see is what you sign" data and immutable storage, that's strong evidence. Whether it's conclusive is a legal and contractual question.
  • "Why double-entry?" — Every movement is a balanced set of debits and credits, so money can't be created or lost by a bug; the invariant (sum = 0) is checkable in code and in reconciliation.
  • "How would you detect someone editing audit logs?" — Hash-chain the records, store them with Object Lock in a separate account, anchor the latest hash with a signature, and verify daily; CloudTrail log file validation does the same for AWS API logs.
  • "QLDB is gone. What would you use for a verifiable ledger?" — A relational or DynamoDB ledger with append-only entries, transactional posting, hash chaining and periodic signed anchors stored immutably, plus reconciliation. AWS's own QLDB migration guidance points to Aurora PostgreSQL, where you build the same pattern with tables and triggers.

Certification practice

Completion checklist

  • I can explain the difference between integrity, authenticity and non-repudiation, and HMAC versus signature
  • I signed and verified a payment with a KMS asymmetric key, online and offline
  • I saw a tampered payment fail verification
  • I can explain how the idempotency key, the transaction and the funds condition work together
  • I ran the hash-chain tests and saw an edit and a deletion detected
  • I scheduled the KMS key for deletion and confirmed nothing tagged Lab=m05-integrity is active

Key takeaways

  • Idempotency keys plus conditional writes make retries safe; claim the key in the same transaction as the money movement.
  • Double-entry postings written with TransactWriteItems and a balanced-sum invariant prevent money being created or lost.
  • Hash chains and CloudTrail log validation make tampering detectable; Object Lock in a separate account makes it hard.
  • KMS asymmetric keys give you non-exportable signing keys and a logged record of every signature; tie them to a strongly authenticated person and sign canonical bytes.
  • Engineering produces trustworthy evidence; whether it settles a dispute is a legal and contractual decision.

Further reading

Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.

On this page