AWS KMS, Under the Hood

AWS KMS, Under the Hood

An expert-level walkthrough of how envelope encryption, HSM-backed key material, and the interaction between key policies and IAM actually secure data at rest across AWS — for engineers who already know what a KMS key is, and want to understand why almost nothing you encrypt is ever actually encrypted directly by KMS itself.

The single most counterintuitive fact about AWS KMS is that it almost never encrypts your actual data. Every large object — an S3 file, an EBS volume, a database snapshot — is encrypted locally, by the calling service or SDK, using a fast symmetric key that KMS generates and hands over once; KMS itself is used sparingly, to protect that one small data key rather than the potentially enormous payload it protects. This pattern, called envelope encryption, is the entire architectural reason KMS can be both extremely secure (the actual signing key material never leaves AWS-managed hardware security modules) and practically fast enough for petabyte-scale workloads. This guide skips the “what is a KMS key” introduction and goes straight into the advanced mechanics: how envelope encryption actually works end to end, how key policies and IAM policies combine (and sometimes conflict) to control access, how multi-region keys and automatic rotation behave under the hood, and where teams misconfigure key policies badly enough to either lock themselves out of their own data or grant far more access than intended.

1Internal Working: Envelope Encryption and the HSM Boundary

KMS’s core security guarantee rests on a single, non-negotiable architectural boundary: the plaintext key material of a KMS key never leaves the hardware security modules it lives in, which is precisely why envelope encryption exists as the mechanism for protecting anything larger than a few kilobytes.

A KMS key’s cryptographic material is generated and stored inside FIPS 140-2 validated hardware security modules (HSMs), and by design that plaintext key material is never exported, never visible to AWS operators, and never directly used to encrypt an arbitrary large payload over the network. Instead, when an application needs to encrypt a large object, it calls `GenerateDataKey`, and KMS returns two things: a plaintext data key (for immediate local use) and that same data key encrypted under the KMS key (for storage alongside the encrypted object). The application encrypts its actual data locally, in memory, using the fast plaintext data key, then discards the plaintext data key immediately and stores only the encrypted version alongside the ciphertext.

Analogy

Think of the KMS key as a bank’s master vault key that never physically leaves the vault. Rather than using that master key to lock every single customer’s individual safety deposit box directly, the bank issues each customer a disposable combination lock (the data key) for their own box, then locks a copy of that combination itself inside the vault using the master key. Opening any customer’s box later means the bank retrieves and unlocks that specific stored combination with the master key — the master key itself never has to physically touch every box.

Decryption reverses this exactly: the application sends the encrypted data key to KMS via `Decrypt`, KMS uses the HSM-protected key material to decrypt it and returns the plaintext data key, and the application uses that plaintext data key locally to decrypt the actual object — again discarding the plaintext data key immediately afterward. At no point does the large object’s actual content, or even its encrypted form, ever pass through KMS itself; KMS’s entire role is protecting the small data key, not the payload.

!
Advanced Gotcha

Engineers new to KMS sometimes assume calling `Encrypt` directly against KMS is the standard pattern for all encryption needs — it is, but only for payloads under KMS’s direct encryption size limit (a few kilobytes), making it suitable for encrypting secrets or small configuration values, never for encrypting a multi-gigabyte object directly, which must always go through the envelope-encryption `GenerateDataKey` pattern instead.

2Data Flow: The Full Envelope Encryption Lifecycle

Tracing a single object from plaintext through encryption, storage, and eventual decryption reveals exactly which parts of the process happen locally at the client and which parts genuinely require a round trip to KMS.

flowchart TD
    A["Application requests GenerateDataKey from KMS"] --> B["KMS returns plaintext data key + encrypted data key"]
    B --> C["Application encrypts object locally using plaintext data key"]
    C --> D["Plaintext data key discarded from memory immediately"]
    D --> E["Encrypted object + encrypted data key stored together"]
    E --> F["Later: application retrieves encrypted object + encrypted data key"]
    F --> G["Application calls Decrypt, sending encrypted data key to KMS"]
    G --> H["KMS uses HSM-protected key material to decrypt the data key"]
    H --> I["KMS returns plaintext data key to application"]
    I --> J["Application decrypts object locally, then discards plaintext data key"]
    
Fig. 1 — The complete envelope-encryption round trip: only the small data key ever touches KMS directly, never the object itself

Only two network round trips to KMS occur in this entire lifecycle — once at encryption time to generate the data key, and once at decryption time to unwrap it — regardless of whether the object being protected is one kilobyte or one terabyte. This is precisely why envelope encryption scales to arbitrarily large payloads with no meaningful KMS-side bottleneck: the actual bulk cryptographic work happens locally, using fast, standard symmetric encryption, entirely outside of KMS’s request path.

KMS request quotas apply specifically to these API calls (`GenerateDataKey`, `Decrypt`, `Encrypt`) themselves, not to the volume of data being protected — a service performing millions of small object encryptions per second can genuinely hit these per-second API request quotas even though the underlying data volume might otherwise seem modest, which is precisely the scenario data-key caching (Chapter 6) exists to address.

Stage

Generate

A single GenerateDataKey call produces both plaintext and encrypted forms of a fresh symmetric key.

Stage

Encrypt Locally

Actual object encryption happens client-side using standard, fast symmetric cryptography.

Stage

Store Together

The encrypted object and its encrypted data key are stored side by side, forming a self-contained encrypted package.

Stage

Unwrap on Read

A single Decrypt call against the small encrypted data key is all that’s needed to recover access, regardless of object size.

3Key Types & Ownership: AWS-Owned, AWS-Managed, and Customer-Managed

The three key-ownership tiers trade control, cost, and operational overhead against each other in a genuinely deliberate spectrum, and choosing the wrong tier for a given compliance or auditability requirement is a common, consequential mistake.

AWS-owned keys are used and managed entirely by an AWS service internally, with the customer having no visibility into or control over the key at all — used automatically by some services for baseline default encryption with essentially zero customer-facing configuration. AWS-managed keys are created automatically the first time a customer uses a given service’s default encryption option, are visible in the customer’s account, and rotate automatically on a fixed schedule, but the customer cannot control their key policy or deletion. Customer-managed keys give the customer full control: a fully customizable key policy, optional automatic or manual rotation, explicit control over cross-account grants, and the ability to schedule deletion — the tier required for any workload with a genuine compliance or audit requirement to demonstrate explicit key-level access control.

Key TypeVisible to Customer?Custom Key Policy?Best Fit
AWS-ownedNoNoDefault, zero-configuration baseline encryption
AWS-managedYesNoConvenient default encryption with some visibility
Customer-managedYesYesCompliance-driven, auditable, cross-account access control

Production Example — Regulated Data Isolation

Healthcare and financial services organizations handling regulated data almost universally require customer-managed keys specifically because auditors need to see an explicit, reviewable key policy demonstrating exactly which principals can use a given key to decrypt data — a requirement AWS-managed keys structurally cannot satisfy, since their policies are not customer-editable.

ADR-KMS-03Anti-Pattern
Anti-Pattern

Relying on AWS-managed keys for a workload later found to require detailed, per-principal access audit and revocation capability.

Why It Fails

AWS-managed key policies are not customer-editable, so there is no way to add fine-grained per-principal restrictions or explicit deny statements after the fact — the access model is fixed to what AWS defines for that service’s default encryption.

Better Approach

Default to customer-managed keys proactively for any workload with even a plausible future compliance or fine-grained access requirement, since migrating already-encrypted data to a different key later is a genuinely disruptive re-encryption exercise.

4Advanced Configuration: Key Policies, Grants, and Multi-Region Keys

Access to a customer-managed key is governed by a genuinely distinct combination of the key’s own resource policy and IAM policies, plus a separate, temporary grants mechanism — and multi-region keys solve a replication problem no ordinary key can.

Every customer-managed key has its own key policy, a resource-based policy attached directly to the key, and — unlike most AWS resource policies — a KMS key policy is mandatory and evaluated as the primary gate: unless the key policy explicitly allows the AWS account’s IAM policies to govern access (the common default statement enabling this), IAM policies alone are insufficient to grant access to the key at all. This dual-gate model is a frequent source of confusion for engineers used to services where IAM policies alone are sufficient.

Grants provide a separate, more dynamic access mechanism, ideal for temporarily and programmatically delegating specific key permissions to a principal — commonly used by AWS services internally to grant themselves exactly the permissions needed to use a customer’s key for a specific operation, without modifying the key policy itself, and grants can be created and revoked far more dynamically than key policy edits typically are in practice.

Multi-Region keys solve the specific problem of needing the same underlying key material available in multiple AWS Regions — a primary key in one region and a replica in another share the same key material and key ID, letting an encrypted object created in one region be decrypted in another without any cross-region KMS API call or re-encryption step, which matters enormously for multi-region disaster-recovery architectures where encrypted backups must remain decryptable after a regional failover.

i
Advanced Tip

Multi-Region keys are related but never identical to ordinary independent keys created separately in each region — they explicitly share key material by design specifically to support this cross-region decrypt-without-re-encryption pattern, and choosing between them should be driven entirely by whether that specific cross-region decryption need genuinely exists.

5High Availability & Reliability

KMS is a highly available, regionally redundant managed service by default, but the reliability considerations that actually require deliberate design are key deletion safeguards and the cross-region availability of encrypted data.

Within a single region, KMS’s underlying HSM infrastructure is redundant across multiple Availability Zones, and this redundancy requires no configuration from the customer — it is simply a property of the managed service. The genuine reliability risk in KMS is not infrastructure failure but irreversible key deletion: deleting a KMS key permanently destroys its key material, and any data encrypted under that key becomes permanently unrecoverable — there is no backup or recovery path for a deleted key’s material, which is precisely why KMS enforces a mandatory waiting period (between 7 and 30 days, configurable) before a scheduled deletion actually takes effect, giving administrators a final window to cancel the deletion if it was made in error.

For genuine multi-region disaster-recovery reliability, ordinary independent per-region keys create a real dependency risk: encrypted data replicated to a disaster-recovery region cannot be decrypted there unless the DR region also has access to the original key, which is exactly the scenario Multi-Region keys from Chapter 4 are designed to eliminate.

7–30 days
Mandatory waiting period before scheduled key deletion completes
Multi-AZ
Built-in HSM redundancy within a region, no configuration required
Irreversible
Data encrypted under a deleted key’s material is permanently unrecoverable

6Performance & Scalability: Request Quotas and Data Key Caching

KMS API request quotas, not encryption throughput, are the actual scalability ceiling most high-volume workloads run into — and the AWS Encryption SDK’s data key caching feature exists specifically to push that ceiling back for workloads that don’t genuinely need a fresh data key per object.

Because encryption throughput itself happens locally (Chapter 1), the practical scaling limit for envelope encryption is the per-second request quota on `GenerateDataKey` and `Decrypt` API calls against a given key. A workload performing extremely frequent, small encryption operations — a high-throughput event-processing pipeline encrypting individual records — can approach or exceed this quota well before running into any actual cryptographic throughput limit.

The AWS Encryption SDK’s data key caching feature directly addresses this: rather than calling `GenerateDataKey` for every single encryption operation, the SDK can safely reuse the same data key across a configurable number of operations or bytes, within a bounded caching window, trading a small, well-understood reduction in cryptographic key diversity for a dramatic reduction in KMS API call volume — the standard mitigation for workloads that would otherwise be quota-bound purely by request rate rather than by any genuine data volume constraint.

Production Example — High-Throughput Event Streaming

Real-time analytics pipelines encrypting millions of small event records per minute adopt data key caching specifically to keep KMS API call volume within quota, accepting a bounded, deliberately configured amount of data-key reuse rather than requesting a brand-new key for every single record.

7Security: The Dual-Gate Access Model and Key Rotation

KMS security combines a mandatory key-policy gate with standard IAM evaluation, plus an automatic key-rotation feature that preserves the ability to decrypt old data even as the underlying key material changes.

As established in Chapter 4, a customer-managed key’s own key policy is the primary access gate — a principal needs both an IAM policy allowing the KMS action and a key policy permitting that principal (directly, or indirectly through the common “enable IAM policies” statement) to use the key, making KMS one of the few AWS services where getting access right genuinely requires reasoning about two independent policy documents together, not just one.

Automatic key rotation, when enabled on a symmetric customer-managed key, generates new backing key material on a schedule while transparently retaining all previous versions of that key material internally — data encrypted under an older rotation version remains decryptable indefinitely, since KMS tracks which specific version of the key material was used for each encryption operation, entirely invisible to the calling application. This means rotation improves cryptographic hygiene without ever requiring the disruptive re-encryption of previously encrypted data.

Key Policy Gate

  • Mandatory resource-level policy on every customer-managed key
  • Must explicitly enable IAM policy evaluation, or IAM alone is insufficient

Automatic Rotation

  • New key material generated on schedule, old versions retained internally
  • Previously encrypted data remains decryptable with zero re-encryption needed
!
Common Trap

Writing an overly restrictive key policy that omits the account’s root principal or the “enable IAM policies” statement can lock every principal in the account out of managing the key entirely, including administrators — key policy edits should always be validated carefully, since an account can genuinely lose all ability to administer a key it created.

8Monitoring, Logging & Metrics

CloudTrail is the primary and, for most compliance frameworks, mandatory observability layer for KMS — every single cryptographic operation against a customer-managed key is individually logged, providing a genuinely complete audit trail of exactly who used which key, when, and for what.

Every `Encrypt`, `Decrypt`, `GenerateDataKey`, and administrative API call (key policy changes, rotation toggling, grant creation) against a KMS key is recorded in CloudTrail with the calling principal’s identity, making it possible to reconstruct a complete usage history for any specific key — a capability many compliance frameworks explicitly require as evidence that encryption key usage is monitored and auditable, not merely configured correctly at a point in time.

CloudWatch metrics complement this audit trail with quota-related visibility — tracking request counts against a key’s API quota specifically helps catch a workload approaching a throttling threshold before it actually starts failing, giving operators time to implement data key caching or request a quota increase proactively rather than reactively.

1

Audit Trail

Every cryptographic and administrative operation against a key is logged in CloudTrail with full principal identity.

2

Quota Monitoring

CloudWatch request-rate metrics provide early warning before a workload hits API throttling.

3

Anomaly Review

Unexpected principals or unusual usage volume against a sensitive key surfaces directly from CloudTrail analysis.

4

Compliance Evidence

The CloudTrail record itself often serves directly as auditor-facing evidence of key usage governance.

9Design Patterns & Anti-Patterns

The durable KMS architectures deliberately separate key ownership by workload or sensitivity tier and lean on envelope encryption and data key caching rather than treating KMS as a general-purpose bulk encryption endpoint.

Pattern

Per-Workload Key Separation

Distinct customer-managed keys per application or data-sensitivity tier limit blast radius and simplify per-workload access auditing.

Pattern

Envelope Encryption via SDK

Using the AWS Encryption SDK’s envelope encryption and caching support rather than hand-rolling GenerateDataKey/Decrypt logic reduces implementation risk.

Anti-Pattern

Calling Encrypt Directly on Large Payloads

Attempting to encrypt objects beyond KMS’s direct-encryption size limit fails outright — large payloads must always go through envelope encryption.

Anti-Pattern

One Shared Key for Every Workload

Using a single customer-managed key across unrelated applications makes per-application access auditing and blast-radius containment far harder than necessary.

10Advantages, Disadvantages & Trade-offs

KMS trades a small amount of architectural complexity — envelope encryption, dual policy gates — for HSM-grade key protection and compliance-ready auditability that would be genuinely difficult to build and operate independently.

Advantages

  • HSM-backed key material that never leaves AWS-managed hardware, even to AWS operators
  • Envelope encryption scales to arbitrarily large payloads with minimal KMS-side request overhead
  • Complete, mandatory CloudTrail audit logging of every cryptographic and administrative operation
  • Automatic rotation preserves decryptability of old data without any disruptive re-encryption

Disadvantages

  • Dual key-policy-plus-IAM access model adds genuine complexity compared to IAM-only services
  • API request quotas can become a real scaling constraint for high-frequency, small-object workloads without caching
  • Key deletion is genuinely irreversible, with no backup or recovery path for lost key material
  • Misconfigured key policies can lock an entire account out of a key’s own administration

11Best Practices & Common Mistakes

Nearly every advanced KMS incident traces back to a key-policy misconfiguration, an attempt to bypass envelope encryption for large payloads, or a scheduled key deletion made without fully understanding its permanence.

Use customer-managed keys with explicit, reviewed key policies for any workload with a genuine compliance or audit requirement.
Always validate a key policy edit against the account’s own administrative access before applying it, to avoid accidental account-wide lockout.
Use the AWS Encryption SDK’s envelope encryption support rather than hand-implementing GenerateDataKey/Decrypt logic.
Enable data key caching for high-frequency, small-object encryption workloads approaching KMS API quotas.
Treat scheduled key deletion as genuinely irreversible after its waiting period, and double-check dependent workloads before confirming it.
!
Most Common Mistake

Scheduling deletion of a KMS key still referenced by active encrypted data without first confirming every dependent workload and backup has been identified — once the waiting period elapses and the key is destroyed, every object encrypted under it becomes permanently, unrecoverably inaccessible.

12Real-World & Industry Examples

KMS adoption at the advanced level clusters around regulated industries needing demonstrable, auditable key control, and high-throughput platforms needing envelope encryption’s scalability without sacrificing HSM-grade protection.

Financial Services Regulatory Compliance

Financial institutions use customer-managed keys with tightly scoped key policies and dedicated per-application keys specifically so auditors can review, per key, exactly which principals were ever permitted to use it — a level of granular, reviewable evidence AWS-managed keys cannot provide.

Cross-Account Data Sharing

Organizations sharing encrypted data across AWS accounts (a data lake shared between a producing team’s account and a consuming analytics account) use customer-managed key policies and grants to explicitly permit cross-account decryption without duplicating or exporting any key material.

Multi-Region Disaster Recovery

Enterprises with strict recovery-time requirements adopt Multi-Region keys specifically so encrypted backups replicated to a disaster-recovery region remain immediately decryptable there, without any cross-region KMS dependency or re-encryption step during an actual failover event.

“KMS’s real achievement isn’t encrypting data — it’s making HSM-grade key protection invisible enough that ordinary application code can use it correctly, at any scale, without ever touching the key material itself.”

13Frequently Asked Questions

Q1Can KMS encrypt large files directly?
No — direct Encrypt calls are limited to a few kilobytes of data, suitable for secrets or configuration values; anything larger must use envelope encryption via GenerateDataKey, with the actual object encrypted locally using the returned plaintext data key.
Q2What happens to data encrypted under an older rotated key version?
It remains fully decryptable indefinitely — KMS retains all previous backing key material internally and automatically uses the correct version for each decryption, with no application-level awareness or action required.
Q3Why does an IAM policy that clearly allows kms:Decrypt still result in access denied?
Because KMS requires both an IAM policy allowing the action and the key’s own key policy permitting that principal (directly or via the “enable IAM policies” statement) to use the key — an IAM allow alone is not sufficient without the corresponding key-policy permission.
Q4Can a scheduled key deletion be canceled?
Yes, but only during the mandatory waiting period (7 to 30 days) before the deletion actually completes; once that window elapses and the key material is destroyed, the deletion is permanent and cannot be reversed by any means.
Q5Is a Multi-Region key the same as creating identical keys independently in two regions?
No — independently created keys, even with identical configuration, have entirely distinct key material and cannot decrypt each other’s ciphertext; Multi-Region keys deliberately share the same underlying key material across their primary and replica keys specifically to enable cross-region decryption without re-encryption.

14Summary and Key Takeaways

Key Takeaways

  • Envelope encryption, not direct encryption, is how KMS actually protects most data — KMS secures a small data key, and the calling application encrypts the actual payload locally.
  • Key material never leaves KMS’s HSM boundary, which is the foundational security guarantee everything else in the service builds on.
  • Customer-managed keys are the only tier offering a fully customizable key policy, essential for any genuine compliance or audit requirement.
  • Access to a customer-managed key requires both an IAM allow and a key-policy allow — a dual-gate model unlike most other AWS services.
  • Automatic rotation preserves decryptability of all previously encrypted data with zero re-encryption required, entirely transparent to applications.
  • Multi-Region keys solve cross-region decryption specifically by sharing key material — a genuinely different mechanism from independently created regional keys.
  • Key deletion is permanent and unrecoverable — the mandatory waiting period is the only safeguard, and it should never be treated as a formality.