KMS Basics

8 examples to get you started with AWS KMS via the SDK - 5 basic and 3 intermediate.

Prerequisites

Install the SDK: Python pip install boto3 (1.43.x, Python 3.10+) or Node.js npm install @aws-sdk/client-kms (AWS SDK v3, Node 18+).
Credentials available through the default provider chain (environment variables, ~/.aws/credentials, or an attached role).
An IAM principal with kms:CreateKey, kms:Encrypt, kms:Decrypt, and kms:CreateAlias permissions, or an admin who can grant them.

Basic Examples

1. Create a symmetric key

Start with the default key type - it covers almost all encrypt/decrypt use cases.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
key = kms.create_key(
    Description="app-config-key",
    KeySpec="SYMMETRIC_DEFAULT",
    KeyUsage="ENCRYPT_DECRYPT",
)
key_id = key["KeyMetadata"]["KeyId"]
print(key_id)

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, CreateKeyCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
const key = await kms.send(new CreateKeyCommand({
  Description: "app-config-key",
  KeySpec: "SYMMETRIC_DEFAULT",
  KeyUsage: "ENCRYPT_DECRYPT",
}));
const keyId = key.KeyMetadata?.KeyId;
console.log(keyId);

SYMMETRIC_DEFAULT is AES-256-GCM, the right choice unless you specifically need asymmetric signing or encryption.
KeyUsage: ENCRYPT_DECRYPT is the default and cannot be changed after creation.
The returned KeyId is a UUID; you will almost always want an alias on top of it (example 2).

Related: KMS's Envelope-Encryption Model - what this key actually does under the hood.

2. Give the key a friendly alias

Aliases decouple your code from raw key IDs.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
kms.create_alias(AliasName="alias/app-config-key", TargetKeyId="1234abcd-12ab-34cd-56ef-1234567890ab")

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, CreateAliasCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
await kms.send(new CreateAliasCommand({
  AliasName: "alias/app-config-key",
  TargetKeyId: "1234abcd-12ab-34cd-56ef-1234567890ab",
}));

Alias names must start with alias/ and are unique per account per region.
You can pass alias/app-config-key anywhere a KeyId parameter is accepted - Encrypt, Decrypt, GenerateDataKey, all of it.
Repointing an alias to a new key (UpdateAlias) lets you change which physical key your code uses without a deploy.

3. Encrypt a small payload directly

For values under the size limit, skip the data-key dance entirely.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
resp = kms.encrypt(KeyId="alias/app-config-key", Plaintext=b"db-password-123")
ciphertext = resp["CiphertextBlob"]

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, EncryptCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
const resp = await kms.send(new EncryptCommand({
  KeyId: "alias/app-config-key",
  Plaintext: new TextEncoder().encode("db-password-123"),
}));
const ciphertext = resp.CiphertextBlob;

Plaintext must be bytes, not a string - encode it first in both SDKs.
Direct Encrypt is capped near 4KB for symmetric keys; use GenerateDataKey for anything larger.
CiphertextBlob is opaque binary - store it as-is (e.g., base64 in a text column).

4. Decrypt that payload back

Decrypt only needs the blob - not the key ID.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
resp = kms.decrypt(CiphertextBlob=ciphertext)
plaintext = resp["Plaintext"].decode("utf-8")
print(plaintext)

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, DecryptCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
const resp = await kms.send(new DecryptCommand({ CiphertextBlob: ciphertext }));
const plaintext = new TextDecoder().decode(resp.Plaintext);
console.log(plaintext);

The blob embeds which CMK encrypted it, so Decrypt resolves that automatically for single-region keys.
Passing a KeyId to Decrypt is optional but recommended as a defense-in-depth check that the ciphertext came from the key you expect.
A failed decrypt (wrong account, revoked access, tampered blob) raises AccessDeniedException or InvalidCiphertextException, not a silent wrong answer.

5. Check a key's status

Read key state before you build automation around it.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
desc = kms.describe_key(KeyId="alias/app-config-key")["KeyMetadata"]
print(desc["KeyState"], desc["KeySpec"], desc["KeyUsage"])

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, DescribeKeyCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
const desc = (await kms.send(new DescribeKeyCommand({ KeyId: "alias/app-config-key" }))).KeyMetadata;
console.log(desc?.KeyState, desc?.KeySpec, desc?.KeyUsage);

KeyState is typically Enabled; it can also be Disabled, PendingDeletion, or PendingImport.
A key in PendingDeletion still exists but rejects Encrypt/Decrypt - check this before an outage surprises you.
DescribeKey needs only kms:DescribeKey and works with either a key ID or an alias.

Intermediate Examples

6. Enable automatic key rotation

Symmetric CMKs can rotate their backing key material once a year with no code changes.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
kms.enable_key_rotation(KeyId="alias/app-config-key")
status = kms.get_key_rotation_status(KeyId="alias/app-config-key")
print(status["KeyRotationEnabled"])

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, EnableKeyRotationCommand, GetKeyRotationStatusCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
await kms.send(new EnableKeyRotationCommand({ KeyId: "alias/app-config-key" }));
const status = await kms.send(new GetKeyRotationStatusCommand({ KeyId: "alias/app-config-key" }));
console.log(status.KeyRotationEnabled);

Rotation is only available for symmetric, customer-managed CMKs with Origin: AWS_KMS.
Old key material is retained internally so ciphertext encrypted before rotation still decrypts correctly.
Your alias and KeyId never change across a rotation - callers notice nothing.

Related: Automatic Key Rotation & Multi-Region Keys - rotation schedules in depth.

7. Delegate access with a grant instead of editing the key policy

Grants let a specific principal use the key for specific operations, revocable independently.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
grant = kms.create_grant(
    KeyId="alias/app-config-key",
    GranteePrincipal="arn:aws:iam::111122223333:role/report-worker-role",
    Operations=["Decrypt"],
)
print(grant["GrantId"])

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, CreateGrantCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
const grant = await kms.send(new CreateGrantCommand({
  KeyId: "alias/app-config-key",
  GranteePrincipal: "arn:aws:iam::111122223333:role/report-worker-role",
  Operations: ["Decrypt"],
}));
console.log(grant.GrantId);

A grant adds permission on top of the key policy; it never requires editing the key policy document itself.
Operations is an explicit allow-list - grant only what the principal needs, such as ["Decrypt"].
Revoke with RevokeGrant using the returned GrantId when access is no longer needed.

Related: Grants & Key Policies for Delegated Access - grants versus key policies in depth.

8. Encrypt with encryption context for auditability

Bind a ciphertext to metadata that must match again on decrypt.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
ctx = {"tenant": "acme-corp"}
resp = kms.encrypt(
    KeyId="alias/app-config-key",
    Plaintext=b"tenant-secret",
    EncryptionContext=ctx,
)
# Decrypt must pass the identical context or the call fails.
kms.decrypt(CiphertextBlob=resp["CiphertextBlob"], EncryptionContext=ctx)

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, EncryptCommand, DecryptCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
const ctx = { tenant: "acme-corp" };
const resp = await kms.send(new EncryptCommand({
  KeyId: "alias/app-config-key",
  Plaintext: new TextEncoder().encode("tenant-secret"),
  EncryptionContext: ctx,
}));
// Decrypt must pass the identical context or the call fails.
await kms.send(new DecryptCommand({ CiphertextBlob: resp.CiphertextBlob, EncryptionContext: ctx }));

Encryption context is authenticated but not encrypted - it shows up in plaintext in CloudTrail, so never put secrets in it.
A mismatched or missing context on decrypt raises InvalidCiphertextException.
Use it to bind ciphertext to a tenant, resource ARN, or purpose so a stolen blob cannot be replayed in the wrong context.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Prerequisites

Install the SDK: Python pip install boto3 (1.43.x, Python 3.10+) or Node.js npm install @aws-sdk/client-kms (AWS SDK v3, Node 18+).
Credentials available through the default provider chain (environment variables, ~/.aws/credentials, or an attached role).
An IAM principal with kms:CreateKey, kms:Encrypt, kms:Decrypt, and kms:CreateAlias permissions, or an admin who can grant them.

Basic Examples

1. Create a symmetric key

Start with the default key type - it covers almost all encrypt/decrypt use cases.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
key = kms.create_key(
    Description="app-config-key",
    KeySpec="SYMMETRIC_DEFAULT",
    KeyUsage="ENCRYPT_DECRYPT",
)
key_id = key["KeyMetadata"]["KeyId"]
print(key_id)

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, CreateKeyCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
const key = await kms.send(new CreateKeyCommand({
  Description: "app-config-key",
  KeySpec: "SYMMETRIC_DEFAULT",
  KeyUsage: "ENCRYPT_DECRYPT",
}));
const keyId = key.KeyMetadata?.KeyId;
console.log(keyId);

SYMMETRIC_DEFAULT is AES-256-GCM, the right choice unless you specifically need asymmetric signing or encryption.
KeyUsage: ENCRYPT_DECRYPT is the default and cannot be changed after creation.
The returned KeyId is a UUID; you will almost always want an alias on top of it (example 2).

Related: KMS's Envelope-Encryption Model - what this key actually does under the hood.

2. Give the key a friendly alias

Aliases decouple your code from raw key IDs.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
kms.create_alias(AliasName="alias/app-config-key", TargetKeyId="1234abcd-12ab-34cd-56ef-1234567890ab")

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, CreateAliasCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
await kms.send(new CreateAliasCommand({
  AliasName: "alias/app-config-key",
  TargetKeyId: "1234abcd-12ab-34cd-56ef-1234567890ab",
}));

Alias names must start with alias/ and are unique per account per region.
You can pass alias/app-config-key anywhere a KeyId parameter is accepted - Encrypt, Decrypt, GenerateDataKey, all of it.
Repointing an alias to a new key (UpdateAlias) lets you change which physical key your code uses without a deploy.

3. Encrypt a small payload directly

For values under the size limit, skip the data-key dance entirely.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
resp = kms.encrypt(KeyId="alias/app-config-key", Plaintext=b"db-password-123")
ciphertext = resp["CiphertextBlob"]

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, EncryptCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
const resp = await kms.send(new EncryptCommand({
  KeyId: "alias/app-config-key",
  Plaintext: new TextEncoder().encode("db-password-123"),
}));
const ciphertext = resp.CiphertextBlob;

Plaintext must be bytes, not a string - encode it first in both SDKs.
Direct Encrypt is capped near 4KB for symmetric keys; use GenerateDataKey for anything larger.
CiphertextBlob is opaque binary - store it as-is (e.g., base64 in a text column).

4. Decrypt that payload back

Decrypt only needs the blob - not the key ID.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
resp = kms.decrypt(CiphertextBlob=ciphertext)
plaintext = resp["Plaintext"].decode("utf-8")
print(plaintext)

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, DecryptCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
const resp = await kms.send(new DecryptCommand({ CiphertextBlob: ciphertext }));
const plaintext = new TextDecoder().decode(resp.Plaintext);
console.log(plaintext);

The blob embeds which CMK encrypted it, so Decrypt resolves that automatically for single-region keys.
Passing a KeyId to Decrypt is optional but recommended as a defense-in-depth check that the ciphertext came from the key you expect.
A failed decrypt (wrong account, revoked access, tampered blob) raises AccessDeniedException or InvalidCiphertextException, not a silent wrong answer.

5. Check a key's status

Read key state before you build automation around it.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
desc = kms.describe_key(KeyId="alias/app-config-key")["KeyMetadata"]
print(desc["KeyState"], desc["KeySpec"], desc["KeyUsage"])

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, DescribeKeyCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
const desc = (await kms.send(new DescribeKeyCommand({ KeyId: "alias/app-config-key" }))).KeyMetadata;
console.log(desc?.KeyState, desc?.KeySpec, desc?.KeyUsage);

KeyState is typically Enabled; it can also be Disabled, PendingDeletion, or PendingImport.
A key in PendingDeletion still exists but rejects Encrypt/Decrypt - check this before an outage surprises you.
DescribeKey needs only kms:DescribeKey and works with either a key ID or an alias.

Intermediate Examples

6. Enable automatic key rotation

Symmetric CMKs can rotate their backing key material once a year with no code changes.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
kms.enable_key_rotation(KeyId="alias/app-config-key")
status = kms.get_key_rotation_status(KeyId="alias/app-config-key")
print(status["KeyRotationEnabled"])

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, EnableKeyRotationCommand, GetKeyRotationStatusCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
await kms.send(new EnableKeyRotationCommand({ KeyId: "alias/app-config-key" }));
const status = await kms.send(new GetKeyRotationStatusCommand({ KeyId: "alias/app-config-key" }));
console.log(status.KeyRotationEnabled);

Rotation is only available for symmetric, customer-managed CMKs with Origin: AWS_KMS.
Old key material is retained internally so ciphertext encrypted before rotation still decrypts correctly.
Your alias and KeyId never change across a rotation - callers notice nothing.

Related: Automatic Key Rotation & Multi-Region Keys - rotation schedules in depth.

7. Delegate access with a grant instead of editing the key policy

Grants let a specific principal use the key for specific operations, revocable independently.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
grant = kms.create_grant(
    KeyId="alias/app-config-key",
    GranteePrincipal="arn:aws:iam::111122223333:role/report-worker-role",
    Operations=["Decrypt"],
)
print(grant["GrantId"])

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, CreateGrantCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
const grant = await kms.send(new CreateGrantCommand({
  KeyId: "alias/app-config-key",
  GranteePrincipal: "arn:aws:iam::111122223333:role/report-worker-role",
  Operations: ["Decrypt"],
}));
console.log(grant.GrantId);

A grant adds permission on top of the key policy; it never requires editing the key policy document itself.
Operations is an explicit allow-list - grant only what the principal needs, such as ["Decrypt"].
Revoke with RevokeGrant using the returned GrantId when access is no longer needed.

Related: Grants & Key Policies for Delegated Access - grants versus key policies in depth.

8. Encrypt with encryption context for auditability

Bind a ciphertext to metadata that must match again on decrypt.

# --- Python (boto3) ---
import boto3
 
kms = boto3.client("kms", region_name="us-east-1")
ctx = {"tenant": "acme-corp"}
resp = kms.encrypt(
    KeyId="alias/app-config-key",
    Plaintext=b"tenant-secret",
    EncryptionContext=ctx,
)
# Decrypt must pass the identical context or the call fails.
kms.decrypt(CiphertextBlob=resp["CiphertextBlob"], EncryptionContext=ctx)

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, EncryptCommand, DecryptCommand } from "@aws-sdk/client-kms";
 
const kms = new KMSClient({ region: "us-east-1" });
const ctx = { tenant: "acme-corp" };
const resp = await kms.send(new EncryptCommand({
  KeyId: "alias/app-config-key",
  Plaintext: new TextEncoder().encode("tenant-secret"),
  EncryptionContext: ctx,
}));
// Decrypt must pass the identical context or the call fails.
await kms.send(new DecryptCommand({ CiphertextBlob: resp.CiphertextBlob, EncryptionContext: ctx }));

Encryption context is authenticated but not encrypted - it shows up in plaintext in CloudTrail, so never put secrets in it.
A mismatched or missing context on decrypt raises InvalidCiphertextException.
Use it to bind ciphertext to a tenant, resource ARN, or purpose so a stolen blob cannot be replayed in the wrong context.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

KMS Basics

Search Documentation

KMS Basics