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.
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-Keyand 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-sandboxprofile (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:
- 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.
- 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.
- 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:
| Property | Question it answers | Control in this lesson |
|---|---|---|
| Idempotency | If the same request arrives twice, does it take effect once? | Idempotency-Key + conditional write |
| Atomicity | Do all parts of a transaction happen, or none? | DynamoDB TransactWriteItems (or a database transaction) |
| Integrity | Has this data been changed since it was written? | Hashes, hash chains, HMACs |
| Authenticity | Did this data come from who it claims? | HMAC (shared key) or digital signature (private key) |
| Non-repudiation | Can 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 / feature | What it gives you | Limits 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 CloudTrail | Messages 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 KMS | Message up to 4,096 bytes; a symmetric scheme, so integrity/authenticity between trusted parties only |
| DynamoDB conditional writes | ConditionExpression such as attribute_not_exists(pk) makes "insert if absent" atomic | Failure surfaces as ConditionalCheckFailedException |
| DynamoDB transactions | TransactWriteItems: up to 100 actions across tables in one Region, all-or-nothing | Items 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 Lock | WORM storage for signed records and audit chains | Compliance mode cannot be shortened — use governance mode in labs |
| CloudTrail | Records who called kms:Sign, with which role and session | Management events, including KMS Sign, are logged; data plane volume can be high in busy systems |
| Amazon QLDB | Was AWS's managed ledger database with a verifiable journal | Reached 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 equivalent | What's different |
|---|---|---|
Key Vault keys with sign/verify operations, Managed HSM | KMS asymmetric keys (SIGN_VERIFY); CloudHSM for full control | Same 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 Vault | KMS 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 transactions | DynamoDB transactions are a single API call with up to 100 actions, not an open session |
| SQL Server Ledger tables / Azure confidential ledger | Hash chains you build + S3 Object Lock; Aurora/RDS with your own ledger tables | No managed ledger database after QLDB's end of support; build verification yourself |
| Azure Service Bus duplicate detection | SQS FIFO deduplication (5-minute window) + application idempotency | Broker deduplication is time-limited; your API still needs idempotency keys |
Architecture
Security-boundary view
| Asset | Where it lives | Who can change it | Integrity control |
|---|---|---|---|
| Signing private key | KMS HSMs, never exportable | Nobody can read it; key policy limits kms:Sign to the payments role | Key policy, SCP, CloudTrail |
| Ledger entries | DynamoDB, CMK-encrypted | Payments API role only (conditional, transactional writes) | Transactions + invariants + hash chain |
| Audit chain | S3 bucket with Object Lock in the log-archive account | Write-once role; no delete | Object Lock, chain verification job |
| Public key | Anywhere — it is public | n/a | Published 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):
- Console → Key Management Service → Customer managed keys → Create key.
- Key type: Asymmetric. Key usage: Sign and verify. Key spec:
ECC_NIST_P256. Choose Next. - Alias:
hl-m05-payment-signing. Add the four mandatory tags (Project=cea-lab,Lab=m05-integrity,Environment=learn,Owner=<you>). - Key administrators: your admin role only. Do not tick "Allow key administrators to delete this key" in production; in the lab it's fine.
- Key users: your
learn-sandboxrole for the lab. In production, the payment-approval role getskms:Signand a broader set of roles getkms:Verify. - Review the key policy, then Finish.
- 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.jsonNotes: 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.
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.
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)}.");
}
}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
}
}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())));
}
}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
LedgerEntry(… decimal Amount …)— money is alwaysdecimal; adoublecannot represent 0.10 exactly, and rounding errors in a ledger are integrity failures.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.- 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
- Primary constructor
(IAmazonDynamoDB dynamo, …)— the client is injected (registered withAddAWSService<IAmazonDynamoDB>()), so tests can pass a mock. 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.- First
Putwithattribute_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. 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.- The balance
Updatewithbalance >= :needed— the funds check and the debit happen atomically, which closes the race where two concurrent payments both see sufficient funds. currency = :ccy— prevents posting EUR to a GBP account.- The entry
Putwithattribute_not_exists(postingId)— entries are append-only; an entry can never be overwritten. In this simplified schemapostingIdis the partition key andaccountIdthe sort key. 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.catch (TransactionCanceledException …)— DynamoDB reports per-action reasons inCancellationReasons, in the same order asTransactItems. Index 0 failing means the key exists.ClassifyReplayAsync— a strongly consistent read of the stored hash decides between Replayed (return the original response) and IdempotencyKeyReused (respond422with ProblemDetails).
AuditChain
Genesis— a fixed starting value for the first record'sPrevHash.ComputeHashlength-prefixes every field — without this, field boundaries are ambiguous and two different records could hash the same.- Timestamps are normalised to UTC with seven fractional digits — the same canonicalisation rule as the signed payment.
FindFirstBreak— recomputes every hash and checks eachPrevHashlinks to the previousHash. 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:Signis 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:Verifystops 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
| Symptom | Likely cause | Fix |
|---|---|---|
KMSInvalidSignatureException on Verify | Data changed, wrong algorithm, wrong MessageType (signed as DIGEST, verified as RAW or vice versa), or wrong key | Recompute the canonical digest; match MessageType and SigningAlgorithm; use the key ARN stored with the signature |
.NET ECDsa.VerifyHash returns false but KMS says valid | Signature format mismatch | KMS returns DER (RFC 3279); pass DSASignatureFormat.Rfc3279DerSequence |
ValidationException on Sign: message too long | Sending a message over 4,096 bytes as RAW | Hash locally and send MessageType = DIGEST |
AccessDeniedException on kms:Sign | Key policy doesn't allow the role, or the algorithm condition doesn't match | Check the key policy statement and kms:SigningAlgorithm condition |
TransactionCanceledException with TransactionConflict | Another transaction touched the same item concurrently | Retry with backoff; the idempotency key makes retries safe |
| Every second request returns 422 | Client generates a new body (e.g. timestamp) but reuses the key | Fix the client: the key identifies one logical request with one body |
| Chain verification fails after a deployment | Canonicalisation 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/GetPublicKeyrequests — 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-sandboxA 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 theSignevent in CloudTrail and note which role session signed. - 🟡 Challenge: Add a
ReverseAsyncmethod 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-0000004711is 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
Follow the CLI section. After sed changes the amount, OpenSSL prints Verification failure and aws kms verify (with a recomputed digest) fails with KMSInvalidSignatureException. In CloudTrail Event history, filter by event name Sign: userIdentity.arn shows assumed-role/<your SSO role>/<your user> and requestParameters shows the key ID, messageType: DIGEST and the algorithm — not the message.
Why it matters: the evidence of who signed comes from CloudTrail and identity, not from the signature itself. The signature proves which key signed which bytes.
public static LedgerPosting CreateReversal(LedgerPosting original, string reversalPostingId) =>
new(reversalPostingId, original.PaymentId,
original.Entries.Select(e => e with { Amount = -e.Amount }).ToList());Write the reversal with the same DynamoLedgerWriter, using "reversal:" + original.PostingId as the idempotency key. Because the idempotency key is claimed with attribute_not_exists, a second reversal of the same posting returns Replayed or IdempotencyKeyReused instead of posting again. Add a status update on the payment (reversed) to the same transaction with a condition status = :booked.
Why: ledgers are append-only. A correction is a new balanced posting that references the original, so the history of what happened is preserved for audit.
Possible causes: (1) a code path that updates balance outside DynamoLedgerWriter (for example an admin "fix" script or a fee job) without writing an entry; (2) a direct console edit by a human; (3) a transaction that wrote the balance update but an entry write was routed to a different table due to configuration drift.
Investigate: look for UpdateItem calls on the balances table in CloudTrail data events (if enabled) or application audit events; check which principals have write access to the table; list entries and balance changes around the time the difference appeared (point-in-time recovery lets you restore a copy and compare).
Change: remove all write paths except the transactional writer (IAM: only its role may UpdateItem); add a daily automated reconciliation alarm; consider deriving balances from entries (event sourcing) or adding a version attribute so out-of-band updates are detectable. Treat it as an incident until explained.
Knowledge check
Answer: Both the sender and the verifier hold the same secret key, so either could have produced the MAC. A third party can't tell which one did. A digital signature uses a private key that only the signer can use, so verification by anyone with the public key points to the signer.
Answer: Compute the SHA-256 digest locally and call Sign with MessageType = DIGEST and ECDSA_SHA_256 (or an RSA PSS/PKCS1 algorithm for an RSA key). RAW messages are limited to 4,096 bytes. Sending the digest also keeps the payment contents out of the KMS request.
Answer: It makes the same TransactWriteItems call idempotent for 10 minutes, protecting against SDK or network retries applying the transaction twice. It doesn't cover a user tapping Send twice an hour apart, or a client generating a new request; that needs an application-level idempotency key with a longer window.
Answer: Between the read and the write, another request can debit the same account. A condition expression is evaluated atomically with the write, so two concurrent debits can't both succeed against the same balance.
Answer: The verifier is using the alias, which now points to the new key. Signatures must be verified with the key ARN recorded at signing time; keep old keys enabled for Verify (or keep their public keys) for the retention period.
Interview questions
- "How do you make a payment API idempotent?" — A client-supplied
Idempotency-Keystored 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
A bank must sign payment files sent to a clearing house. The private key must never be exportable, every signing operation must be auditable, and the clearing house must verify signatures without calling AWS. Which solution meets these requirements?
A. Generate an RSA key pair with OpenSSL, store the private key in Secrets Manager, and sign in the application.
B. Create a KMS asymmetric key with key usage SIGN_VERIFY, sign with the KMS Sign API, and give the clearing house the public key from GetPublicKey.
C. Create a KMS symmetric key and use GenerateMac; share the key ARN with the clearing house.
D. Use a KMS HMAC key and give the clearing house an IAM role to call VerifyMac.
Answer: B. The private key stays in KMS, Sign is logged in CloudTrail, and the public key allows offline verification. A makes the private key retrievable. C — GenerateMac needs an HMAC key, and a MAC can't be verified offline by a third party. D requires the clearing house to call AWS and still isn't a signature.
A developer is implementing transfers between two accounts stored as items in an Amazon DynamoDB table. A transfer must debit one item and credit another, and must fail if the source balance is insufficient. Which approach should the developer use?
A. Two UpdateItem calls, the debit first, with a retry on failure.
B. BatchWriteItem with both updates.
C. TransactWriteItems with two Update actions and a condition expression on the source balance.
D. A DynamoDB Stream that applies the credit after the debit is written.
Answer: C. Transactions are all-or-nothing and the condition is evaluated atomically. A can leave a debit without a credit. B — BatchWriteItem supports only puts and deletes, not conditional updates, and is not atomic. D is eventually consistent and can fail between steps.
An auditor asks how the bank can prove its CloudTrail logs have not been modified or deleted since delivery. What should the security engineer show?
A. S3 server-side encryption with KMS on the trail bucket.
B. CloudTrail log file integrity validation enabled, with digest files, and the validate-logs command output.
C. S3 Versioning on the trail bucket.
D. An Amazon Macie job on the trail bucket.
Answer: B. Log file validation uses SHA-256 hashes and signed digest files that chain together, so modification or deletion is detectable. A protects confidentiality. C helps recovery but doesn't prove integrity on its own. D classifies sensitive data.
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-integrityis 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
TransactWriteItemsand 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.
UK GDPR and data residency
Design AWS workloads that respect UK GDPR: lawful basis, minimisation, the right to erasure versus immutable logs (pseudonymisation and crypto-shredding in .NET), international transfers, Region choice and residency guardrails. Concepts only — legal and DPO review required.
Labs 5.3 and 5.7: envelope encryption with KMS and signing payment instructions
Encrypt customer fields with a KMS data key and AES-GCM, prove that a copied ciphertext will not decrypt for another customer, sign a payment instruction with an asymmetric KMS key, verify it online and offline, and optionally repeat both against real KMS with Terraform before scheduling the keys for deletion.