AWS KMS: keys, key policies and envelope encryption
Create and govern customer managed KMS keys for a bank: key policies, grants, encryption context, envelope encryption from .NET, rotation, multi-Region keys, quotas, pricing and safe deletion.
Assumes: .NET 10 LTS · AWS SDK for .NET v4 (AWSSDK.KeyManagementService 4.1.1.1) · AWS CLI v2 · Region us-east-1. Verified against official sources on 2026-11-18.
Learning objectives
By the end of this lesson you can:
- Explain the three kinds of KMS key (AWS owned, AWS managed, customer managed) and the key specs (symmetric, asymmetric RSA/ECC, HMAC), and choose one for a banking workload.
- Write a key policy that keeps the key manageable, separates key administrators from key users, and limits use with encryption context and
kms:ViaServiceconditions. - Explain grants and when AWS services create them for you.
- Implement envelope encryption in C#:
GenerateDataKey, local AES-GCM, store the wrapped key,Decryptwith the same context. - Configure automatic and on-demand rotation, explain what rotation does and does not change, and plan multi-Region keys for disaster recovery.
- Estimate KMS cost and quota headroom, and schedule a key for deletion safely.
Prerequisites
- IAM in depth and Policy evaluation logic — key policies are resource-based policies with one special rule
- Tools: AWS CLI v2 with the
learn-sandboxprofile, .NET 10 SDK (or Docker), optionally Terraform 1.10+ - Lab repository
labs/m05-secure-banking-apifor the offline version
Why this matters in banking
Three conversations a cloud engineer at a bank has every quarter:
- The auditor: "Show me who decrypted customer identity data last month, and prove that the database administrators could not." With KMS, every decrypt is an IAM-authorised API call logged in CloudTrail with the encryption context you chose, for example
customer_id=CUS-00012345. A DBA with full database access but nokms:Decryptsees only ciphertext. - The regulator's operational-resilience review: "If your primary Region is lost, can you still read your backups?" A key that exists only in
eu-west-2makes encrypted snapshots copied toeu-west-1useless unless you planned keys for the recovery Region. - The incident: "A developer scheduled the payments key for deletion by mistake." Deleting a KMS key destroys every piece of data encrypted under it, permanently. The waiting period, CloudTrail alerting and key-policy separation of duties are the only things that save you.
KMS is the vault behind nearly every "encrypted at rest" tick box on AWS. Getting key policies and deletion controls right is a core security-engineer skill and a heavily weighted SCS-C03 topic.
The idea in plain language
AWS Key Management Service (KMS) stores cryptographic keys inside hardware security modules (HSMs) that AWS operates, and performs operations with them on your behalf. The important property: the key material never leaves KMS in plain text. You send data (up to 4 KB) or a request for a new data key; KMS does the cryptography and returns the result.
Because KMS can only encrypt 4 KB at a time, and calling it for every byte would be slow, real systems use envelope encryption:
- Ask KMS for a fresh data key. KMS returns it twice: in plain text, and encrypted ("wrapped") under your KMS key.
- Encrypt your data locally with the plain-text data key (AES-256-GCM).
- Throw away the plain-text data key. Store the wrapped data key next to the ciphertext.
- To decrypt, send the wrapped data key to KMS, get the plain-text data key back, decrypt locally.
Analogy: a bank's safe-deposit room. Each customer's box has its own small key (the data key). Those small keys are kept in an envelope sealed by the vault master key that never leaves the vault (the KMS key). To open a box, a clerk takes the sealed envelope to the vault, the vault checks the clerk's authority and writes it in the log book (CloudTrail), and returns the small key for one use.
| Term | Plain meaning |
|---|---|
| KMS key (formerly "CMK") | The logical key in KMS: ID, ARN, policy, state, and one or more versions of key material |
| Key material | The secret bits inside the HSM. Rotation adds new material; the key ID stays the same |
| Data key | A key KMS generates for you to encrypt data outside KMS |
| Encryption context | Non-secret key/value pairs bound to a ciphertext; decrypt fails unless the same pairs are supplied; logged in CloudTrail |
| Key policy | The resource-based policy on a KMS key — the primary access control |
| Grant | A delegated, revocable permission to use a key, usually created by AWS services |
| Alias | A friendly name such as alias/hl-m05-data that points to a key and can be repointed |
What problem the AWS service solves
KMS solves key storage, key access control and key audit for you, and integrates with more than a hundred AWS services (S3, EBS, RDS, DynamoDB, Secrets Manager, Lambda environment variables, CloudTrail, Backup and many others).
Key ownership types
| Type | Who creates and controls it | Visible in your account | Key policy you control | Cost | Banking use |
|---|---|---|---|---|---|
| AWS owned key | The AWS service, shared across accounts | No | No | Free | Default encryption where you need no audit trail or control (e.g. SSE-S3 is a separate S3-managed mechanism; DynamoDB's default is an AWS owned key) |
AWS managed key (aws/s3, aws/rds…) | AWS, one per service per account | Yes | No (read only) | No monthly fee; requests charged | Quick wins, but you cannot restrict who uses it, share it cross-account or delete it |
| Customer managed key | You | Yes | Yes | USD 1 per key per month, prorated hourly | The default for regulated data: your policy, your rotation, your deletion decision, cross-account use |
Key specs
| Key spec | Usage | Rotation | Typical use |
|---|---|---|---|
SYMMETRIC_DEFAULT (AES-256-GCM inside KMS) | Encrypt/decrypt, data keys | Automatic and on-demand | Almost everything: S3, RDS, field encryption |
RSA_2048/3072/4096 | Encrypt/decrypt or sign/verify | Manual only | Signing documents; encrypting for parties outside AWS |
ECC_NIST_P256/P384/P521, ECC_SECG_P256K1 | Sign/verify (and key agreement) | Manual only | Payment instruction signing (Lab 5.7) |
HMAC_224/256/384/512 | GenerateMac/VerifyMac | Manual only | Tokens, blind indexes, message authentication |
| ML-DSA (post-quantum signatures) | Sign/verify | Manual only | Early post-quantum pilots ⚠ VERIFY Region availability |
Limits and sharp edges (checked 2026-11-18)
- 4 KB maximum plaintext for
Encrypt; use envelope encryption for anything larger. - Symmetric cryptographic request quota is shared per account and Region: 100,000 requests/second in us-east-1, us-west-2 and eu-west-1; 20,000 in several Regions including eu-west-2 (London); 10,000 elsewhere. RSA and ECC operations have separate 1,000/second quotas. Exceeding them returns
ThrottlingException. Calls AWS services make on your behalf (S3 SSE-KMS uploads, for example) count too. - Deletion is only possible after a waiting period of 7 to 30 days (default 30). After deletion, data encrypted under the key is unrecoverable. Keys pending deletion are not charged.
- Rotation of symmetric keys can be automatic (default every 365 days; configurable period) and on-demand (up to 25 times per key). Asymmetric, HMAC and custom-key-store keys need manual rotation (new key + alias switch).
- Keys are regional. Multi-Region keys are related keys with the same key ID and material in several Regions; each replica is billed as a key.
Microsoft / Azure comparison
| You know (Microsoft/Azure) | AWS equivalent | What's different |
|---|---|---|
| Azure Key Vault (keys) | AWS KMS | KMS is keys only; secrets live in Secrets Manager. KMS keys cannot be exported (except imported material you already hold) |
| Key Vault Premium / Managed HSM | KMS (FIPS-validated HSMs) / CloudHSM key store | KMS already uses HSMs; single-tenant HSMs are CloudHSM — see When banks need CloudHSM |
| Key Vault access policies / RBAC data-plane roles | Key policy + IAM policies + grants | The key policy must allow IAM to be used at all (the account-root statement) |
| Customer-managed keys for Storage/SQL (BYOK) | SSE-KMS, RDS/Aurora with a customer managed key | Same idea; in AWS you choose the key at resource creation for many services |
| Key Vault soft delete + purge protection | KMS deletion waiting period (7–30 days) + CancelKeyDeletion | There is no "purge protection" switch; protect deletion with key policy, SCP and alerts |
| Key Vault key rotation policy | Automatic rotation (period in days) and on-demand rotation | KMS keeps the same key ID and all old material; no re-encryption is needed |
CryptographyClient.WrapKey / Always Encrypted column master keys | GenerateDataKey / envelope encryption | AWS recommends the AWS Encryption SDK rather than raw calls for application encryption |
Architecture
The security boundary view: who can do what with the key.
Separation of duties is built in: administrators can manage the key but cannot use it to decrypt; users can decrypt but cannot change the policy or delete the key.
Step-by-step implementation
1. Decide the key layout
One key per data domain and environment is a good default at a bank: hl-prod-customer-pii, hl-prod-payments, hl-prod-logs. It keeps blast radius small, lets you hand different keys to different teams, and makes key-level audit queries meaningful. Very many keys cost money (USD 1 each per month) and add policy sprawl; one key for everything means anyone who can decrypt logs can also decrypt PII.
2. Write the key policy
Every key policy needs three parts:
- The account-root statement (
"Principal": {"AWS": "arn:aws:iam::<account>:root"}withkms:*). This does not give the root user special access; it enables IAM policies in the account to grant use of the key. Without it, only principals named in the key policy can use or manage the key, and if you lock yourself out you need AWS Support. - Key administrators: manage but not use.
- Key users: use but not manage, with conditions:
kms:EncryptionContextKeysorkms:EncryptionContext:customer_idto force callers to bind ciphertext to a customer;kms:ViaService(for examplerds.us-east-1.amazonaws.com) to allow use only through a service;kms:CallerAccountfor cross-account users.
3. Create the key and alias
Create the key with the policy, enable rotation, set a short deletion window in labs (7 days), tag it, and point an alias at it. Applications refer to the alias or the key ARN. Aliases let you switch to a new key during manual rotation without redeploying.
4. Encrypt with envelope encryption from .NET
Use GenerateDataKey with an encryption context, encrypt locally with AES-GCM, store the wrapped key. The complete code is below. For production code, use the AWS Encryption SDK for .NET, which implements this with a standard message format, key commitment and data-key caching.
5. Prove the controls
- Decrypt with the wrong encryption context →
InvalidCiphertextException. - Call from a role not in the key policy (and without IAM permission) →
AccessDeniedException. - Find both attempts in CloudTrail (event source
kms.amazonaws.com).
6. Plan rotation, Regions and deletion
Turn on automatic rotation (or justify why not), decide whether disaster recovery needs multi-Region keys, and put deletion behind separation of duties, an SCP and an alert.
Grants in one paragraph
A grant is a small, programmatic permission attached to a key: "principal X may perform operations Y, optionally only with encryption context Z, until the grant is retired". AWS services use grants so they can use your key on your behalf for as long as a resource exists — for example, when you create an encrypted EBS volume, EC2 creates a grant so the host can decrypt the volume's data key. You rarely create grants yourself, but you must allow kms:CreateGrant (usually with kms:GrantIsForAWSResource = true) for roles that create encrypted resources, and you should know that ListGrants is how you see who else can use a key. Grants are eventually consistent; a newly created grant can be used immediately through its grant token.
Multi-Region keys
A multi-Region key is a primary key plus replica keys in other Regions, sharing the same key ID (prefix mrk-) and key material. Data encrypted in eu-west-2 can be decrypted in eu-west-1 without a cross-Region call — useful for DynamoDB global tables, cross-Region backups and active-active payment services. Each replica has its own key policy and is billed as a separate key. Use them deliberately: regulators may ask why the same key material exists outside a jurisdiction. For most workloads, separate single-Region keys and re-encryption on copy (which AWS Backup and snapshot copy do for you) are simpler.
AWS Console instructions
- Console → Key Management Service → Customer managed keys → Create key. Choose Symmetric, Encrypt and decrypt. Under Advanced options, keep KMS as the key material origin and Single-Region key.
- Alias:
hl-m05-data. Description: "Lab 5.3 field encryption". Tags:Project=cea-lab,Lab=m05-kms,Environment=learn,Owner=<you>. - Key administrators: choose your SSO role (it appears as
AWSReservedSSO_...). Untick Allow key administrators to delete this key if you want to practise separation of duties; you will then delete it with a different role. - Key users: choose the same role for the lab. In production this is the workload role.
- Review the generated key policy JSON. Find the account-root statement, the administrators statement and the users statement, and the separate statement for grants (
kms:CreateGrantwithkms:GrantIsForAWSResource). - Open the key → Key rotation tab → Automatically rotate this KMS key every year → set the rotation period → Save.
- To delete: Key actions → Schedule key deletion, set 7 days, confirm. To undo: Key actions → Cancel key deletion (the key returns in the Disabled state; enable it again).
AWS CLI
export AWS_PROFILE=learn-sandbox AWS_REGION=us-east-1
ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
ME=$(aws sts get-caller-identity --query Arn --output text) # assumed-role session ARN
ROLE_ARN=$(aws iam get-role --role-name "$(echo "$ME" | cut -d/ -f2)" --query Role.Arn --output text)
# Key policy: enable IAM, my SSO role administers and uses the key (lab only).
cat > key-policy.json <<EOF
{
"Version": "2012-10-17",
"Statement": [
{ "Sid": "EnableIamPolicies", "Effect": "Allow",
"Principal": { "AWS": "arn:aws:iam::${ACCOUNT}:root" }, "Action": "kms:*", "Resource": "*" },
{ "Sid": "LabUserWithCustomerContextOnly", "Effect": "Allow",
"Principal": { "AWS": "${ROLE_ARN}" },
"Action": ["kms:GenerateDataKey", "kms:Decrypt", "kms:Encrypt"], "Resource": "*",
"Condition": { "ForAnyValue:StringEquals": { "kms:EncryptionContextKeys": "customer_id" } } }
]
}
EOF
# Create the key (symmetric is the default) with tags, then an alias.
KEY_ID=$(aws kms create-key --description "hl-m05 lab field encryption" \
--policy file://key-policy.json \
--tags TagKey=Project,TagValue=cea-lab TagKey=Lab,TagValue=m05-kms TagKey=Environment,TagValue=learn TagKey=Owner,TagValue=alex \
--query KeyMetadata.KeyId --output text)
aws kms create-alias --alias-name alias/hl-m05-data --target-key-id "$KEY_ID"
# Rotation every 180 days instead of the default 365.
aws kms enable-key-rotation --key-id "$KEY_ID" --rotation-period-in-days 180
aws kms get-key-rotation-status --key-id "$KEY_ID"
# Envelope encryption by hand: get a data key bound to a customer.
aws kms generate-data-key --key-id alias/hl-m05-data --key-spec AES_256 \
--encryption-context customer_id=CUS-00012345,field=iban \
--query '{wrapped: CiphertextBlob}' --output json > datakey.json
# Decrypt the wrapped key with the same context (works) ...
aws kms decrypt --key-id alias/hl-m05-data \
--ciphertext-blob fileb://<(jq -r .wrapped datakey.json | base64 -d) \
--encryption-context customer_id=CUS-00012345,field=iban --query KeyId
# ... and with a different customer (fails with InvalidCiphertextException).
aws kms decrypt --key-id alias/hl-m05-data \
--ciphertext-blob fileb://<(jq -r .wrapped datakey.json | base64 -d) \
--encryption-context customer_id=CUS-00099999,field=iban || echo "refused, as expected"
# Who else can use this key?
aws kms list-grants --key-id "$KEY_ID"
# Schedule deletion with the minimum waiting period (no charge while pending).
aws kms schedule-key-deletion --key-id "$KEY_ID" --pending-window-in-days 7--rotation-period-in-days accepts values from 90 to 2,560 days. The fileb://<(...) form needs Git Bash or Linux; on PowerShell, write the decoded blob to a file first.
Infrastructure as Code
using Amazon.CDK;
using Amazon.CDK.AWS.IAM;
using Amazon.CDK.AWS.KMS;
using Constructs;
namespace Harbourline.Security.Infra;
public sealed class KmsStack : Stack
{
public KmsStack(Construct scope, string id, IStackProps? props = null) : base(scope, id, props)
{
var apiRole = new Role(this, "AccountsApiRole", new RoleProps
{
RoleName = "hl-m05-cdk-accounts-api",
AssumedBy = new ServicePrincipal("ecs-tasks.amazonaws.com"),
});
var key = new Key(this, "DataKey", new KeyProps
{
Alias = "alias/hl-m05-cdk-data",
Description = "Customer field encryption",
EnableKeyRotation = true,
RotationPeriod = Duration.Days(365),
PendingWindow = Duration.Days(7), // lab: shortest waiting period
RemovalPolicy = RemovalPolicy.DESTROY, // lab only; production: RETAIN
// CDK adds the account-root statement by default, which enables IAM policies.
});
// Key user, constrained to calls that carry a customer_id encryption context.
key.AddToResourcePolicy(new PolicyStatement(new PolicyStatementProps
{
Sid = "AccountsApiFieldEncryptionOnly",
Principals = [new ArnPrincipal(apiRole.RoleArn)],
Actions = ["kms:GenerateDataKey", "kms:Decrypt"],
Resources = ["*"],
Conditions = new Dictionary<string, object>
{
["ForAnyValue:StringEquals"] = new Dictionary<string, object> { ["kms:EncryptionContextKeys"] = new[] { "customer_id" } },
},
}));
Amazon.CDK.Tags.Of(this).Add("Project", "cea-lab");
Amazon.CDK.Tags.Of(this).Add("Lab", "m05-kms");
Amazon.CDK.Tags.Of(this).Add("Environment", "learn");
_ = new CfnOutput(this, "KeyArn", new CfnOutputProps { Value = key.KeyArn });
}
}The full lab Terraform in labs/m05-secure-banking-api/infra/terraform adds the ECC signing key, a separate Secrets Manager key, and the least-privilege task role.
Complete code
A self-contained console app: envelope encryption of one customer field with KMS, the wrong-context check and a tamper check. It talks to real KMS; the same logic runs offline in the lab with LocalDevelopmentKms (hl-crypto envelope --local).
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
<RootNamespace>Harbourline.Security.KmsEnvelope</RootNamespace>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="AWSSDK.KeyManagementService" Version="4.1.1.1" />
<PackageReference Include="AWSSDK.SSO" Version="4.1.0.2" />
<PackageReference Include="AWSSDK.SSOOIDC" Version="4.1.0.2" />
</ItemGroup>
</Project>using System.Security.Cryptography;
using System.Text;
using Amazon.KeyManagementService;
using Amazon.KeyManagementService.Model;
// Run: $env:AWS_PROFILE="learn-sandbox"; aws sso login; dotnet run -- alias/hl-m05-data
var keyId = args.Length > 0 ? args[0] : "alias/hl-m05-data";
using var kms = new AmazonKeyManagementServiceClient();
var context = new Dictionary<string, string> { ["customer_id"] = "CUS-00012345", ["field"] = "iban" };
var stored = await Envelope.EncryptAsync(kms, keyId, Encoding.UTF8.GetBytes("GB82WEST12345698765432"), context);
Console.WriteLine($"Stored record: key={stored.KeyArn}, wrappedKey={stored.WrappedKey.Length} bytes, ciphertext={Convert.ToHexString(stored.Ciphertext)}");
var plaintext = await Envelope.DecryptAsync(kms, stored, context);
Console.WriteLine($"Decrypted with matching context: {Encoding.UTF8.GetString(plaintext)}");
try
{
var otherCustomer = new Dictionary<string, string>(context) { ["customer_id"] = "CUS-00099999" };
await Envelope.DecryptAsync(kms, stored, otherCustomer);
Console.WriteLine("UNEXPECTED: decrypt succeeded with another customer's context");
}
catch (InvalidCiphertextException)
{
Console.WriteLine("Decrypt as another customer: refused by KMS (InvalidCiphertextException)");
}
var tampered = stored with { Ciphertext = [.. stored.Ciphertext.Select((b, i) => i == 0 ? (byte)(b ^ 1) : b)] };
try
{
await Envelope.DecryptAsync(kms, tampered, context);
}
catch (AuthenticationTagMismatchException)
{
Console.WriteLine("Tampered ciphertext: rejected by AES-GCM authentication");
}
/// <summary>What you store in the database: everything except the plaintext data key.</summary>
public sealed record EnvelopeRecord(string KeyArn, byte[] WrappedKey, byte[] Nonce, byte[] Tag, byte[] Ciphertext);
public static class Envelope
{
public static async Task<EnvelopeRecord> EncryptAsync(
IAmazonKeyManagementService kms, string keyId, byte[] plaintext, Dictionary<string, string> context)
{
var dataKey = await kms.GenerateDataKeyAsync(new GenerateDataKeyRequest
{
KeyId = keyId,
KeySpec = DataKeySpec.AES_256,
EncryptionContext = context,
});
var key = dataKey.Plaintext.ToArray();
try
{
var nonce = RandomNumberGenerator.GetBytes(AesGcm.NonceByteSizes.MaxSize); // 12 bytes
var tag = new byte[AesGcm.TagByteSizes.MaxSize]; // 16 bytes
var ciphertext = new byte[plaintext.Length];
using var aes = new AesGcm(key, tag.Length);
aes.Encrypt(nonce, plaintext, ciphertext, tag, AssociatedData(context));
return new EnvelopeRecord(dataKey.KeyId, dataKey.CiphertextBlob.ToArray(), nonce, tag, ciphertext);
}
finally
{
CryptographicOperations.ZeroMemory(key);
if (dataKey.Plaintext.TryGetBuffer(out var buffer))
{
CryptographicOperations.ZeroMemory(buffer.AsSpan());
}
}
}
public static async Task<byte[]> DecryptAsync(
IAmazonKeyManagementService kms, EnvelopeRecord record, Dictionary<string, string> context)
{
var response = await kms.DecryptAsync(new DecryptRequest
{
KeyId = record.KeyArn, // pin the key: refuse blobs from any other key
CiphertextBlob = new MemoryStream(record.WrappedKey),
EncryptionContext = context,
});
var key = response.Plaintext.ToArray();
try
{
var plaintext = new byte[record.Ciphertext.Length];
using var aes = new AesGcm(key, record.Tag.Length);
aes.Decrypt(record.Nonce, record.Ciphertext, record.Tag, plaintext, AssociatedData(context));
return plaintext;
}
finally
{
CryptographicOperations.ZeroMemory(key);
}
}
// Bind the same context to the local ciphertext, sorted so the bytes are stable.
private static byte[] AssociatedData(Dictionary<string, string> context) =>
Encoding.UTF8.GetBytes(string.Join(';', context.OrderBy(p => p.Key, StringComparer.Ordinal).Select(p => $"{p.Key}={p.Value}")));
}Expected output (key ARN shortened):
Stored record: key=arn:aws:kms:us-east-1:111122223333:key/..., wrappedKey=184 bytes, ciphertext=6F1C...
Decrypted with matching context: GB82WEST12345698765432
Decrypt as another customer: refused by KMS (InvalidCiphertextException)
Tampered ciphertext: rejected by AES-GCM authenticationCode explained line by line
AWSSDK.KeyManagementService4.1.1.1 is the SDK v4 KMS client;AWSSDK.SSO/SSOOIDClet the default credential chain use your Identity Center profile.new AmazonKeyManagementServiceClient()— credentials and Region come from the environment (AWS_PROFILE, profile Region). In ASP.NET Core register it withAddAWSService<IAmazonKeyManagementService>()and inject the interface.context— two identifiers, no personal data. The context appears in plain text in CloudTrail, so never put a name, date of birth or IBAN in it.GenerateDataKeyAsyncwithKeySpec = AES_256returnsPlaintext(32 bytes) andCiphertextBlob(the wrapped key, which also embeds a reference to the KMS key).KeyIdin the response is always the full key ARN, even if you passed an alias — store the ARN, not the alias.AesGcm.NonceByteSizes.MaxSizeis 12 bytes, the standard GCM nonce. Because every record gets a new data key, nonce reuse under one key is impossible here.aes.Encrypt(..., AssociatedData(context))— the context is also used as AES-GCM associated data, so the local ciphertext is bound to the same customer and field as the wrapped key.ZeroMemoryinfinally— best-effort removal of the plaintext key from memory. .NET may have copied it; this reduces, not eliminates, exposure.DecryptRequest.KeyId = record.KeyArn— optional for symmetric keys, but pinning it means KMS refuses a wrapped key from any other key. This defends against an attacker who can write to your table and substitutes a blob wrapped under a key they control.EncryptionContext = contexton decrypt — must match exactly (keys and values, case-sensitive). Any difference givesInvalidCiphertextException, deliberately indistinguishable from a corrupted blob.- The tamper check flips one bit;
AesGcm.DecryptthrowsAuthenticationTagMismatchException(aCryptographicException). Never catch and ignore it. EnvelopeRecord— a real system adds a format version and serialises compactly; seeEnvelopeCiphertextin the lab.
Security considerations
⚠ Learning shortcut — not for production
The lab key policy makes your own SSO role both administrator and user of the key, and the code above hand-rolls an envelope format. In production, administrators and users are different roles (separation of duties), and application encryption uses the AWS Encryption SDK for .NET (AWS.Cryptography.EncryptionSDK; 5.0.0 on nuget.org at the time of writing — ⚠ VERIFY its compatibility with SDK v4 clients before adopting), which adds key commitment, a standard message format, multi-key keyrings and data-key caching.
- Never remove the account-root statement unless you fully understand the lock-out risk. Instead, restrict IAM with conditions and SCPs.
- Protect deletion three ways: key policy (only a security-admin role may
ScheduleKeyDeletion), an SCP denyingkms:ScheduleKeyDeletionandkms:DisableKeyfor everyone else, and an EventBridge rule that pages on those events. During the waiting period, KMS also emits an error metric if something tries to use the key — alarm on it. - Use encryption context everywhere and require it in key policies. It turns CloudTrail into a data-access log and stops ciphertext from being moved between records.
- Use
kms:ViaServicefor keys that should only be used by one service (RDS, S3, Secrets Manager), so a stolen role cannot callDecryptdirectly. - Cross-account use needs both the key policy (naming the other account or role) and the caller's IAM policy. Prefer naming specific roles with
kms:CallerAccountconditions. - AWS managed keys cannot be shared cross-account and their policies cannot be changed — another reason regulated data uses customer managed keys.
- Disabling vs deleting: disabling is reversible and is the right incident-response action. Deletion is irreversible and is a change-managed decommissioning step.
Banking use case
Harbourline encrypts every customer's date of birth and IBAN at field level in the Accounts API, under alias/hl-prod-customer-pii in the production workload account:
- The key policy allows only the Accounts API task role to
GenerateDataKeyandDecrypt, only whenkms:EncryptionContextKeysincludescustomer_id. - The data-protection team receives a monthly report from CloudTrail: number of
Decryptevents per role, and the top customer IDs decrypted. A spike for one customer, or decrypts at 03:00, triggers review. - Database administrators have full access to Aurora but no permission on the key; restored snapshots in a test account show only
enc:v1:tokens. - When a customer exercises the UK GDPR right to erasure, the bank deletes the rows; because the key is shared by all customers, it does not delete the key. (Per-customer keys for "crypto-shredding" are possible but cost USD 1 per key per month each — impractical for millions of customers. Per-tenant keys for corporate clients can make sense.)
- Disaster recovery: AWS Backup copies Aurora snapshots to
eu-west-1, re-encrypting under a key in that Region during the copy.
Common mistakes
- Using the alias in stored records. Aliases can be repointed; old records would then reference the wrong key. → Store the key ARN returned by KMS.
- Putting personal data in encryption context. → It is logged in plain text. Use identifiers.
- Calling KMS
Encrypton large payloads. → 4 KB limit; use envelope encryption. - Calling
GenerateDataKeyfor every small field at high volume. → You hit request quotas and pay per request. Cache data keys briefly (Encryption SDK caching) or encrypt a whole record with one data key. - Expecting rotation to re-encrypt data. → It only adds new key material; old ciphertext still decrypts with old material. Rotation does not help if a data key leaked.
- Scheduling deletion to "save USD 1". → Disable first, watch CloudTrail and metrics for at least a full business cycle, then schedule deletion with the longest window you can tolerate.
- Forgetting
kms:CreateGrant. → Roles that create encrypted EBS volumes or RDS instances need it (withkms:GrantIsForAWSResource), or creation fails with a KMS error.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
AccessDeniedException ... because no resource-based policy allows the kms:Decrypt action | Key policy does not name the caller (typical cross-account) and has no account-root delegation for its account | Add the caller to the key policy, or the account-root statement plus an IAM policy |
AccessDeniedException although the IAM policy allows kms:Decrypt | Key policy lacks the account-root statement, or a condition (encryption context, ViaService) is not met | Read the key policy conditions; compare with the request's context in CloudTrail |
InvalidCiphertextException | Wrong or missing encryption context, corrupted blob, or blob from another key | Supply the exact context used at encryption |
IncorrectKeyException | KeyId pinned in Decrypt differs from the key that wrapped the blob | Use the key ARN stored with the record |
DisabledException / KMSInvalidStateException | Key disabled or pending deletion | aws kms describe-key; enable or cancel deletion if appropriate |
ThrottlingException | Exceeded the shared cryptographic request quota | Data-key caching, batching, exponential backoff (the SDK retries), quota increase via Service Quotas |
NotFoundException: Alias ... is not found | Wrong Region or alias name | aws kms list-aliases --region us-east-1 |
S3 upload fails with KMS.AccessDeniedException | Uploader lacks kms:GenerateDataKey on the bucket's key | Add it to the role (and key policy if cross-account) |
Cost and cleanup
Cost: a customer managed key costs USD 1 per month, prorated hourly (so a key that exists for two hours costs well under one cent). Requests cost USD 0.03 per 10,000 for symmetric operations after the free tier of 20,000 requests per month; asymmetric Sign requests are priced higher (the pricing page shows USD 0.15 per 10,000 for ECC signing in its example) and are excluded from the free tier. The first and second rotations each add USD 1 per month to the key; later rotations add nothing. Keys pending deletion are not charged. This lesson costs a few cents if you clean up the same day.
export AWS_PROFILE=learn-sandbox AWS_REGION=us-east-1
KEY_ID=$(aws kms describe-key --key-id alias/hl-m05-data --query KeyMetadata.KeyId --output text)
aws kms delete-alias --alias-name alias/hl-m05-data
aws kms schedule-key-deletion --key-id "$KEY_ID" --pending-window-in-days 7
aws kms describe-key --key-id "$KEY_ID" --query KeyMetadata.KeyState # PendingDeletion
rm -f key-policy.json datakey.json
# CDK / Terraform versions: cdk destroy or terraform destroy
aws resourcegroupstaggingapi get-resources --tag-filters Key=Project,Values=cea-lab --resource-type-filters kmsKeys pending deletion still appear in the tagging API until the waiting period ends; that is expected.
Exercises
- 🟢 Guided: Run the CLI section end to end. Then open CloudTrail → Event history, filter Event source = kms.amazonaws.com, and find your
GenerateDataKeyand bothDecryptevents. Note where the encryption context appears and how the failed decrypt is recorded. - 🟡 Challenge: Change the key policy so your role may
Decryptonly whenkms:EncryptionContext:fieldisiban(notdate_of_birth). Prove with two CLI calls that the rule works, then explain whykms:EncryptionContextKeysalone could not express this. - 🔴 Live problem: The payments team asks for "one KMS key per customer so we can crypto-shred on GDPR erasure". Harbourline has 2.4 million customers. Write a one-page response: cost, quotas, operational risk, and an alternative design that still makes erased data unreadable.
Assignment
In your portfolio repository, add a Terraform or CDK module kms-data-key that creates a customer managed key with: account-root delegation, separate administrator and user principals as inputs, a required encryption-context key as an input, rotation on, a 30-day default deletion window, mandatory tags, and an EventBridge rule plus SNS topic that alerts on ScheduleKeyDeletion and DisableKey. Include a README with a usage example and the expected monthly cost.
Solutions
GenerateDataKey and Decrypt events show the context under requestParameters.encryptionContext — that is why identifiers, not personal data, belong there. The failed decrypt has errorCode: InvalidCiphertextException; KMS does not say which part was wrong, by design, so an attacker cannot use error messages to guess contexts. Note the userIdentity.arn is your SSO session ARN, which is what an auditor would trace back to a person through Identity Center.
Add a condition "StringEquals": { "kms:EncryptionContext:field": "iban" } to the user statement. A decrypt with field=date_of_birth then fails with AccessDeniedException (a policy denial), whereas a wrong value for a context key that the policy does not check would fail later with InvalidCiphertextException. kms:EncryptionContextKeys only tests which keys are present, not their values, so it can require "there is a field key" but cannot distinguish iban from date_of_birth.
Cost: 2.4 million keys × USD 1 = about USD 2.4 million per month, before rotation charges. Quotas: KMS has a per-account key resource quota (100,000 by default per Region ⚠ VERIFY current value) that would need a large increase, and CreateKey is limited to 5 requests/second, so creating keys alone takes days. Operationally, millions of key policies are unauditable. Alternative: one customer managed key per data domain, envelope encryption with a per-customer data key stored in a key table; erasure deletes the customer's rows and their wrapped data keys, so any copies of their ciphertext in backups become undecryptable once backups holding the key table age out. Document backup retention and residual-copy handling with the DPO — crypto-shredding is a compliance argument that legal must accept, not a technical guarantee.
Knowledge check
Answer: It enables IAM policies in account 111122223333 to grant access to the key. It does not give the root user special day-to-day access and does not by itself let any role use the key; an IAM policy must still allow it. Removing it means only principals named in the key policy can use or manage the key.
Answer: Nothing. KMS keeps all previous key material and automatically uses the right version to decrypt. Rotation changes the material used for new encryptions; the key ID, ARN and policy stay the same, and no data is re-encrypted.
Answer: Encrypt accepts at most 4 KB, every call counts against the shared request quota and costs money, and network latency adds up. Envelope encryption calls KMS once per data key and does the bulk encryption locally, while the KMS key never leaves KMS.
Answer: Asymmetric keys, HMAC keys, keys in custom key stores, and keys with imported material (those support on-demand rotation after you import new material, but not automatic rotation). Rotate them manually by creating a new key and repointing the alias.
Answer: Run CancelKeyDeletion; the key returns in the Disabled state, so also run EnableKey. After day 7 nothing can recover the key or data encrypted only under it.
Interview questions
- "How would you prove to an auditor that DBAs cannot read customer PII?" — Field-level envelope encryption under a customer managed key whose policy grants use only to the application role; DBAs have no KMS permissions; CloudTrail shows every decrypt with encryption context; a test restore in a non-production account shows only ciphertext.
- "What is encryption context and why do you care?" — Non-secret, authenticated key/value data bound to the ciphertext. Decrypt fails without it, it can be required by key policy conditions, and it appears in CloudTrail — making it an access log and a defence against moving ciphertext between records.
- "AWS managed key or customer managed key?" — Customer managed for regulated data: you control the policy, cross-account use, rotation period and deletion; AWS managed keys are fine for low-risk data where convenience wins.
- "How do you stop someone deleting a production key?" — Separation of duties in the key policy, an SCP denying
ScheduleKeyDeletionexcept for a break-glass role with MFA, EventBridge alerts, and the 30-day window.
Certification practice
A security engineer creates a customer managed key using a key policy that names only the application role as a user and the security team role as administrator. It does not include the account-root statement. A new analytics role is given an IAM policy allowing kms:Decrypt on the key ARN. Calls from the analytics role fail. Why?
A. IAM policies cannot reference KMS key ARNs.
B. Without the account-root statement, IAM policies cannot grant access to the key; only the key policy can.
C. The analytics role needs kms:CreateGrant.
D. Automatic rotation must be enabled before IAM policies apply.
Answer: B. The account-root statement is what delegates authority to IAM. A is false. C is unrelated to direct decrypt. D is unrelated to authorisation.
An application stores encrypted customer records. The team wants KMS to refuse to decrypt a record unless the request states which customer it belongs to, and wants CloudTrail to show the customer ID for every decrypt. What should they do?
A. Store the customer ID in the key alias.
B. Use a separate key per customer.
C. Pass the customer ID as encryption context on encrypt and decrypt, and require it with a kms:EncryptionContextKeys condition in the key policy.
D. Tag each ciphertext object with the customer ID.
Answer: C. Encryption context is cryptographically bound, enforceable in policy and logged. A is meaningless. B is expensive and unnecessary. D does not affect KMS authorisation.
A bank runs DynamoDB global tables in eu-west-2 and eu-west-1 and wants client-side encrypted items written in one Region to be decryptable in the other without cross-Region KMS calls. What should the architect use?
A. An AWS managed key in each Region. B. A multi-Region customer managed key with a replica in the second Region. C. One single-Region key in eu-west-2, called from both Regions. D. SSE-S3.
Answer: B. Related multi-Region keys share key material and key ID, so either Region can decrypt locally. A cannot decrypt the other Region's ciphertext. C works but adds cross-Region latency and a regional dependency. D does not apply to DynamoDB client-side encryption.
A developer must encrypt 2 MB statements before writing them to S3 with client-side encryption using a KMS key. Calls to Encrypt fail. What should the developer do?
A. Split the file into 4 KB chunks and call Encrypt for each.
B. Call GenerateDataKey, encrypt the file locally with the plaintext data key, store the encrypted data key with the object, and discard the plaintext key.
C. Request a quota increase for the Encrypt payload size.
D. Use an asymmetric RSA key, which supports larger payloads.
Answer: B. That is envelope encryption. A is slow and costly. C is not a quota that can be raised. D is wrong: RSA payloads are even smaller.
Completion checklist
- I can explain AWS owned vs AWS managed vs customer managed keys
- I created a key with a policy that uses an encryption-context condition, and proved it
- I ran envelope encryption from C# (or
hl-crypto envelope --local) - I found my KMS calls in CloudTrail and read the encryption context
- I know the rotation, deletion and quota facts in this lesson
- I scheduled my lab key for deletion and removed the alias
Key takeaways
- KMS keys never leave KMS; envelope encryption lets you encrypt any amount of data with one KMS call per data key.
- The key policy is the primary control; the account-root statement enables IAM; separate administrators from users.
- Encryption context binds ciphertext to a record, can be required by policy, and makes CloudTrail a data-access log.
- Rotation adds new key material without re-encrypting anything; asymmetric, HMAC and custom-key-store keys rotate manually.
- Deletion is irreversible after 7–30 days: disable first, protect with policy, SCP and alerts.
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.
Labs 5.1 and 5.2: IAM policy puzzles, permission boundaries and an offline policy linter
Predict allow or deny for ten IAM evaluation puzzles, confirm each with an offline evaluator and the IAM policy simulator, lint a deliberately bad policy, and design a permission boundary that lets a developer create roles without escalating privileges.
When banks need CloudHSM
Decide when a bank genuinely needs single-tenant HSMs: AWS CloudHSM clusters, KMS custom key stores (CloudHSM and external), AWS Payment Cryptography, the PKCS#11 programming model from .NET, and the real operational cost.