AWS KMS (Key Management Service)AuthorCloudBrum editorial teamLast reviewed30 Oct 2026Reading time~12 minLevelBeginner to advanced

• Keys that stay in the hardwareA KMS key is created inside hardware security modules that AWS runs. You can use it to encrypt and decrypt, but you can’t read the key material of a symmetric key, and so neither can anyone who steals a credential.
• Envelope encryptionKMS encrypts small things directly (up to 4 KB). For anything larger it hands your code a data key, in plain and encrypted form. You encrypt the data locally with the plain key, throw it away, and store the encrypted key next to the data.
• Three ways to grant accessEvery key has a key policy. IAM policies can add permissions only if the key policy allows it, and grants hand out narrow, temporary rights to a service or a role. Conditions such as kms:ViaService limit a key to one service.
• RotationAutomatic rotation creates new key material on a schedule of 90 to 2,560 days (365 by default) and keeps the old material so existing data can still be read. You can also rotate on demand.
• Multi-Region keysA multi-Region key has the same key ID and key material in several Regions, so data encrypted in one Region can be decrypted in another without a round trip. Each replica keeps its own policy.
• Built into AWS servicesS3, EBS, RDS, DynamoDB, Lambda, Secrets Manager and many other services can encrypt with a KMS key you choose, and you don’t write any cryptography code for that.
• More than one kind of keyBesides symmetric keys there are RSA and elliptic curve key pairs for signing and encryption, HMAC keys, and ML-DSA keys for post-quantum signatures. You can import your own key material, or keep the key outside AWS in an external key store.
• Every use is loggedEach call to KMS is recorded in CloudTrail with the caller, the key and the encryption context, which is how you answer who decrypted what and when.

KMS key

The main resource in the service. It used to be called a customer master key (CMK). A KMS key holds key material and metadata such as its state, usage and key policy.

AWS owned, AWS managed and customer managed keys

AWS owned keys sit in service accounts and you never see them. AWS managed keys (for example aws/s3) appear in your account, free of a monthly fee, and you can’t change their policy. Customer managed keys are the ones you create and control.

Key policy

A resource policy attached to one key. It is the first thing KMS checks, and an IAM policy has no effect unless the key policy allows IAM to take part.

Grant

A temporary, narrow permission on a key that you or an AWS service creates for a grantee, usually for a single task such as attaching an encrypted volume.

Data key

A key that KMS generates for you to encrypt data outside KMS. You get it in plain text and as a copy encrypted under a KMS key.

Envelope encryption

Encrypting data with a data key, and then encrypting that data key with a KMS key. It keeps large data out of KMS and keeps the number of calls low.

Encryption context

Extra key and value pairs that KMS binds to the ciphertext. They aren’t secret, they appear in CloudTrail, and the same pairs must be supplied to decrypt.

Alias

A friendly name such as alias/orders-prod that points to a key. You can move an alias to a new key without changing code.

Multi-Region key

A set of related keys in different Regions that share an ID and key material. One is the primary and the others are replicas.

Key material

The cryptographic secret inside a KMS key. KMS can generate it, you can import it, or it can live in an external key manager.

Custom key store

A key store backed by an AWS CloudHSM cluster that you own, for keys that must sit in a single-tenant HSM.

External key store (XKS)

A key store where the key material stays in an external key manager that you run outside AWS, and KMS sends the cryptographic operations to it.

Key state

Enabled, disabled, pending deletion, pending import and so on. A key that isn’t enabled can’t be used, and neither can the data that depends on it.

Create a customer managed key and use it with the AWS CLI

1. Decide who administers and who usesWrite down two lists: the role that manages the key and the roles or services that may encrypt and decrypt with it. Keep them separate, because the administrator doesn’t need to read the data.
2. Write the key policy firstStart from a policy that names the administrator role, the user roles and the account root (which turns on IAM policies). A key policy that leaves everyone out is the one mistake that needs AWS Support to fix.
3. Create the key and an aliasRun create-key with the policy, then create-alias with a name such as alias/orders-prod. Use the alias in code and in other services' settings.
4. Turn on rotationEnable automatic rotation and set the period. A year is the default and a shorter period is a policy decision, because every rotation adds a billable version of the key material.
5. Point a service at the keyFor example, set default encryption on an S3 bucket to SSE-KMS with your key and switch on S3 Bucket Keys, so S3 doesn’t call KMS for every object.
6. Use data keys in your own codeAsk for a data key with generate-data-key, encrypt locally with an AES-GCM library, keep the encrypted data key with the ciphertext and pass an encryption context that names the tenant or record.
7. Allow a service through a grant or a conditionWhere a service needs access for a task, create a grant. Where a role should use the key only through one service, add kms:ViaService to the policy.
8. Watch itSend CloudTrail to a log bucket and alert on ScheduleKeyDeletion, DisableKey, policy changes and a sudden rise in Decrypt calls.
9. Plan the end of the keyNever delete a key you are unsure about. Disable it first, wait, and then schedule deletion with the longest waiting period. Data that was encrypted under a deleted key is gone for good.

• Use envelope encryption and keep data keys in a short-lived cache, so a busy service doesn’t call KMS for every record.
• Enable S3 Bucket Keys on buckets that use SSE-KMS, which cuts the number of KMS requests sharply, according to AWS.
• Keep keys in the same Region as the workload, since every call crosses the network to the KMS endpoint.
• Use a VPC interface endpoint for KMS so calls from private subnets don’t go through a NAT gateway.
• Retry with exponential backoff and jitter on throttling errors, and let the SDK do it.
• Use the AWS Encryption SDK when you need caching of data keys and a standard message format.
• Spread very hot workloads across several keys, because quotas are per key type and Region, and check them in Service Quotas.
• Use asymmetric keys only where needed, since their operations are slower and cost more than symmetric ones.

FinOps is the habit of managing cloud spend together with engineering. These are the FinOps checks that matter most for AWS KMS.

• Count the keys first: each customer managed key costs about one dollar a month, so a key per application and stage is cheap, and a key per customer record is not.
• Use AWS managed keys where the default policy is acceptable, since they have no monthly fee.
• Turn on S3 Bucket Keys, because object-level KMS requests are the usual source of a large bill.
• Cache data keys and decrypted values in your application for a short time.
• Remember that rotation adds charges for each older version of key material that stays in the key. A shorter period costs a bit more.
• Delete keys that nobody needs, after the disable-and-wait routine, so you stop paying for them.
• Watch asymmetric and HMAC requests, which are priced higher than symmetric ones.
• Check multi-Region replicas: each replica is billed as its own key.
• Look at requests by key in CloudTrail or Cost Explorer before you decide which workload to tune.
• Tag keys with an owner and a project, and add a budget alert on KMS spend.

• Write separate key administrators and key users, and avoid giving one role both.
• Keep the account root statement in the key policy so IAM policies work, and so the key can’t be orphaned.
• Use encryption context and the kms:EncryptionContext condition to tie a key’s use to a tenant, table or application.
• Limit a role to a service with kms:ViaService, and to your organisation with aws:PrincipalOrgID when sharing keys.
• Turn on automatic rotation for symmetric keys, and decide a rotation period that matches your policy.
• Set a service control policy that denies kms:ScheduleKeyDeletion and kms:DisableKey except for a break-glass role.
• Use IAM Access Analyzer to find keys shared with external accounts, and review the findings.
• Send CloudTrail to a protected bucket in another account, and alert on key policy changes.
• Prefer customer managed keys for sensitive data, so that you can disable them and show their policy.
• Use multi-Region keys only where you need them, and give each replica the policy it needs, not a copy of the primary’s.

AWS CloudTrail records every KMS call, AWS Config checks the rules above, IAM Access Analyzer reports keys shared outside the account, and AWS Artifact holds compliance reports. AWS runs the HSMs and the service, and AWS says the HSMs hold a FIPS 140-3 Level 3 validation. You own the key policies, the rotation settings, who may use each key and the decision to delete.

• Cache data keys and decrypted values, so fewer requests travel to the KMS endpoint.
• Turn on S3 Bucket Keys, which cuts request volume for object-heavy buckets.
• Delete test keys and old multi-Region replicas that you no longer use.
• Where data rules allow and latency doesn’t matter, run in a Region with a cleaner power grid.
• Keep asymmetric operations for places that need them, since they use more compute than symmetric ones.
• The Customer Carbon Footprint Tool reports emissions per account. It doesn’t break out KMS, so don’t put a number on it.

Purchase options

What you actually pay for

• Each customer managed key and each multi-Region replica
• Requests beyond the monthly free tier, from services and from your own code
• Older versions of rotated key material, according to AWS’s pricing page
• CloudHSM clusters behind a custom key store, and the infrastructure behind an external key store
• CloudTrail storage and data transfer for logs and cross-Region traffic

An orders-prod key for an orders service: a customer managed key whose policy separates the administrator role from the application role, rotating every 180 days, with an S3 bucket encrypted under it and Bucket Keys switched on. The AWS CLI tab creates it step by step and Terraform builds the same set. The Python tab encrypts a payload with a data key (envelope encryption) and decrypts it again, and the C# tab audits every customer managed key in an account for rotation, state and sharing. Replace the account number and the role names with your own. The key policy is the part to read twice.

# Placeholders: replace the account, role names and bucket with your own.
REGION=ap-south-1
ACCOUNT=111122223333
BUCKET=orders-prod-data-example

# 1. The key policy. Admins manage the key but cannot use it for data. The app role can use it but cannot manage it.
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": "KeyAdministration", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::$ACCOUNT:role/kms-key-admin"},
     "Action": ["kms:Create*", "kms:Describe*", "kms:Enable*", "kms:List*", "kms:Put*", "kms:Update*", "kms:Revoke*",
                "kms:Disable*", "kms:Get*", "kms:TagResource", "kms:UntagResource", "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion"], "Resource": "*"},
    {"Sid": "KeyUsage", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::$ACCOUNT:role/orders-app"},
     "Action": ["kms:Decrypt", "kms:GenerateDataKey", "kms:DescribeKey"], "Resource": "*",
     "Condition": {"StringEquals": {"kms:EncryptionContext:app": "orders"}}}
  ]
}
EOF

# 2. Create the key, give it an alias and turn on rotation every 180 days.
KEY_ID=$(aws kms create-key --region $REGION --description "orders-prod data key" --key-usage ENCRYPT_DECRYPT --key-spec SYMMETRIC_DEFAULT \
  --policy file://key-policy.json --tags TagKey=app,TagValue=orders TagKey=env,TagValue=prod --query KeyMetadata.KeyId --output text)
aws kms create-alias --region $REGION --alias-name alias/orders-prod --target-key-id "$KEY_ID"
aws kms enable-key-rotation --region $REGION --key-id "$KEY_ID" --rotation-period-in-days 180
aws kms get-key-rotation-status --region $REGION --key-id "$KEY_ID"

# 3. Encrypt a bucket with the key, and use S3 Bucket Keys so S3 doesn't call KMS for every object.
aws s3api put-bucket-encryption --bucket $BUCKET --server-side-encryption-configuration '{
  "Rules": [{"ApplyServerSideEncryptionByDefault": {"SSEAlgorithm": "aws:kms", "KMSMasterKeyID": "alias/orders-prod"}, "BucketKeyEnabled": true}]}'

# 4. A data key for envelope encryption: you get a plain copy to encrypt with, and an encrypted copy to store.
aws kms generate-data-key --region $REGION --key-id alias/orders-prod --key-spec AES_256 --encryption-context app=orders \
  --query '{encrypted:CiphertextBlob,plain:Plaintext}'

# 5. A grant lets a role use the key for one task, without editing the policy.
aws kms create-grant --region $REGION --key-id "$KEY_ID" --grantee-principal arn:aws:iam::$ACCOUNT:role/orders-batch \
  --operations Decrypt GenerateDataKey --constraints EncryptionContextSubset={app=orders}

# 6. A multi-Region key for data that must be readable in a second Region.
DR_KEY=$(aws kms create-key --region $REGION --multi-region --description "orders-dr data key" --query KeyMetadata.KeyId --output text)
aws kms replicate-key --region $REGION --key-id "$DR_KEY" --replica-region ap-southeast-1

# 7. Ending a key: disable it first and watch for failures. Deletion waits 30 days and cannot be undone after that.
aws kms disable-key --region $REGION --key-id "$KEY_ID"
aws kms schedule-key-deletion --region $REGION --key-id "$KEY_ID" --pending-window-in-days 30
aws kms cancel-key-deletion --region $REGION --key-id "$KEY_ID"

# Placeholders: pass in your own account number and role names.
provider "aws" {
  region = "ap-south-1"
}

provider "aws" {
  alias  = "singapore"
  region = "ap-southeast-1"
}

variable "account_id" {
  type = string
}

variable "admin_role_name" {
  type    = string
  default = "kms-key-admin"
}

variable "app_role_name" {
  type    = string
  default = "orders-app"
}

data "aws_iam_policy_document" "orders_key" {
  statement {
    sid       = "EnableIamPolicies"
    actions   = ["kms:*"]
    resources = ["*"]
    principals {
      type        = "AWS"
      identifiers = ["arn:aws:iam::${var.account_id}:root"]
    }
  }

  statement {
    sid = "KeyAdministration"
    actions = [
      "kms:Create*", "kms:Describe*", "kms:Enable*", "kms:List*", "kms:Put*", "kms:Update*",
      "kms:Revoke*", "kms:Disable*", "kms:Get*", "kms:TagResource", "kms:UntagResource",
      "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion",
    ]
    resources = ["*"]
    principals {
      type        = "AWS"
      identifiers = ["arn:aws:iam::${var.account_id}:role/${var.admin_role_name}"]
    }
  }

  statement {
    sid       = "KeyUsage"
    actions   = ["kms:Decrypt", "kms:GenerateDataKey", "kms:DescribeKey"]
    resources = ["*"]
    principals {
      type        = "AWS"
      identifiers = ["arn:aws:iam::${var.account_id}:role/${var.app_role_name}"]
    }
    condition {
      test     = "StringEquals"
      variable = "kms:EncryptionContext:app"
      values   = ["orders"]
    }
  }
}

resource "aws_kms_key" "orders" {
  description              = "orders-prod data key"
  key_usage                = "ENCRYPT_DECRYPT"
  customer_master_key_spec = "SYMMETRIC_DEFAULT"
  enable_key_rotation      = true
  rotation_period_in_days  = 180
  deletion_window_in_days  = 30
  policy                   = data.aws_iam_policy_document.orders_key.json

  tags = {
    app = "orders"
    env = "prod"
  }
}

resource "aws_kms_alias" "orders" {
  name          = "alias/orders-prod"
  target_key_id = aws_kms_key.orders.key_id
}

resource "aws_s3_bucket" "data" {
  bucket = "orders-prod-data-example"
}

resource "aws_s3_bucket_server_side_encryption_configuration" "data" {
  bucket = aws_s3_bucket.data.id

  rule {
    bucket_key_enabled = true
    apply_server_side_encryption_by_default {
      sse_algorithm     = "aws:kms"
      kms_master_key_id = aws_kms_key.orders.arn
    }
  }
}

# A multi-Region primary key and a replica, for data that must be readable in a second Region.
resource "aws_kms_key" "orders_dr" {
  description             = "orders-dr data key"
  multi_region            = true
  enable_key_rotation     = true
  deletion_window_in_days = 30
}

resource "aws_kms_replica_key" "orders_dr_singapore" {
  provider                = aws.singapore
  description             = "orders-dr replica"
  primary_key_arn         = aws_kms_key.orders_dr.arn
  deletion_window_in_days = 30
}

output "orders_key_arn" {
  value = aws_kms_key.orders.arn
}

# pip install boto3 cryptography
# Envelope encryption: KMS makes a data key, AES-GCM encrypts the payload locally, and only the encrypted data key is stored with it.
import json
import os

import boto3
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

kms = boto3.client("kms", region_name="ap-south-1")
KEY = "alias/orders-prod"


def encrypt(payload, tenant):
    context = {"app": "orders", "tenant": tenant}
    data_key = kms.generate_data_key(KeyId=KEY, KeySpec="AES_256", EncryptionContext=context)
    nonce = os.urandom(12)
    ciphertext = AESGCM(data_key["Plaintext"]).encrypt(nonce, payload, json.dumps(context, sort_keys=True).encode())
    return {                                      # the plain data key is never stored
        "key": data_key["CiphertextBlob"].hex(),
        "nonce": nonce.hex(),
        "data": ciphertext.hex(),
        "context": context,
    }


def decrypt(envelope):
    context = envelope["context"]
    plain_key = kms.decrypt(CiphertextBlob=bytes.fromhex(envelope["key"]), EncryptionContext=context)["Plaintext"]
    return AESGCM(plain_key).decrypt(bytes.fromhex(envelope["nonce"]), bytes.fromhex(envelope["data"]),
                                     json.dumps(context, sort_keys=True).encode())


if __name__ == "__main__":
    sealed = encrypt(b'{"order": 1042, "card_last4": "4242"}', tenant="acme")
    print("stored:", {k: (v[:16] + "...") if isinstance(v, str) else v for k, v in sealed.items()})
    print("read back:", decrypt(sealed).decode())

// dotnet add package AWSSDK.KeyManagementService
// Audits every customer managed key in the Region: state, rotation, age and whether the key policy lets an outside principal in.
using System.Text.Json;
using Amazon.KeyManagementService;
using Amazon.KeyManagementService.Model;

using var kms = new AmazonKeyManagementServiceClient();
int problems = 0;
string? marker = null;
do
{
    var page = await kms.ListKeysAsync(new ListKeysRequest { Marker = marker, Limit = 100 });
    foreach (var item in page.Keys)
    {
        KeyMetadata key = (await kms.DescribeKeyAsync(new DescribeKeyRequest { KeyId = item.KeyId })).KeyMetadata;
        if (key.KeyManager != KeyManagerType.CUSTOMER) continue;

        var notes = new List<string>();
        if (key.KeyState == KeyState.PendingDeletion) notes.Add($"scheduled for deletion on {key.DeletionDate:yyyy-MM-dd}");
        if (key.KeyState == KeyState.Disabled) notes.Add("disabled");

        bool symmetric = key.KeySpec == KeySpec.SYMMETRIC_DEFAULT && key.Origin == OriginType.AWS_KMS;
        if (symmetric && key.KeyState == KeyState.Enabled)
        {
            var rotation = await kms.GetKeyRotationStatusAsync(new GetKeyRotationStatusRequest { KeyId = key.KeyId });
            if (rotation.KeyRotationEnabled != true) notes.Add("automatic rotation is off");
        }

        var policy = (await kms.GetKeyPolicyAsync(new GetKeyPolicyRequest { KeyId = key.KeyId, PolicyName = "default" })).Policy;
        using var doc = JsonDocument.Parse(policy);
        foreach (var st in doc.RootElement.GetProperty("Statement").EnumerateArray())
        {
            if (!st.TryGetProperty("Principal", out var p)) continue;
            string text = p.ToString();
            if (text == "*" || text.Contains("\"AWS\":\"*\"")) { notes.Add("key policy allows any principal"); break; }
        }

        string name = key.Description.Length > 0 ? key.Description : key.KeyId;
        Console.WriteLine($"{key.KeyId}  {key.KeyState,-16} created {key.CreationDate:yyyy-MM-dd}  {name}");
        foreach (var n in notes) { Console.WriteLine($"    ! {n}"); problems++; }
    }
    marker = page.Truncated == true ? page.NextMarker : null;
} while (marker != null);

Console.WriteLine(problems == 0 ? "No problems found." : $"{problems} problem(s) found.");
return problems == 0 ? 0 : 1;

Videos picked for this service. Each one is labelled with its source, opens on YouTube if you prefer, and loads only when you press play.

For passwords and tokens look at AWS Secrets Manager, which stores them encrypted under a KMS key. Server disks that use KMS keys are on Amazon EC2, and object data on Amazon S3. Databases that encrypt under KMS include Amazon RDS.