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.
Assumes: .NET 10 LTS · AWS SDK for .NET v4 (AWSSDK.KeyManagementService 4.1.1.1) · xUnit v3 4.0.3 · Terraform 1.10+ with AWS provider v6 · AWS CLI v2 · Region us-east-1. Verified against official sources on 2026-11-18.
Learning objectives
By the end of these labs you can:
- Describe envelope encryption and say why a bank uses it: the customer managed key never leaves KMS, payloads of any size can be encrypted, and every unwrap is an authorised, logged call.
- Run the lab's
EnvelopeEncryptorandFieldEncryptor, and prove with tests that a ciphertext copied to another customer, or to another field, does not decrypt. - Explain encryption context (non-secret labels bound to the ciphertext and written to CloudTrail) and what must never go in it.
- Sign a canonical payment instruction with an asymmetric
ECC_NIST_P256KMS key, verify it with KMS and offline with the exported public key, and show that a one-penny change breaks the signature. - Handle the .NET detail that bites everyone: KMS returns ECDSA signatures in DER format, and .NET defaults to the fixed-size format.
- Read the Terraform that creates the keys with a least-privilege policy, and (optionally) run the same demos against real KMS for a few cents, then schedule the keys for deletion.
- Say when to use the AWS Encryption SDK instead of this hand-written format.
This page covers Lab 5.3 (envelope encryption) and Lab 5.7 (signing a payment instruction). The theory is in KMS and envelope encryption and Transaction integrity and non-repudiation. For hardware you control, see CloudHSM and custom key stores.
Prerequisites
- KMS and envelope encryption and Transaction integrity and non-repudiation.
- Docker Desktop. The .NET 10 SDK is optional for the offline part.
- For the optional AWS part (Part 4, credits): AWS CLI v2,
aws sso login --profile learn-sandbox, Terraform 1.10 or later, and an SSO role allowedkms:GenerateDataKey,kms:Decrypt,kms:Sign,kms:Verifyandkms:GetPublicKeyon the lab keys. Use only the sandbox account.
Why this matters in banking
A customer database is stolen from a backup. If dates of birth and IBANs were stored as plain text, that is a reportable breach with a large cost. If they were encrypted with one key held in the application's configuration, the attacker has the data and the key in the same place. With envelope encryption under a KMS key, the stolen rows are unreadable without a call to KMS, which only the right role can make, which CloudTrail records with the customer id in the log. And when the payments team needs to prove later that a payment instruction was approved by the bank's signing service and not altered, a signature made by a key that never left KMS, verifiable by anyone holding the public key, is the evidence.
The idea in plain language
Envelope encryption. Encrypting big data directly with a master key is slow and awkward, and the master key would have to be handed to every application. Instead:
- Ask KMS for a fresh one-time data key. KMS gives it to you twice: once in plain text, once encrypted ("wrapped") under your master key.
- Encrypt your data locally with the plaintext data key (AES-256-GCM).
- Throw the plaintext key away and store the wrapped key next to the ciphertext.
- To read the data, send the wrapped key back to KMS. If you are allowed, KMS returns the plain data key, and you decrypt locally.
Analogy: a bank sends valuables by courier in locked boxes. Each box gets its own key. The box key is sealed in an envelope that only the vault's key-officer (KMS) can open. The courier carries the box and the sealed envelope together. To open a box, someone must ask the key-officer, who checks their ID and writes it in the register (CloudTrail).
Encryption context. When you ask KMS for a data key you can attach labels such as customer_id=CUS-00012345. KMS will only unwrap the key if you present exactly the same labels. The labels are not secret; they are visible in CloudTrail, which makes them an audit trail ("whose field was decrypted?") as well as a binding.
Signing. With an asymmetric key pair the private key signs and the public key verifies. KMS holds the private key and never lets it out. Anyone with the public key can check a signature, offline and years later.
What the AWS services do here
- AWS KMS holds the keys, enforces the key policy and IAM, and logs every use. Three key types appear: a symmetric key (
alias/hl-m05-data), an asymmetric signing key (alias/hl-m05-payment-signing, specECC_NIST_P256, usageSIGN_VERIFY) and a symmetric key for Secrets Manager (alias/hl-m05-secrets). - AWS CloudTrail records
GenerateDataKey,Decrypt,Sign,VerifyandGetPublicKeyevents, including the encryption context. This is your access log for data. - IAM and the key policy decide who may use each key. The lab's task role may only call
GenerateDataKeyandDecryptwhen the request carries the encryption-context keycustomer_id. - Terraform creates the keys, aliases and the role for the optional AWS part.
Microsoft / Azure comparison
| You know (Microsoft/Azure) | AWS in this lab | What's different |
|---|---|---|
| Azure Key Vault keys with wrap/unwrap | KMS GenerateDataKey and Decrypt | KMS returns a ready-made wrapped data key in one call, instead of you generating the key and wrapping it |
| SQL Server Always Encrypted | FieldEncryptor in application code | AWS does not do it in the database driver. You do it in code, and an encrypted column cannot be searched without extra design |
| Key Vault key access policy or RBAC | KMS key policy plus IAM | The key policy is the primary access control. Without the "enable IAM policies" statement, IAM alone cannot grant access |
Azure Key Vault sign operation | KMS Sign with MessageType = DIGEST | You hash locally and send only the digest. The payment details never go to KMS |
| Key Vault soft delete and purge protection | KMS pending deletion (7 to 30 days) | A key cannot be deleted instantly. It sits in a pending state that you can cancel |
Data protection API (IDataProtector) | Envelope encryption with an explicit context | The context is an explicit, auditable "purpose string" that lands in the log |
Architecture
And for signing:
Step-by-step implementation
The lab folder is labs/m05-secure-banking-api. The relevant projects are Harbourline.Security.Crypto (the library), Harbourline.Security.Tools (the hl-crypto demo) and the tests in Harbourline.SecureBanking.Tests.
Part 1: run the tests (free)
Run them in Docker
MSYS_NO_PATHCONV=1 docker run --rm --memory 3g \
-v "$PWD/labs/m05-secure-banking-api:/src" \
-v cea-nuget-m05:/root/.nuget/packages \
-w /src mcr.microsoft.com/dotnet/sdk:10.0 \
sh -c "dotnet test --solution SecureBankingApi.slnx; find . -type d \( -name bin -o -name obj \) -prune -exec rm -rf {} +"Expected result (verified 2026-11-18 in Docker): total: 72, failed: 0, succeeded: 71, skipped: 1. The skipped test, Envelope_demo_against_real_kms_when_enabled, calls real KMS and runs only with RUN_AWS_TESTS=1.
Map the tests to the claims
| Test | What it proves |
|---|---|
Field_round_trips_for_the_same_customer_and_field | A field encrypts to a token starting enc:v1: that does not contain the plaintext, and decrypts with the same customer and field |
Ciphertext_copied_to_another_customer_does_not_decrypt | Decrypting with another customer id throws InvalidCiphertextException (the encryption context does not match) |
Ciphertext_copied_to_another_field_does_not_decrypt | The same for a ciphertext moved from the IBAN column to the date-of-birth column |
Same_value_encrypts_differently_each_time | A fresh data key and nonce each time, so equal values are not visibly equal |
Tampered_ciphertext_fails_authentication | AES-GCM's authentication tag detects any modification |
Envelope_survives_serialisation, Truncated_envelope_is_rejected | The length-prefixed binary layout round-trips and rejects truncated input |
Disabled_key_makes_existing_data_unreadable | Disabling the key stops all decrypts, which is the emergency brake of the incident runbook |
Decrypt_pinned_to_a_different_key_is_refused | Decrypt pins KeyId, so rewriting the stored key id to an attacker's key fails |
Signature_verifies_with_kms_and_offline | A signature made through KMS verifies both ways |
One_penny_change_breaks_the_signature | 1250.00 versus 1250.01 produces failed verification, online and offline |
Canonical_json_is_stable_and_uses_two_decimals, Non_positive_amounts_are_rejected, Three_decimal_places_are_rejected | The signed bytes are deterministic, and invalid money values never reach KMS |
Demo_passes_against_the_local_kms (envelope, sign), Demo_requires_an_explicit_mode | The command-line demo works offline and refuses to guess whether to call AWS |
Part 2: Lab 5.3, envelope encryption offline (free)
Run the demo against the local stand-in
dotnet run --project src/Harbourline.Security.Tools -- envelope --localReal output from this build (verified 2026-11-18): the demo prints four numbered lines, and the exit code is 0.
KMS: local stand-in (no AWS calls), key: alias/hl-m05-data
1. Encrypted date_of_birth → enc:v1:AQA4YXJuOmF3czprbXM6dXMtZWFzdC0xOjAwMDAwM… (303 chars)
2. Decrypt with matching context → OK
3. Decrypt as another customer → refused by KMS (InvalidCiphertextException), as expected
4. Encrypting the same value again gives a different token → TrueThe AQA4YXJ... start is the Base64 of the version byte and the key ARN (arn:aws:kms:us-east-1:000000...). The local stand-in LocalDevelopmentKms fakes KMS in memory, with the behaviours that matter for learning: the context is bound to the wrapped key, a wrong context or key makes Decrypt fail, a disabled key refuses to work. It has no IAM, key policy, CloudTrail or durability, so it is a learning shortcut (see below).
Read the token format
EnvelopeCiphertext.ToBase64() writes a length-prefixed binary layout: one byte of version, then the key id, the wrapped data key, the 12-byte nonce, the 16-byte tag and the ciphertext, with big-endian length prefixes. A version byte means you can change the algorithm or layout later without breaking stored records, which is the thing hand-rolled formats most often forget.
Break it on purpose
Edit FieldEncryptor.ContextFor so the context contains only customer_id (remove field). Run the tests. Ciphertext_copied_to_another_field_does_not_decrypt now fails, because without the field in the context an IBAN ciphertext can be moved to the date-of-birth column and still decrypt. Revert. Then try putting the customer's date of birth into the context and run the demo: it works, which is why the doc comment says never to do it. The context is visible in CloudTrail in plain text, so it must hold identifiers, never personal data.
Part 3: Lab 5.7, signing a payment instruction offline (free)
Run the signing demo
dotnet run --project src/Harbourline.Security.Tools -- sign --localReal output from this build (verified 2026-11-18):
KMS: local stand-in (no AWS calls), key: alias/hl-m05-payment-signing
Canonical JSON: {"paymentId":"PAY-01933b6e-7c1a-7d42-9b1e-5f0c2a9d8e11","debtorAccountId":"ACC-0001234567","creditorName":"Northwind Supplies Ltd","creditorIban":"GB33BUKB20201555555555","amount":"1250.00","currency":"GBP","scheme":"FPS","endToEndId":"HL-E2E-20261118-0001","requestedExecutionDate":"2026-11-18","createdAt":"2026-11-18T09:30:00.0000000Z"}
1. Signed with ECDSA_SHA_256; signature MEUCIGfhCtrBlVtLive0NtB1…
2. Verify with KMS → True
3. Verify offline with the exported public key → True
4. Amount changed to 1250.01 → KMS: False, offline: False (both should be False)The signature will differ on every run (ECDSA includes a random value). The signature begins MEUC... because it is a DER-encoded structure: a sequence of two integers.
Why the instruction is canonicalised
A signature covers bytes, not objects. PaymentInstruction.ToCanonicalJson() fixes the property order, camelCase names, the amount as a string with exactly two decimals, the date as yyyy-MM-dd and the timestamp as UTC with a Z suffix and seven fractional digits. Two systems that serialise 100.5 and 100.50 differently would produce different bytes and a signature that will not verify. The tests Canonical_json_is_stable_and_uses_two_decimals and Three_decimal_places_are_rejected lock the rules.
Why the digest is sent, not the message
PaymentInstructionSigner.SignAsync hashes the canonical bytes with SHA-256 locally and calls Sign with MessageType = DIGEST and SigningAlgorithm = ECDSA_SHA_256. Only 32 bytes go to KMS, so the payment details never leave the application, and the 4 KB message limit does not apply.
Why .NET needs Rfc3279DerSequence
KMS returns ECDSA signatures DER-encoded (RFC 3279). .NET's ECDsa.VerifyHash defaults to the fixed-size IEEE P1363 format (r and s concatenated). Without the format argument, a correct signature fails verification with no helpful error. VerifyOffline therefore calls VerifyHash(digest, signature, DSASignatureFormat.Rfc3279DerSequence) after importing the public key with ImportSubjectPublicKeyInfo.
Part 4: the same demos against real KMS (optional, credits)
Cost and scope
Three KMS keys cost about 1 USD per key per month, prorated hourly (⚠ VERIFY current KMS pricing), plus one secret at about 0.40 USD per month. Destroyed the same day, this costs a few cents. KMS API calls have a free monthly allowance (⚠ VERIFY the current number). Use only the sandbox account, and run the teardown the same day.
Sign in and prepare Terraform
aws sso login --profile learn-sandbox
aws sts get-caller-identity --profile learn-sandbox
cd labs/m05-secure-banking-api/infra/terraform
# Either a remote state bucket (copy backend.hcl.example to backend.hcl and edit the bucket) ...
terraform init -backend-config=backend.hcl
# ... or, for a throwaway local state file:
# terraform init -backend=falseThe Terraform syntax was validated in this build with terraform init -backend=false and terraform validate (result: "The configuration is valid", Terraform 1.14 image). It was not applied.
Review what it creates, then apply
terraform plan -var owner=<your-name>
terraform apply -var owner=<your-name>It creates alias/hl-m05-data (symmetric, automatic rotation on, 7-day deletion window by default), alias/hl-m05-payment-signing (ECC_NIST_P256, SIGN_VERIFY), alias/hl-m05-secrets, the task role hl-m05-accounts-api, a secret container for the blind-index key and a Parameter Store entry. Every resource is tagged Project=cea-lab, Lab=m05-secure-banking-api, Environment=learn and Owner.
Run the demos against KMS
cd ../..
export AWS_PROFILE=learn-sandbox AWS_REGION=us-east-1
dotnet run --project src/Harbourline.Security.Tools -- envelope --key alias/hl-m05-data
dotnet run --project src/Harbourline.Security.Tools -- sign --key alias/hl-m05-payment-signingThe output has the same four numbered lines, but the first line now says KMS: AWS KMS. Your SSO role must be allowed kms:GenerateDataKey, kms:Decrypt, kms:Sign, kms:Verify and kms:GetPublicKey. The key policies include the account-root statement, so an administrator permission set works. This part was not run in the build environment (no AWS account), so treat the AWS output as ⚠ VERIFY on your machine.
Look in CloudTrail
Wait a few minutes. Console → CloudTrail → Event history, filter Event source = kms.amazonaws.com. Open a GenerateDataKey event and a Decrypt event: the request parameters show encryptionContext with customer_id and field. Now the "which customer's field was decrypted?" question has an answer without any application log.
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=kms.amazonaws.com \
--max-results 10 --query "Events[].{Name:EventName,Time:EventTime}" --profile learn-sandboxTear down
cd infra/terraform
terraform destroy -var owner=<your-name>
aws resourcegroupstaggingapi get-resources --tag-filters Key=Project,Values=cea-lab --region us-east-1 --profile learn-sandboxKMS keys cannot be deleted immediately: destroy schedules them for deletion, and they sit in pending deletion for 7 days (the lab's default window), with no charge while pending (⚠ VERIFY). The secret is deleted immediately because the lab sets recovery_window_in_days = 0, a learning shortcut.
AWS Console instructions
- KMS keys: Console → Key Management Service → Customer managed keys. Open
alias/hl-m05-dataand check Key rotation (automatic rotation on), Key policy and Aliases. Open the signing key: key specECC_NIST_P256, usageSign and verify, and notice that there is no rotation option for asymmetric keys. - Pending deletion: after
terraform destroy, the keys show status Pending deletion with a date. You can Cancel key deletion within the window. - CloudTrail: Console → CloudTrail → Event history, filtered by event source
kms.amazonaws.com.
Console wording changes over time (⚠ VERIFY).
AWS CLI
# Describe the keys (replace nothing: aliases resolve)
aws kms describe-key --key-id alias/hl-m05-data --query "KeyMetadata.{Arn:Arn,State:KeyState,Spec:KeySpec,Rotation:KeyRotationStatus}" --profile learn-sandbox
aws kms get-key-rotation-status --key-id alias/hl-m05-data --profile learn-sandbox
# Download the signing public key (DER, Base64) for offline verification
aws kms get-public-key --key-id alias/hl-m05-payment-signing --query PublicKey --output text --profile learn-sandbox
# Read the key policy that Terraform created
aws kms get-key-policy --key-id alias/hl-m05-data --policy-name default --profile learn-sandbox
# Emergency brake (incident runbook): stop all use of the key. NEVER schedule deletion during an incident.
aws kms disable-key --key-id alias/hl-m05-data --profile learn-sandbox
aws kms enable-key --key-id alias/hl-m05-data --profile learn-sandboxInfrastructure as Code
The lab ships Terraform (infra/terraform). The data key with its policy:
resource "aws_kms_key" "data" {
description = "hl-m05 customer field encryption (Lab 5.3 and module project)"
enable_key_rotation = true
rotation_period_in_days = 365
deletion_window_in_days = var.key_deletion_window_days
policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Sid = "EnableIamPolicies"
Effect = "Allow"
Principal = { AWS = "arn:aws:iam::${local.account_id}:root" }
Action = "kms:*"
Resource = "*"
},
{
Sid = "AccountsApiFieldEncryptionOnly"
Effect = "Allow"
Principal = { AWS = local.api_role_arn }
Action = ["kms:GenerateDataKey", "kms:Decrypt"]
Resource = "*"
Condition = {
"ForAnyValue:StringEquals" = { "kms:EncryptionContextKeys" = ["customer_id"] }
}
}
]
})
}resource "aws_kms_key" "signing" {
description = "hl-m05 payment instruction signing (Lab 5.7)"
customer_master_key_spec = "ECC_NIST_P256"
key_usage = "SIGN_VERIFY"
deletion_window_in_days = var.key_deletion_window_days
# ... policy: root enables IAM; the API role may Sign, Verify and GetPublicKey
}Why two statements in the key policy? The root statement lets IAM policies in the account grant use of the key. Without it, only the key policy decides, and one mistake can leave a key that nobody can manage. The second statement restricts the API's role to the two operations it needs, and only when the request carries customer_id in the encryption context. The task role's own policy (iam.tf) repeats the same condition, so a change to one place does not silently widen access. Secrets Manager gets its own key (alias/hl-m05-secrets) because it sends its own encryption context and would otherwise fail the customer_id condition on the data key.
Complete code
The complete lab is in labs/m05-secure-banking-api/. The core of encryption and decryption:
var response = await _kms.GenerateDataKeyAsync(new GenerateDataKeyRequest
{
KeyId = _keyId,
KeySpec = DataKeySpec.AES_256,
EncryptionContext = EncryptionContext.ToSdkDictionary(encryptionContext),
}, cancellationToken).ConfigureAwait(false);
var dataKey = response.Plaintext?.ToArray()
?? throw new InvalidOperationException("KMS did not return a plaintext data key.");
Wipe(response.Plaintext);
try
{
var nonce = RandomNumberGenerator.GetBytes(NonceSize);
var tag = new byte[TagSize];
var ciphertext = new byte[plaintext.Length];
using (var aes = new AesGcm(dataKey, TagSize))
{
// The canonical context is passed as associated data: it is not encrypted,
// but any change to it makes decryption fail.
aes.Encrypt(nonce, plaintext, ciphertext, tag, EncryptionContext.ToCanonicalBytes(encryptionContext));
}
return new EnvelopeCiphertext(EnvelopeCiphertext.CurrentVersion, response.KeyId ?? _keyId,
response.CiphertextBlob?.ToArray() ?? throw new InvalidOperationException("KMS did not return an encrypted data key."),
nonce, tag, ciphertext);
}
finally
{
CryptographicOperations.ZeroMemory(dataKey);
}var response = await _kms.DecryptAsync(new DecryptRequest
{
// Pinning KeyId makes KMS refuse blobs wrapped by any other key.
KeyId = envelope.KeyId,
CiphertextBlob = new MemoryStream(envelope.EncryptedDataKey),
EncryptionContext = EncryptionContext.ToSdkDictionary(encryptionContext),
}, cancellationToken).ConfigureAwait(false);
var dataKey = response.Plaintext?.ToArray()
?? throw new InvalidOperationException("KMS did not return a plaintext data key.");
Wipe(response.Plaintext);
try
{
var plaintext = new byte[envelope.Ciphertext.Length];
using var aes = new AesGcm(dataKey, TagSize);
aes.Decrypt(envelope.Nonce, envelope.Ciphertext, envelope.Tag, plaintext, EncryptionContext.ToCanonicalBytes(encryptionContext));
return plaintext;
}
finally
{
CryptographicOperations.ZeroMemory(dataKey);
}public async Task<SignedPaymentInstruction> SignAsync(PaymentInstruction instruction, CancellationToken cancellationToken = default)
{
var digest = ComputeDigest(instruction);
var response = await _kms.SignAsync(new SignRequest
{
KeyId = _keyId,
Message = new MemoryStream(digest),
MessageType = MessageType.DIGEST,
SigningAlgorithm = SigningAlgorithmSpec.ECDSA_SHA_256,
}, cancellationToken).ConfigureAwait(false);
// ... wrap the signature with key id, algorithm and time
}
public static bool VerifyOffline(SignedPaymentInstruction signed, byte[] publicKeyDer)
{
// ... compute the digest and decode the signature
using var ecdsa = ECDsa.Create();
ecdsa.ImportSubjectPublicKeyInfo(publicKeyDer, out _);
return ecdsa.VerifyHash(digest, signature, DSASignatureFormat.Rfc3279DerSequence);
}Code explained line by line
GenerateDataKeyAsyncwithKeySpec = AES_256asks KMS for a 256-bit data key and returns it twice (PlaintextandCiphertextBlob). TheEncryptionContextis bound to the wrapped key at this moment.Wipe(response.Plaintext)zeroes the SDK's copy of the plaintext key straight away.dataKeyis the one working copy, zeroed in thefinallyblock. The comment in the source is honest: the garbage collector may already have copied the array, so this is best effort, not a guarantee.RandomNumberGenerator.GetBytes(12)makes a fresh 96-bit nonce. Safe here because every payload gets a new data key, so a nonce is never reused under the same key. If you cached a data key and encrypted many items with it, you would need a nonce-management strategy.aes.Encrypt(nonce, plaintext, ciphertext, tag, associatedData)is AES-GCM. The canonical context is passed as associated data: it is authenticated but not encrypted. A change to the context after encryption makes the tag check fail, so there are two layers: KMS checks the context when unwrapping, and GCM checks it again when decrypting.EncryptionContext.ToCanonicalBytessorts keys ordinally and length-prefixes each key and value, so{"a":"bc"}and{"ab":"c"}can never produce the same bytes.new EnvelopeCiphertext(version, keyId, wrappedKey, nonce, tag, ciphertext)is everything needed to decrypt later. The plaintext key is never stored.- In
DecryptAsync,KeyId = envelope.KeyIdpins the key. If an attacker edits the stored token to point at a key they control,Decryptfails instead of "helpfully" using whatever key wrapped the data. aes.Decrypt(...)throwsAuthenticationTagMismatchExceptionif the ciphertext or context was tampered with.- In signing,
MessageType.DIGESTtells KMS that the 32 bytes are already a hash.ECDSA_SHA_256must match the key's spec (ECC_NIST_P256). ImportSubjectPublicKeyInforeads the DER public key fromGetPublicKey.Rfc3279DerSequencetells .NET the signature is DER-encoded, as KMS returns it.
Security considerations
⚠ Learning shortcut — not for production
LocalDevelopmentKms is an in-process fake: no HSM, no key policy, no IAM, no CloudTrail, keys vanish on restart. The hand-written envelope format shows the mechanics, but production code should use the AWS Encryption SDK for .NET (key commitment, a standard message format, keyrings, data-key caching) or the AWS-provided database encryption libraries, which cryptographers have reviewed. A hand-rolled format is a common audit finding. The lab also calls KMS once per field; at scale you cache data keys within limits you can justify, which the Encryption SDK supports. The API refuses Crypto:Mode=Local outside Development and Testing, which is a control worth keeping.
- Never put secrets or personal data in the encryption context. It is visible in plain text in CloudTrail and in KMS grants and key conditions.
- Least privilege on keys. Separate keys per purpose (data, signing, secrets). Separate who administers a key from who uses it.
- Key policy mistakes are costly. Keep the root-enables-IAM statement unless you have a specific, reviewed reason.
- Rotation. Automatic rotation applies to symmetric keys (
enable_key_rotation) and keeps older key material so old data stays readable. Asymmetric keys do not rotate automatically; rotating a signing key means creating a new key and publishing the new public key. A rotation is not a re-encryption of stored data (⚠ VERIFY rotation period limits for your key type in the KMS documentation). - Disable, never delete, during an incident. Disabling stops all use and is reversible; deletion is not (after the waiting period).
- Signing and non-repudiation. A KMS signature proves the signing service approved those exact bytes at a time the log records. It does not by itself prove that a human intended the payment; that depends on how the upstream approval was authenticated. This lab does not make a system PCI DSS or UK GDPR compliant, and the crypto design needs review by security and compliance specialists.
- FIPS and algorithms. Stick to standard algorithms (AES-GCM, ECDSA P-256, SHA-256). Do not invent formats.
Banking use case
The secure Accounts API stores a customer's date of birth and IBAN as enc:v1: tokens bound to customer_id and field. Support staff see masked views and never trigger a decrypt. A KYC officer's "reveal" request causes a KMS Decrypt with the customer id in the context, so a security analyst can list exactly which customers' identity fields were revealed, by whom, in a given hour, straight from CloudTrail. The payments service signs each approved payment instruction with the KMS signing key and passes the signed instruction and the public key's identifier to the settlement system, which verifies it offline before releasing funds. Years later an auditor can verify the same signature with the public key.
Common mistakes
- Keeping the plaintext data key alongside the ciphertext, or logging it.
- Skipping the encryption context, which loses the binding and the audit trail.
- Putting personal data in the context.
- Reusing one data key and a random nonce for millions of items, which risks nonce collisions.
- Verifying a KMS signature with .NET's default signature format, and getting false for a good signature.
- Signing objects instead of canonical bytes, and failing verification across systems.
- Scheduling a key for deletion to "stop" an incident. Disable it instead.
- Granting
kms:*on*to the application role. - Forgetting that Secrets Manager sends its own encryption context and breaking it with a restrictive condition on a shared key.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
InvalidCiphertextException on decrypt | Wrong customer id or field (encryption context mismatch), or the local KMS restarted | Use the same context as at encryption; local data does not survive restarts |
AccessDeniedException from KMS | The SSO role or key policy lacks the action, or the customer_id condition is not met | Check aws kms get-key-policy --key-id alias/hl-m05-data --policy-name default and your role's permissions |
NotFoundException: Alias ... is not found | Terraform was not applied, or you are in another Region | aws kms list-aliases --region us-east-1 |
DisabledException | The key is disabled | aws kms enable-key (and find out who disabled it) |
IncorrectKeyException | The stored key id does not match the key you pinned | Expected for tampered or swapped data |
AuthenticationTagMismatchException | The ciphertext or context was changed | Treat as tampering; do not retry blindly |
| A good signature verifies as false offline | .NET default signature format | Use DSASignatureFormat.Rfc3279DerSequence |
Crypto:Mode=Local is only allowed... | Running Local mode outside Development/Testing | Intended: the API fails closed |
terraform apply fails on the backend | backend.hcl missing or bucket name wrong | Copy backend.hcl.example and edit it, or use init -backend=false |
| Key still billed after destroy | It is pending deletion; or a key from another run exists | Check the key state; list by tag |
Cost and cleanup
Offline parts: free. AWS part: credits, a few cents if destroyed the same day (three KMS keys about 1 USD per key-month prorated hourly, one secret about 0.40 USD per month, small API-call charges; ⚠ VERIFY prices).
cd labs/m05-secure-banking-api/infra/terraform
terraform destroy -var owner=<your-name>
# Nothing tagged for the labs should remain (KMS keys show as pending deletion for 7 days):
aws resourcegroupstaggingapi get-resources --tag-filters Key=Project,Values=cea-lab --region us-east-1 --profile learn-sandbox
# Local build output
find labs/m05-secure-banking-api -type d \( -name bin -o -name obj -o -name TestResults \) -prune -exec rm -rf {} +Exercises
- 🟢 Guided: run the tests and both demos offline. Then perform the "break it" step in Part 2, and write down which test fails and why.
- 🟡 Challenge: add a
PaymentInstructionfieldReferenceto the canonical JSON. Predict which existing tests must change, update them deliberately, and write a new test proving that two instructions that differ only inReferencehave different digests. Then explain why adding a field to a signed format needs a version strategy. - 🔴 Live problem: a ticket says: "After we rotated the data key last month, a batch job that re-reads old customer records fails with
InvalidCiphertextExceptionfor about 3 per cent of rows. New records are fine." Decide which of these causes fit the evidence and which do not: (a) rotation lost the old key material; (b) those rows were written with a different encryption context (an earlier code version used onlycustomer_id); (c) the job's role lost permission; (d) a different Region. State what you would check in CloudTrail, what a safe migration looks like, and how theenc:v1:version prefix and the envelope version byte help.
Assignment
Write a key-management design note (one to two pages) for the Accounts API in your portfolio repository: the keys (data, signing, secrets), who administers and who uses each, rotation policy and why asymmetric keys differ, the encryption-context standard (which keys, never what values), what CloudTrail alarms you would create (a spike in Decrypt from one principal, any ScheduleKeyDeletion or DisableKey), and a rollback plan if a key is disabled by mistake. Include the policy statements you would change before production, referencing the learning shortcuts above.
Solutions
Removing field from the context makes Ciphertext_copied_to_another_field_does_not_decrypt fail: the IBAN ciphertext now decrypts as a date of birth, which is exactly the swap attack the field binding exists to stop. Putting a date of birth into the context still "works" in the demo, but KMS records the context in CloudTrail, so personal data would now sit in the audit log in plain text. Restore {customer_id, field}.
Add Reference to the record and write it in ToCanonicalJson() at a fixed position. All tests that assert the exact canonical string or the digest of a sample instruction must be updated (the stability test and any fixture). New test: two instructions identical except for Reference have different digests, and a signature made over one does not verify against the other. Adding a field changes the bytes of every instruction, so previously signed instructions would no longer verify unless the verifier knows which format they were signed under. The fix is a version marker in the signed bytes (for example a schema field or a prefix), and a verifier that picks the canonicalisation by version.
(a) does not fit: automatic rotation keeps old key material for decrypting old data, and only 3 per cent of rows fail. (c) does not fit: a permission loss would fail every row, not a subset. (d) does not fit for the same reason. (b) fits: a subset of rows written by an earlier code version with a different context. Check CloudTrail for the failing Decrypt calls and compare the encryptionContext in those events with a successful one, and find the code or deployment date at which the context changed. Safe migration: decrypt with the old context, re-encrypt under the standard context, write back in batches with audit logging, and keep both code paths until done. The enc:v1: prefix and the envelope version byte let you add enc:v2: with the new context standard without ambiguity.
Knowledge check
Answer: KMS Encrypt is limited to small payloads (4 KB), and calling KMS for every byte of a large object would be slow and costly. A data key encrypts the payload locally, and KMS protects only the small data key. The master key never leaves KMS, and each unwrap is an authorised, logged call.
Answer: A set of non-secret key-value pairs bound to the ciphertext; KMS requires the same context to decrypt, and it appears in CloudTrail. Never put secrets or personal data in it. Identifiers such as customer_id are appropriate.
Answer: Decryption fails with InvalidCiphertextException, because the context for B (customer_id=B) differs from the one used at encryption. The failed attempt is also visible in CloudTrail.
Answer: The message is hashed locally, so the payment details never leave the application and the message-size limit does not apply. KMS signs the 32-byte digest with MessageType = DIGEST.
Answer: The signature format. KMS returns DER-encoded ECDSA signatures; .NET defaults to fixed-size P1363. Pass DSASignatureFormat.Rfc3279DerSequence.
Interview questions
- "Explain envelope encryption and why banks use it." A one-time data key encrypts the data; KMS wraps the data key under a master key that never leaves KMS. Large data, strong access control, and every unwrap is logged.
- "How do you prevent someone with database access from moving encrypted values between customers?" Bind each ciphertext to the customer and field through the encryption context and AES-GCM associated data. A moved value fails to decrypt.
- "When would you use an asymmetric KMS key?" For signing where verifiers need no AWS access: payment instructions, documents, tokens. The private key stays in KMS; the public key is distributed.
- "Is it acceptable to ship your own envelope format?" Better to use the AWS Encryption SDK. A custom format is acceptable for learning, but production formats need versioning, key commitment and review.
- "What do you do if a key may be misused during an incident?" Disable it (reversible), with approval, never schedule deletion, then investigate with CloudTrail grouped by encryption context.
Certification practice
An application encrypts customer fields with data keys from KMS. A security architect wants a log that shows which customer's data was decrypted and by whom, without adding application-side logging. Which approach BEST achieves this?
A. Encrypt with a fixed key and log decrypts in the application.
B. Use GenerateDataKey and Decrypt with an encryption context that includes the customer id, and review CloudTrail events.
C. Store the plaintext data key beside the ciphertext.
D. Use SSE-S3 for the database.
Answer: B. KMS records the encryption context in CloudTrail, giving a per-customer audit trail. A depends on the application. C defeats encryption. D gives no per-customer audit.
A developer must encrypt a 50 MB document before storing it. Which is the CORRECT approach with AWS KMS?
A. Call KMS Encrypt with the document.
B. Call GenerateDataKey, encrypt the document locally with the plaintext data key, store the wrapped key with the ciphertext, and discard the plaintext key.
C. Put the document in the encryption context.
D. Create one KMS key per document byte.
Answer: B. KMS Encrypt is limited to small payloads. Envelope encryption handles any size. C is wrong because the context is for small non-secret labels. D is absurd.
A payments system must let a downstream partner verify that an instruction came from the bank, without giving the partner AWS credentials. Which design works?
A. Sign with a symmetric KMS key and share the key.
B. Sign with an asymmetric KMS key (SIGN_VERIFY) and give the partner the public key.
C. Email the payment instruction with a checksum.
D. Share the IAM role's access keys.
Answer: B. The private key never leaves KMS and the public key verifies offline. A shares a secret. C has no authenticity. D breaks least privilege.
Completion checklist
- I ran the tests and saw
total: 72, succeeded: 71, skipped: 1 - I ran
envelope --localandsign --localand read every line of output - I broke the encryption context on purpose and saw the test fail
- I can explain why
Rfc3279DerSequenceis needed - If I deployed: I ran
terraform destroy, confirmed the keys are pending deletion, and saw no other tagged resources - I wrote the key-management design note
Key takeaways
- Envelope encryption: a data key does the work, KMS protects the data key, and the plaintext key is never stored.
- The encryption context binds ciphertext to a purpose and doubles as an audit label. It is visible, so it must be non-secret.
- Sign canonical bytes with an asymmetric KMS key, send only the digest, and verify with the public key. Mind the DER format.
- Fake KMS for speed and cost in the lab, real KMS for truth. Use the AWS Encryption SDK in production.
- Disable a key to stop a leak. Schedule deletion only deliberately, and expect a waiting period.
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.
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.
Audit logging and evidence collection
Understand what auditors actually ask a bank for, and build evidence on AWS that answers them: AWS Artifact reports, CloudTrail and AWS Config as configuration and activity evidence, application audit events, and a repeatable .NET evidence collector that packages, hashes and locks what it gathers.