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.
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.
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"]
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.
Generate
A single GenerateDataKey call produces both plaintext and encrypted forms of a fresh symmetric key.
Encrypt Locally
Actual object encryption happens client-side using standard, fast symmetric cryptography.
Store Together
The encrypted object and its encrypted data key are stored side by side, forming a self-contained encrypted package.
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 Type | Visible to Customer? | Custom Key Policy? | Best Fit |
|---|---|---|---|
| AWS-owned | No | No | Default, zero-configuration baseline encryption |
| AWS-managed | Yes | No | Convenient default encryption with some visibility |
| Customer-managed | Yes | Yes | Compliance-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.
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.
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.
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
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.
Audit Trail
Every cryptographic and administrative operation against a key is logged in CloudTrail with full principal identity.
Quota Monitoring
CloudWatch request-rate metrics provide early warning before a workload hits API throttling.
Anomaly Review
Unexpected principals or unusual usage volume against a sensitive key surfaces directly from CloudTrail analysis.
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.
Per-Workload Key Separation
Distinct customer-managed keys per application or data-sensitivity tier limit blast radius and simplify per-workload access auditing.
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.
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.
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.
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.
13Frequently Asked Questions
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.