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

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.

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

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:ViaService conditions.
  • Explain grants and when AWS services create them for you.
  • Implement envelope encryption in C#: GenerateDataKey, local AES-GCM, store the wrapped key, Decrypt with 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-sandbox profile, .NET 10 SDK (or Docker), optionally Terraform 1.10+
  • Lab repository labs/m05-secure-banking-api for the offline version

Why this matters in banking

Three conversations a cloud engineer at a bank has every quarter:

  1. 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 no kms:Decrypt sees only ciphertext.
  2. 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-2 makes encrypted snapshots copied to eu-west-1 useless unless you planned keys for the recovery Region.
  3. 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:

  1. Ask KMS for a fresh data key. KMS returns it twice: in plain text, and encrypted ("wrapped") under your KMS key.
  2. Encrypt your data locally with the plain-text data key (AES-256-GCM).
  3. Throw away the plain-text data key. Store the wrapped data key next to the ciphertext.
  4. 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.

TermPlain meaning
KMS key (formerly "CMK")The logical key in KMS: ID, ARN, policy, state, and one or more versions of key material
Key materialThe secret bits inside the HSM. Rotation adds new material; the key ID stays the same
Data keyA key KMS generates for you to encrypt data outside KMS
Encryption contextNon-secret key/value pairs bound to a ciphertext; decrypt fails unless the same pairs are supplied; logged in CloudTrail
Key policyThe resource-based policy on a KMS key — the primary access control
GrantA delegated, revocable permission to use a key, usually created by AWS services
AliasA 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

TypeWho creates and controls itVisible in your accountKey policy you controlCostBanking use
AWS owned keyThe AWS service, shared across accountsNoNoFreeDefault 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 accountYesNo (read only)No monthly fee; requests chargedQuick wins, but you cannot restrict who uses it, share it cross-account or delete it
Customer managed keyYouYesYesUSD 1 per key per month, prorated hourlyThe default for regulated data: your policy, your rotation, your deletion decision, cross-account use

Key specs

Key specUsageRotationTypical use
SYMMETRIC_DEFAULT (AES-256-GCM inside KMS)Encrypt/decrypt, data keysAutomatic and on-demandAlmost everything: S3, RDS, field encryption
RSA_2048/3072/4096Encrypt/decrypt or sign/verifyManual onlySigning documents; encrypting for parties outside AWS
ECC_NIST_P256/P384/P521, ECC_SECG_P256K1Sign/verify (and key agreement)Manual onlyPayment instruction signing (Lab 5.7)
HMAC_224/256/384/512GenerateMac/VerifyMacManual onlyTokens, blind indexes, message authentication
ML-DSA (post-quantum signatures)Sign/verifyManual onlyEarly 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 equivalentWhat's different
Azure Key Vault (keys)AWS KMSKMS is keys only; secrets live in Secrets Manager. KMS keys cannot be exported (except imported material you already hold)
Key Vault Premium / Managed HSMKMS (FIPS-validated HSMs) / CloudHSM key storeKMS already uses HSMs; single-tenant HSMs are CloudHSM — see When banks need CloudHSM
Key Vault access policies / RBAC data-plane rolesKey policy + IAM policies + grantsThe 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 keySame idea; in AWS you choose the key at resource creation for many services
Key Vault soft delete + purge protectionKMS deletion waiting period (7–30 days) + CancelKeyDeletionThere is no "purge protection" switch; protect deletion with key policy, SCP and alerts
Key Vault key rotation policyAutomatic rotation (period in days) and on-demand rotationKMS keeps the same key ID and all old material; no re-encryption is needed
CryptographyClient.WrapKey / Always Encrypted column master keysGenerateDataKey / envelope encryptionAWS 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:

  1. The account-root statement ("Principal": {"AWS": "arn:aws:iam::<account>:root"} with kms:*). 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.
  2. Key administrators: manage but not use.
  3. Key users: use but not manage, with conditions:
    • kms:EncryptionContextKeys or kms:EncryptionContext:customer_id to force callers to bind ciphertext to a customer;
    • kms:ViaService (for example rds.us-east-1.amazonaws.com) to allow use only through a service;
    • kms:CallerAccount for 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

  1. 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.
  2. Alias: hl-m05-data. Description: "Lab 5.3 field encryption". Tags: Project=cea-lab, Lab=m05-kms, Environment=learn, Owner=<you>.
  3. 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.
  4. Key users: choose the same role for the lab. In production this is the workload role.
  5. 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:CreateGrant with kms:GrantIsForAWSResource).
  6. Open the key → Key rotation tab → Automatically rotate this KMS key every year → set the rotation period → Save.
  7. 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).

Harbourline.Security.KmsEnvelope.csproj
<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>
Program.cs
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 authentication

Code explained line by line

  1. AWSSDK.KeyManagementService 4.1.1.1 is the SDK v4 KMS client; AWSSDK.SSO/SSOOIDC let the default credential chain use your Identity Center profile.
  2. new AmazonKeyManagementServiceClient() — credentials and Region come from the environment (AWS_PROFILE, profile Region). In ASP.NET Core register it with AddAWSService<IAmazonKeyManagementService>() and inject the interface.
  3. 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.
  4. GenerateDataKeyAsync with KeySpec = AES_256 returns Plaintext (32 bytes) and CiphertextBlob (the wrapped key, which also embeds a reference to the KMS key). KeyId in the response is always the full key ARN, even if you passed an alias — store the ARN, not the alias.
  5. AesGcm.NonceByteSizes.MaxSize is 12 bytes, the standard GCM nonce. Because every record gets a new data key, nonce reuse under one key is impossible here.
  6. 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.
  7. ZeroMemory in finally — best-effort removal of the plaintext key from memory. .NET may have copied it; this reduces, not eliminates, exposure.
  8. 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.
  9. EncryptionContext = context on decrypt — must match exactly (keys and values, case-sensitive). Any difference gives InvalidCiphertextException, deliberately indistinguishable from a corrupted blob.
  10. The tamper check flips one bit; AesGcm.Decrypt throws AuthenticationTagMismatchException (a CryptographicException). Never catch and ignore it.
  11. EnvelopeRecord — a real system adds a format version and serialises compactly; see EnvelopeCiphertext in 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 denying kms:ScheduleKeyDeletion and kms:DisableKey for 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:ViaService for keys that should only be used by one service (RDS, S3, Secrets Manager), so a stolen role cannot call Decrypt directly.
  • 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:CallerAccount conditions.
  • 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 GenerateDataKey and Decrypt, only when kms:EncryptionContextKeys includes customer_id.
  • The data-protection team receives a monthly report from CloudTrail: number of Decrypt events 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 Encrypt on large payloads. → 4 KB limit; use envelope encryption.
  • Calling GenerateDataKey for 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 (with kms:GrantIsForAWSResource), or creation fails with a KMS error.

Troubleshooting

SymptomLikely causeFix
AccessDeniedException ... because no resource-based policy allows the kms:Decrypt actionKey policy does not name the caller (typical cross-account) and has no account-root delegation for its accountAdd the caller to the key policy, or the account-root statement plus an IAM policy
AccessDeniedException although the IAM policy allows kms:DecryptKey policy lacks the account-root statement, or a condition (encryption context, ViaService) is not metRead the key policy conditions; compare with the request's context in CloudTrail
InvalidCiphertextExceptionWrong or missing encryption context, corrupted blob, or blob from another keySupply the exact context used at encryption
IncorrectKeyExceptionKeyId pinned in Decrypt differs from the key that wrapped the blobUse the key ARN stored with the record
DisabledException / KMSInvalidStateExceptionKey disabled or pending deletionaws kms describe-key; enable or cancel deletion if appropriate
ThrottlingExceptionExceeded the shared cryptographic request quotaData-key caching, batching, exponential backoff (the SDK retries), quota increase via Service Quotas
NotFoundException: Alias ... is not foundWrong Region or alias nameaws kms list-aliases --region us-east-1
S3 upload fails with KMS.AccessDeniedExceptionUploader lacks kms:GenerateDataKey on the bucket's keyAdd 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 kms

Keys 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 GenerateDataKey and both Decrypt events. Note where the encryption context appears and how the failed decrypt is recorded.
  • 🟡 Challenge: Change the key policy so your role may Decrypt only when kms:EncryptionContext:field is iban (not date_of_birth). Prove with two CLI calls that the rule works, then explain why kms:EncryptionContextKeys alone 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

Knowledge check

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 ScheduleKeyDeletion except for a break-glass role with MFA, EventBridge alerts, and the 30-day window.

Certification practice

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.

On this page