Know when AWS KMS encryption needs an envelope

A payload limit tells you which operation you are choosing

AWS KMS Encrypt is a small-message operation with a limit determined by the key type and encryption algorithm. It is not a general API for sending an arbitrarily large application document to KMS. For larger payloads, an envelope design uses a data key to encrypt the payload locally and uses a wrapping key, such as a KMS key, to protect that data key. Choose the construction before designing storage or retry behavior around the wrong operation. ^[1][2]

The Encrypt API reference allows at most 4,096 plaintext bytes with a symmetric encryption KMS key using SYMMETRIC_DEFAULT. With RSAES_OAEP_SHA_256, the documented limits are 190 bytes for RSA_2048, 318 for RSA_3072 and 446 for RSA_4096. The chart shows those selected combinations. These values are plaintext input limits, not ciphertext sizes, key-strength scores or maximum sizes for data encrypted locally with an envelope library. ^[1]

A hypothetical document service illustrates the decision. The application needs to encrypt a document larger than the direct Encrypt limit. Splitting it into arbitrary chunks and inventing a custom scheme around repeated KMS calls would create message-format and integrity questions that a supported envelope-encryption library already addresses. The proposed design uses an established library, stores its encrypted message and records the wrapping-key dependencies needed for later decryption. It is not a benchmark or a tested customer deployment.

Small payload size alone does not settle every design choice. The application also needs a supported key type, appropriate permissions, an available key state and a suitable encryption context where that feature is supported. The API reference documents those conditions separately from size. A request below the maximum can still be invalid or unauthorized. Do not treat fitting under a bar in the chart as proof that the application is correctly configured. ^[1]

The chart intentionally excludes the API's SHA-1 variants and Region-specific SM2 option. Its scope is the symmetric default and RSA OAEP with SHA-256, which are enough to explain the direct-encryption boundary. Keep the selected algorithms visible when reusing the figure, rather than describing the values as an exhaustive list of every KMS encryption mode or a recommendation based only on payload capacity.

Source. AWS KMS Encrypt API ^[1]. Sources checked August 28, 2026. AWS KMS Encrypt maximum plaintext input sizes for the selected key and algorithm combinations, checked August 28, 2026. Units are plaintext bytes. These are not ciphertext sizes, bulk envelope-encryption limits or security-strength scores.

Method. Original bar chart of the API reference's maximum-data-size list. Byte values are unchanged; RSA OAEP SHA-256 variants and SYMMETRIC_DEFAULT are the stated scope. The selected operation must also meet key-state, permission and algorithm-compatibility requirements. An envelope design encrypts application data with a data key and is not bounded by these direct Encrypt plaintext values in the same way. No performance, price or throughput measurements are shown.

Accessible table and figure data

Figure 1 accessible table

Key specification	Algorithm	Maximum plaintext bytes
Symmetric encryption key	SYMMETRIC_DEFAULT	4096
RSA_2048	RSAES_OAEP_SHA_256	190
RSA_3072	RSAES_OAEP_SHA_256	318
RSA_4096	RSAES_OAEP_SHA_256	446

Figure 1 accessible table

Key specification	Algorithm	Maximum plaintext bytes
Symmetric encryption key	SYMMETRIC_DEFAULT	4096
RSA_2048	RSAES_OAEP_SHA_256	190
RSA_3072	RSAES_OAEP_SHA_256	318
RSA_4096	RSAES_OAEP_SHA_256	446

Download imageDownload table CSV

Follow the data key rather than sending the whole document to KMS

Envelope encryption separates the key used on the application data from the key used to protect that data key. AWS's KMS and Encryption SDK documentation calls the latter a wrapping key. The application payload is encrypted with a data key, while the encrypted form of the data key is stored with the information needed to recover it under the authorized wrapping-key path. This distinction explains why the direct Encrypt plaintext limit is not the bulk-payload limit of an envelope design. ^[2][6]

GenerateDataKey provides a documented starting point for this pattern. It can return a plaintext data key and a copy encrypted under the specified KMS key. The authorized caller uses the plaintext key for local encryption, then removes it from use as soon as the operation permits. The encrypted copy can be retained with the ciphertext and relevant metadata. Do not store the plaintext data key beside the encrypted document; that would defeat the purpose of protecting it through the wrapping key. ^[4]

Prefer a maintained encryption library that manages the complete encrypted-message construction. The AWS Encryption SDK defines a message format containing ciphertext and required metadata, including encrypted data keys. The application should use supported encryption and decryption APIs rather than inventing its own framing, authentication and key-handling conventions. A diagram of envelope encryption explains the roles; it is not a specification for implementing cryptographic primitives. ^[5][6][7]

Keep the wrapping-key identity explicit. The application needs to know which approved KMS key or keyring configuration may protect its data keys and which identities may invoke the required operations. A permissive decrypt path that accepts any key discovered in an untrusted message can have different authorization implications from a path constrained to an expected wrapping key. Follow the selected SDK's documented keyring and trust configuration rather than assuming that successful cryptography establishes the intended tenant or application boundary. ^[6][7]

Plaintext data keys remain sensitive while the application uses them. The library and runtime determine how memory is allocated and released, so the operating procedure should follow the implementation's supported key-handling behavior. Avoid logging the key, placing it in ordinary telemetry or keeping it in a general application cache without an explicit design. AWS's GenerateDataKey guidance describes removing the plaintext key after use; the article does not claim that every language can guarantee identical memory erasure behavior. ^[4]

Also distinguish the data key from the KMS key material. An envelope operation does not require exporting the KMS wrapping key into the application. The application receives the generated data key under the authorized API contract and later relies on KMS to unwrap the encrypted copy when needed. This separation is central to the design and should remain visible in reviews of data flow, permissions and recovery dependencies. ^[2][4]

The data-flow figure shows those paths separately. It uses a synthetic payload and abstract key representations, with no real key material. The encrypted message carries the protected data-key information needed for the supported decryption process; the plaintext data key is an operational secret used during the local cryptographic operation. The figure describes the construction, not a claim that a particular application's memory handling or key policies have been tested.

Source. AWS KMS concepts ^[2]; AWS KMS GenerateDataKey ^[4]; AWS Encryption SDK message format ^[5]. Sources checked August 28, 2026.

Method. Original conceptual model synthesized from the cited documentation. The relationships and proposed tests explain design choices; they are not measured results or a claim about a deployed environment.

Accessible table and figure data

Figure 2 accessible table

Stage	Plaintext data key	Encrypted data key	Application payload
GenerateDataKey	Returned to authorized caller	Returned under the KMS key	Remains local
Local encryption	Used by the maintained library	Included in encrypted-message metadata	Encrypted locally
Store	Discard after required use	Stored with the encrypted message	Stored as ciphertext
Decrypt	Recovered through authorized unwrap	Supplied to the wrapping-key path	Released only after required authentication and context checks

Figure 2 accessible table

Stage	Plaintext data key	Encrypted data key	Application payload
GenerateDataKey	Returned to authorized caller	Returned under the KMS key	Remains local
Local encryption	Used by the maintained library	Included in encrypted-message metadata	Encrypted locally
Store	Discard after required use	Stored with the encrypted message	Stored as ciphertext
Decrypt	Recovered through authorized unwrap	Supplied to the wrapping-key path	Released only after required authentication and context checks

Download imageDownload table CSV

Authenticate the record's context without putting secrets in it

KMS encryption context is non-secret additional authenticated data for supported symmetric encryption operations. It can bind meaningful key-value information to an encryption operation and can also be used in authorization conditions. It is not an encrypted storage field for sensitive metadata. AWS warns that encryption context can appear in plaintext in CloudTrail logs and other output, so choose values that are appropriate for that visibility. ^[3]

A synthetic record might use a non-secret purpose or tenant reference as context, provided the organization's data-classification rules allow that identifier in logs. The point is to make the expected relationship explicit, not to embed a password, personal record or confidential document title in the context. If an identifier itself is sensitive, use a design approved for that classification rather than assuming that the word encryption makes every parameter confidential.

For direct symmetric KMS encryption, the API requires the same case-sensitive encryption context on decryption when context was used during encryption. A mismatch causes decryption to fail. That is a cryptographic binding property, not a general application permission decision. The application must still decide whether the caller may request the record and whether the supplied context is the context the application expects for that operation. ^[1][3]

The distinction matters when a caller can influence context values. Simply accepting a tenant field from the request and passing it to decryption does not establish that the caller belongs to that tenant. Derive or validate the expected values through the application's authorized request context, then apply the library's supported verification behavior. This is an application-design recommendation based on the separation between authenticated data and authorization; encryption context does not replace the rest of the access-control system.

Do not transfer the direct KMS request rule blindly into every SDK message inspection. The Encryption SDK has its own message format and context-handling behavior, which may include library-managed metadata. Follow the selected SDK's documented method for verifying required context entries before releasing plaintext to the application. State which entries the application requires and what happens when they are missing or unexpected, instead of assuming that every implementation exposes the same comparison API. ^[5][6][7]

Encryption context is not available for the asymmetric KMS Encrypt algorithms in the same way. The API explicitly scopes the parameter to symmetric encryption operations. A design that depends on context binding must therefore choose a compatible operation and supported library construction. Do not present the RSA payload-limit bars as evidence that those algorithms support every symmetric KMS feature. Key type, algorithm and context support are separate parts of the API contract. ^[1][3]

Keep context values stable enough for the intended lifecycle. If the application uses a mutable business label as required context, it needs a documented way to recover the original value when decrypting older records. The exact strategy is application-specific, but the review question is concrete: where will the expected authenticated metadata come from later, and can an authorized reader reproduce it without trusting an unvalidated request field?

Keep enough information to decrypt and recover

Store the library's encrypted message in the form its decryption API expects. The AWS Encryption SDK message format contains more than the application ciphertext; its metadata and encrypted data keys are part of the supported construction. Removing fields because they appear redundant or rebuilding the message from selected pieces can break decryption or discard information the library uses for validation. Use documented serialization and storage paths rather than inventing a smaller unofficial format. ^[5][6]

Separate the message's metadata from the application's index. The application may need a record identifier, access policy and storage location in addition to the encrypted message. Those fields should not be confused with cryptographically authenticated metadata unless the chosen construction actually binds them. A database association between a record and a ciphertext is useful operationally, but the application still needs to validate that the decrypted result belongs to the authorized request.

Record wrapping-key dependencies for recovery. Retaining ciphertext and an encrypted data key is not enough if the required KMS key or authorization path is unavailable. The recovery plan should identify the key, Region and access dependencies relevant to the chosen design, while leaving detailed backup and key-recovery procedures to the appropriate owners. Envelope encryption protects the data key; it does not eliminate the need to maintain the wrapping-key path. ^[2][6]

A change to an alias, keyring configuration or application permission deserves a compatibility review. Determine whether existing messages remain decryptable through the intended authorized path, and test representative synthetic records before broad changes. Do not assume that a successful new encryption proves access to messages created under the earlier configuration. The key and message metadata used for those records may differ.

Keep retention and deletion decisions explicit. The organization should understand which encrypted records depend on a key before changing the key's lifecycle or removing the application's ability to use it. This guide does not prescribe a universal retention period or promise that every key state can be reversed. The practical requirement is an accountable inventory of decryption dependencies, connected to the separate recovery and data-lifecycle procedures.

Test wrong-context and unavailable-key behavior

Use synthetic records and an authorized test key or isolated configuration. Start with a successful encrypt-and-decrypt path using the chosen library, expected context and approved wrapping key. Record the library version and configuration so the result describes a reproducible implementation. A test with another language or keyring type may be useful, but it is not automatically evidence for the production code path.

Then test a context mismatch under the supported API. For a direct symmetric KMS operation, a changed required context should prevent successful decryption under the documented exact-match contract. For an SDK message, verify the application's required-context check according to that SDK's interface. The test should confirm that plaintext is not released to application logic when the required relationship is absent. No actual test result is claimed here. ^[1][3][7]

Test the wrapping-key restriction separately. The application should handle a message or key reference outside its approved configuration according to the supported library and policy. Keep this scoped to controlled fixtures and do not weaken a production key policy to manufacture a failure. The objective is to observe the intended denial and error handling, not to demonstrate broad KMS access.

Exercise an unavailable or unauthorized wrapping-key path through a safe test arrangement. Observe whether the application reports a useful failure, avoids returning unauthenticated or stale plaintext and applies its intended retry behavior. Availability and cryptographic correctness are different concerns. A decrypt failure can be the correct security outcome while still requiring an operational response to restore an authorized dependency.

Also test stored-message integrity and the application's record association. Use the library's supported failure behavior for altered or malformed synthetic messages and confirm that the application does not treat an error as a valid empty record. The exact validation depends on the chosen encrypted-message format. Keep any negative test within the library's contract rather than manipulating real customer ciphertext.

Retain the evidence needed to interpret failures without storing plaintext data keys or sensitive record contents in logs. A useful record can identify the synthetic fixture, library version, expected context, approved key reference and observed outcome. Re-run the affected cases when the SDK, keyring, context policy or storage format changes. This is a proposed acceptance suite, not a security certification of an untested application.

Treat caching as a separate security decision

Data-key caching changes how often an application reuses cryptographic materials and how often it depends on a wrapping-key operation. The AWS Encryption SDK documents caching as a feature with explicit security and implementation considerations. Do not introduce it merely because the direct KMS limit looks inconvenient; payload size and caching are different design questions. Begin with the supported envelope construction, then evaluate whether caching is necessary for the actual workload. ^[8]

Use the controls and limits documented for the selected SDK implementation. Support differs across languages and features, and a setting from one client should not be assumed to exist in another. Any performance or cost benefit needs measurement in the relevant environment. This article presents no throughput, latency or savings benchmark and does not infer one from the number of KMS operations in a conceptual diagram. ^[8]

The resulting decision should explain four things: which operation encrypts the payload, which key protects the data key, which non-secret context the application verifies and which dependencies are needed to decrypt later. The direct Encrypt limits make the first boundary visible. A maintained envelope library, explicit context checks and recovery-aware key ownership make the rest of the construction reviewable.