KMS via SDK Best Practices

Q: Why is envelope encryption the standard for large payloads?

Direct Encrypt caps near 4KB for symmetric keys. Envelope encryption calls KMS once per object (for the data key) regardless of payload size, then does unlimited-size AES-GCM work locally.

Q: How often should I audit KMS access?

On a recurring cadence, not once. Review CloudTrail, run ListGrants to prune stale delegations, and confirm rotation and multi-region settings still match your DR plan.

A working checklist of KMS habits that keep encryption secure, cheap, and easy to operate at scale.

Each rule is stated positively, with a one-line reason and how to enforce it.

How to Use This List

Walk it top to bottom when standing up a new KMS integration or reviewing an old one.
Treat each unchecked box as a finding to fix or consciously accept.
Categories are ordered by leverage - key design first, then access control, then operations.
Re-run the audit categories on a recurring cadence, not just once.
Wire the checkable rules into CI or an ADR so they do not regress.

A - Key Design

Default to symmetric SYMMETRIC_DEFAULT keys. It covers nearly all use cases at lower latency than asymmetric operations.
Reach for asymmetric only when the requirement is real. Use it when an outside party must encrypt or verify without AWS credentials.
Choose KeyUsage carefully at creation. KeyUsage and KeySpec are immutable - a wrong choice means creating a new key and migrating.
Use aliases, never raw key IDs, in application code. An alias can be repointed later; a hardcoded key ID cannot.
Enable a multi-region key upfront if DR is plausible. MultiRegion cannot be added after creation.

# --- Python (boto3) ---
import boto3
kms = boto3.client("kms")
key = kms.create_key(KeySpec="SYMMETRIC_DEFAULT", KeyUsage="ENCRYPT_DECRYPT")
kms.create_alias(AliasName="alias/app-secrets-key", TargetKeyId=key["KeyMetadata"]["KeyId"])

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, CreateKeyCommand, CreateAliasCommand } from "@aws-sdk/client-kms";
const kms = new KMSClient({});
const key = await kms.send(new CreateKeyCommand({ KeySpec: "SYMMETRIC_DEFAULT", KeyUsage: "ENCRYPT_DECRYPT" }));
await kms.send(new CreateAliasCommand({ AliasName: "alias/app-secrets-key", TargetKeyId: key.KeyMetadata!.KeyId! }));

B - Envelope Encryption

Never send large payloads to direct Encrypt. It caps near 4KB for symmetric keys; anything bigger needs a data key.
Use GenerateDataKey for anything larger than a few kilobytes. Encrypt locally with AES-GCM using the returned plaintext key.
Discard the plaintext data key immediately after use. Only the ciphertext blob is ever safe to persist.
Store the AES-GCM nonce and auth tag with the ciphertext. Without them, even the correct data key cannot decrypt.
Use GenerateDataKeyWithoutPlaintext when pre-staging blobs. Skip returning plaintext until the point you actually encrypt.

{
  "note": "Storage record shape for envelope-encrypted data",
  "ciphertextBlob": "<base64 blob from GenerateDataKey>",
  "nonce": "<base64 12-byte AES-GCM nonce>",
  "authTag": "<base64 AES-GCM auth tag>",
  "data": "<base64 encrypted payload>"
}

C - Access Control

Keep the root-account statement in every key policy. Removing it can permanently lock everyone out with no recovery path.
Prefer grants over key policy edits for temporary access. Grants are independently revocable and don't require touching a shared document.
Scope grants to the exact Operations a principal needs. List ["Decrypt"], not a broader set, per grantee.
Pass GrantToken on the call immediately following CreateGrant. New grants can take a moment to propagate; the token proves it exists now.
Give each workload its own principal and its own grant. A single shared grant across services blurs the audit trail.

# --- Python (boto3) ---
grant = kms.create_grant(
    KeyId="alias/app-secrets-key",
    GranteePrincipal="arn:aws:iam::111122223333:role/worker-role",
    Operations=["Decrypt"],
)

// --- TypeScript (AWS SDK v3) ---
const grant = await kms.send(new CreateGrantCommand({
  KeyId: "alias/app-secrets-key",
  GranteePrincipal: "arn:aws:iam::111122223333:role/worker-role",
  Operations: ["Decrypt"],
}));

D - Rotation & Resilience

Enable automatic rotation on every long-lived symmetric CMK. One call, transparent to callers, old ciphertext still decrypts.
Verify rotation status, don't assume it. GetKeyRotationStatus confirms it actually took effect.
Set MultiRegion=true at creation if cross-region decrypt is plausible. It cannot be added to an existing key later.
Replicate keys before you need them, not during an incident. Set up DR key replicas as part of normal provisioning, not emergency response.
Never assume rotation changes the key ID or ARN. Application code and IaC references stay stable across a rotation event.

E - Auditability & Encryption Context

Attach encryption context to encrypt/decrypt calls. It binds ciphertext to metadata like a tenant ID and must match exactly on decrypt.
Never put secrets in encryption context. It is authenticated but not encrypted, and appears in CloudTrail logs in plaintext.
Log CloudTrail events for every KMS key. It is the authoritative record of who called what, and with which encryption context.
Periodically audit standing grants. Run ListGrants and revoke anything no longer tied to an active workload.
Document any required key policy wildcard. When a statement genuinely needs a broad Resource or Principal, note why for reviewers.

FAQs

Why default to symmetric keys instead of asymmetric?

Symmetric operations are faster and cover nearly every encryption use case within AWS. Asymmetric keys add value only when an outside party must encrypt or verify without AWS credentials.

Why is envelope encryption the standard for large payloads?

Direct Encrypt caps near 4KB for symmetric keys. Envelope encryption calls KMS once per object (for the data key) regardless of payload size, then does unlimited-size AES-GCM work locally.

What is the biggest risk with the plaintext data key?

Persisting it anywhere - logs, disk, a cache - defeats the purpose of envelope encryption. Scope it to the smallest code block and discard it right after use.

When should I use a grant instead of editing the key policy?

Whenever access is temporary, per-workload, or needs independent revocation. Grants avoid coordinating edits to a document other teams or automations may also depend on.

What happens if I remove the root-account statement from a key policy?

You risk permanently locking every principal, including admins, out of the key - there is no external recovery path for a CMK's own policy. Always keep a root-account statement unless you have a tested plan.

Does key rotation require any code changes?

No. Rotation is transparent - the key ID, ARN, and alias stay the same, and old ciphertext continues to decrypt because KMS retains prior key material internally.

Why should I set MultiRegion at key creation instead of later?

Because it cannot be changed after the fact. If cross-region decrypt for DR or a global application is even plausible, provision the key as multi-region from the start.

Is encryption context sensitive data?

No - treat it as metadata only. It is authenticated (must match on decrypt) but not encrypted, and it appears in plaintext in CloudTrail logs.

How often should I audit KMS access?

On a recurring cadence, not once. Review CloudTrail, run ListGrants to prune stale delegations, and confirm rotation and multi-region settings still match your DR plan.

KMS's Envelope-Encryption Model - the concepts these rules protect.
Envelope Encryption with Data Key Generation - the pattern behind rule category B.
Grants & Key Policies for Delegated Access - the access-control model behind category C.
Automatic Key Rotation & Multi-Region Keys - the operational habits behind category D.

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 via SDK Best Practices

A working checklist of KMS habits that keep encryption secure, cheap, and easy to operate at scale.

Each rule is stated positively, with a one-line reason and how to enforce it.

How to Use This List

Walk it top to bottom when standing up a new KMS integration or reviewing an old one.
Treat each unchecked box as a finding to fix or consciously accept.
Categories are ordered by leverage - key design first, then access control, then operations.
Re-run the audit categories on a recurring cadence, not just once.
Wire the checkable rules into CI or an ADR so they do not regress.

A - Key Design

Default to symmetric SYMMETRIC_DEFAULT keys. It covers nearly all use cases at lower latency than asymmetric operations.
Reach for asymmetric only when the requirement is real. Use it when an outside party must encrypt or verify without AWS credentials.
Choose KeyUsage carefully at creation. KeyUsage and KeySpec are immutable - a wrong choice means creating a new key and migrating.
Use aliases, never raw key IDs, in application code. An alias can be repointed later; a hardcoded key ID cannot.
Enable a multi-region key upfront if DR is plausible. MultiRegion cannot be added after creation.

# --- Python (boto3) ---
import boto3
kms = boto3.client("kms")
key = kms.create_key(KeySpec="SYMMETRIC_DEFAULT", KeyUsage="ENCRYPT_DECRYPT")
kms.create_alias(AliasName="alias/app-secrets-key", TargetKeyId=key["KeyMetadata"]["KeyId"])

// --- TypeScript (AWS SDK v3) ---
import { KMSClient, CreateKeyCommand, CreateAliasCommand } from "@aws-sdk/client-kms";
const kms = new KMSClient({});
const key = await kms.send(new CreateKeyCommand({ KeySpec: "SYMMETRIC_DEFAULT", KeyUsage: "ENCRYPT_DECRYPT" }));
await kms.send(new CreateAliasCommand({ AliasName: "alias/app-secrets-key", TargetKeyId: key.KeyMetadata!.KeyId! }));

B - Envelope Encryption

Never send large payloads to direct Encrypt. It caps near 4KB for symmetric keys; anything bigger needs a data key.
Use GenerateDataKey for anything larger than a few kilobytes. Encrypt locally with AES-GCM using the returned plaintext key.
Discard the plaintext data key immediately after use. Only the ciphertext blob is ever safe to persist.
Store the AES-GCM nonce and auth tag with the ciphertext. Without them, even the correct data key cannot decrypt.
Use GenerateDataKeyWithoutPlaintext when pre-staging blobs. Skip returning plaintext until the point you actually encrypt.

{
  "note": "Storage record shape for envelope-encrypted data",
  "ciphertextBlob": "<base64 blob from GenerateDataKey>",
  "nonce": "<base64 12-byte AES-GCM nonce>",
  "authTag": "<base64 AES-GCM auth tag>",
  "data": "<base64 encrypted payload>"
}

C - Access Control

Keep the root-account statement in every key policy. Removing it can permanently lock everyone out with no recovery path.
Prefer grants over key policy edits for temporary access. Grants are independently revocable and don't require touching a shared document.
Scope grants to the exact Operations a principal needs. List ["Decrypt"], not a broader set, per grantee.
Pass GrantToken on the call immediately following CreateGrant. New grants can take a moment to propagate; the token proves it exists now.
Give each workload its own principal and its own grant. A single shared grant across services blurs the audit trail.

# --- Python (boto3) ---
grant = kms.create_grant(
    KeyId="alias/app-secrets-key",
    GranteePrincipal="arn:aws:iam::111122223333:role/worker-role",
    Operations=["Decrypt"],
)

// --- TypeScript (AWS SDK v3) ---
const grant = await kms.send(new CreateGrantCommand({
  KeyId: "alias/app-secrets-key",
  GranteePrincipal: "arn:aws:iam::111122223333:role/worker-role",
  Operations: ["Decrypt"],
}));

D - Rotation & Resilience

Enable automatic rotation on every long-lived symmetric CMK. One call, transparent to callers, old ciphertext still decrypts.
Verify rotation status, don't assume it. GetKeyRotationStatus confirms it actually took effect.
Set MultiRegion=true at creation if cross-region decrypt is plausible. It cannot be added to an existing key later.
Replicate keys before you need them, not during an incident. Set up DR key replicas as part of normal provisioning, not emergency response.
Never assume rotation changes the key ID or ARN. Application code and IaC references stay stable across a rotation event.

E - Auditability & Encryption Context

Attach encryption context to encrypt/decrypt calls. It binds ciphertext to metadata like a tenant ID and must match exactly on decrypt.
Never put secrets in encryption context. It is authenticated but not encrypted, and appears in CloudTrail logs in plaintext.
Log CloudTrail events for every KMS key. It is the authoritative record of who called what, and with which encryption context.
Periodically audit standing grants. Run ListGrants and revoke anything no longer tied to an active workload.
Document any required key policy wildcard. When a statement genuinely needs a broad Resource or Principal, note why for reviewers.

FAQs

Why default to symmetric keys instead of asymmetric?

Symmetric operations are faster and cover nearly every encryption use case within AWS. Asymmetric keys add value only when an outside party must encrypt or verify without AWS credentials.

Why is envelope encryption the standard for large payloads?

Direct Encrypt caps near 4KB for symmetric keys. Envelope encryption calls KMS once per object (for the data key) regardless of payload size, then does unlimited-size AES-GCM work locally.

What is the biggest risk with the plaintext data key?

Persisting it anywhere - logs, disk, a cache - defeats the purpose of envelope encryption. Scope it to the smallest code block and discard it right after use.

When should I use a grant instead of editing the key policy?

Whenever access is temporary, per-workload, or needs independent revocation. Grants avoid coordinating edits to a document other teams or automations may also depend on.

What happens if I remove the root-account statement from a key policy?

Does key rotation require any code changes?

No. Rotation is transparent - the key ID, ARN, and alias stay the same, and old ciphertext continues to decrypt because KMS retains prior key material internally.

Why should I set MultiRegion at key creation instead of later?

Because it cannot be changed after the fact. If cross-region decrypt for DR or a global application is even plausible, provision the key as multi-region from the start.

Is encryption context sensitive data?

No - treat it as metadata only. It is authenticated (must match on decrypt) but not encrypted, and it appears in plaintext in CloudTrail logs.

How often should I audit KMS access?

On a recurring cadence, not once. Review CloudTrail, run ListGrants to prune stale delegations, and confirm rotation and multi-region settings still match your DR plan.

KMS's Envelope-Encryption Model - the concepts these rules protect.
Envelope Encryption with Data Key Generation - the pattern behind rule category B.
Grants & Key Policies for Delegated Access - the access-control model behind category C.
Automatic Key Rotation & Multi-Region Keys - the operational habits behind category D.

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 via SDK Best Practices

Buscar en la documentación

KMS via SDK Best Practices