AWS KMS API, CLI Commands, Throttling, and Data Key Caching

Purpose of This Lesson

This lesson focuses on selected AWS Key Management Service (AWS KMS) API actions and their AWS CLI equivalents, along with the distinction between KMS resource quotas and request quotas. It also covers practical responses to KMS throttling and the role of data key caching. The material is especially relevant to SOA-C03 scenario questions that require selecting the correct KMS operation or mitigation strategy.

Key Concepts

• KMS API actions and CLI commands: AWS KMS operations can be invoked through API actions such as Encrypt and corresponding CLI commands such as aws kms encrypt.
• Symmetric data keys: KMS can generate data keys for encrypting application data outside KMS while using a KMS key to protect the data key.
• Envelope-style workflow: The application uses the plaintext data key to encrypt data, then stores the encrypted data key with the encrypted data. The KMS-protected copy allows the application to recover the data key later.
• Re-encryption: KMS can decrypt and re-encrypt ciphertext within KMS, allowing the protected data to move to a different KMS key or to be re-encrypted under the same key with a different encryption context.
• Resource quotas versus request quotas: Resource quotas limit how many resources can be created, while request quotas limit the rate or volume of API calls.
• Data key caching: The AWS Encryption SDK can cache data keys and related cryptographic material locally when repeated key generation creates unacceptable performance, cost, or resource pressure.

KMS API and CLI Operations

Encrypt

The Encrypt API action, available through the aws kms encrypt CLI command, encrypts small amounts of arbitrary plaintext using a specified KMS key. Suitable examples include personal identifiers, database passwords, and other sensitive values.

KMS encryption can also support moving encrypted data between Regions. The operation is intended for relatively small data values rather than bulk application data.

Decrypt

The Decrypt operation decrypts ciphertext that was produced by KMS through operations such as:

• Encrypt
• GenerateDataKey
• GenerateDataKeyWithoutPlaintext
• GenerateDataKeyPair
• GenerateDataKeyPairWithoutPlaintext

When identifying the correct operation, focus on the source of the ciphertext: KMS Decrypt is used to recover plaintext from ciphertext generated by these KMS operations.

ReEncrypt

ReEncrypt decrypts ciphertext and re-encrypts it entirely within KMS. It is useful when:

• Changing the KMS key that protects existing ciphertext, such as after manually rotating key material or changing the protecting key.
• Re-encrypting under the same KMS key while changing the encryption context.

The defining characteristic is that plaintext does not need to be exposed to the calling application during the transition.

EnableKeyRotation

EnableKeyRotation enables automatic rotation of key material for a specified symmetric KMS key. This operation cannot be performed on a KMS key in a different AWS account.

For scenario questions, distinguish automatic rotation of symmetric key material from operations that change which KMS key protects existing ciphertext. The latter is a re-encryption use case.

GenerateDataKey

GenerateDataKey creates a unique symmetric data key and returns two forms:

1. A plaintext copy for the application to use when encrypting data outside KMS.
2. An encrypted copy protected by the specified KMS key.

The application can store the encrypted data key alongside the encrypted data. The plaintext copy should be used only as needed for the encryption operation.

GenerateDataKeyWithoutPlaintext

GenerateDataKeyWithoutPlaintext creates a unique symmetric data key but returns only the encrypted form protected by the specified KMS key. This is appropriate when the caller does not need KMS to return a plaintext data key.

GenerateDataKeyPair and GenerateDataKeyPairWithoutPlaintext

When an asymmetric data key pair is required, use GenerateDataKeyPair or GenerateDataKeyPairWithoutPlaintext. The distinction follows the same pattern as the symmetric operations: the regular operation provides a plaintext form as well as an encrypted form, while the WithoutPlaintext variant returns only the encrypted form.

KMS Quotas, Throttling, and Caching

Resource quotas

Resource quotas limit the number of resources of a particular type that can be created. Exceeding a resource quota causes an attempt to create another resource to fail with a limits exceeded exception.

This is different from making API calls too rapidly. A resource-limit problem is addressed by reducing resource consumption, removing resources where appropriate, or considering a quota increase—not primarily by adding request retries.

Request quotas

Request quotas apply to API actions such as Encrypt, Decrypt, ReEncrypt, and GenerateDataKey. Exceeding a request quota can produce a throttling response, including a ThrottlingException with HTTP status code 400 and a message indicating that the call rate must be reduced.

The presence of a request ID in the response does not change the diagnosis: the application is calling KMS too frequently or exceeding the applicable request rate.

Mitigating request throttling

Three approaches are emphasized:

1. Backoff and retry: Modify the application to wait before retrying failed calls. The delay reduces pressure on KMS and gives the service time to recover capacity.
2. Service quota increase: Request a higher quota when the workload consistently requires a large number of KMS API actions.
3. Data key caching: Reuse cached data keys and related cryptographic material when the application can safely reuse them and repeated generation is too slow, expensive, limited, or resource intensive.

Data key caching with the AWS Encryption SDK

Data key caching can be implemented with the AWS Encryption SDK’s local crypto materials cache feature. The cache stores data keys and related cryptographic material locally so an application does not need to generate new data keys for every operation when reuse is suitable.

Caching is not the first answer to every KMS error. It is most relevant when repeated cryptographic operations create performance or resource pressure and the application can reuse data keys. If the fundamental issue is a resource-count limit, caching API results does not itself create more resource capacity.

Exam- or Assessment-Relevant Takeaways

• Choose Encrypt for small arbitrary plaintext values such as passwords or identifiers.
• Choose GenerateDataKey when the application needs a plaintext data key to encrypt data outside KMS and also needs an encrypted copy for storage.
• Choose GenerateDataKeyWithoutPlaintext when only the KMS-protected data key should be returned.
• Choose ReEncrypt to change the KMS key protecting ciphertext without exposing plaintext to the application, or to change encryption context under the same key.
• EnableKeyRotation enables automatic rotation of key material for a symmetric KMS key and cannot target a key in another AWS account.
• A limits exceeded exception points to a resource quota; a ThrottlingException points to a request quota or excessive call rate.
• Use backoff and retry for transient request-rate pressure, a service quota increase for sustained high demand, and data key caching when repeated data key generation is the source of the pressure.
• Do not confuse data key caching with changing the KMS key used to protect existing ciphertext; that is a ReEncrypt decision.

Tool / Feature Decision Guide

Requirement	Appropriate operation or mitigation	Decisive reason
Encrypt a small password, identifier, or other sensitive value	Encrypt / aws kms encrypt	Directly encrypts small arbitrary plaintext with a KMS key
Encrypt application data outside KMS while retaining KMS protection for the data key	GenerateDataKey	Returns both plaintext and KMS-encrypted copies of a symmetric data key
Obtain only a KMS-encrypted symmetric data key	GenerateDataKeyWithoutPlaintext	Avoids returning a plaintext data key
Obtain an asymmetric data key pair	GenerateDataKeyPair or GenerateDataKeyPairWithoutPlaintext	These operations generate data key pairs rather than symmetric data keys
Change the key protecting existing ciphertext	ReEncrypt	KMS performs the decrypt-and-re-encrypt transition
Change encryption context under the same KMS key	ReEncrypt	The ciphertext can be re-encrypted within KMS with updated context
Enable automatic key material rotation	EnableKeyRotation	Applies to the specified symmetric KMS key, subject to the account restriction
Calls fail because the application is calling KMS too rapidly	Backoff and retry	Reduces request frequency during transient throttling
The workload consistently requires more API capacity	Service quota increase	Addresses a sustained request-quota requirement
Repeated data key generation is costly or slow and keys can be reused	AWS Encryption SDK local crypto materials cache	Reuses cached data keys and related cryptographic material

Common Traps / Misconceptions

• Confusing a resource quota with a request quota: Resource limits concern the number of resources; request quotas concern API call activity.
• Using GenerateDataKeyWithoutPlaintext when plaintext is required: This operation does not return a plaintext data key for the application to use directly.
• Assuming ReEncrypt is only for key rotation: It also supports changing the encryption context while retaining the same KMS key.
• Treating Encrypt as a bulk-data solution: The lesson describes it for small amounts of arbitrary data.
• Using retries for every quota problem: Backoff and retry address request-rate pressure, not a hard resource-count limit.
• Assuming data key caching is a universal replacement for quota increases: Caching helps when repeated key generation can be reduced through reuse; sustained demand may still require a service quota increase.
• Forgetting the account restriction on key rotation: EnableKeyRotation cannot be performed on a KMS key in a different AWS account.
• Mixing up key rotation and re-encryption: Rotation changes key material behavior, while ReEncrypt changes the KMS protection of existing ciphertext or its encryption context.

Real-World Engineer / Analyst Notes

• Diagnose the error category before selecting a remediation. A ThrottlingException suggests request-rate pressure, while a limits-exceeded error suggests a resource quota.
• Build backoff and retry behavior into applications that make KMS calls, rather than retrying immediately and increasing the load.
• When using data keys, preserve the relationship between encrypted data and its encrypted data key so the data key can later be recovered through KMS.
• Treat plaintext data keys as sensitive material and limit their exposure to the portion of the workflow that needs them.
• Consider the workload pattern before enabling caching. Caching is most useful when repeated operations can safely reuse data keys and when KMS activity is a measurable bottleneck.
• For assessment scenarios, identify whether the requirement concerns plaintext availability, ciphertext migration, key-material rotation, resource count, or API-call rate. Those distinctions usually determine the correct KMS feature.

Quick Reference Summary

• Encrypt: Encrypts small arbitrary plaintext with a KMS key.
• Decrypt: Decrypts ciphertext produced by supported KMS encryption and data-key operations.
• ReEncrypt: Decrypts and re-encrypts within KMS, including changing the protecting key or encryption context.
• EnableKeyRotation: Enables automatic rotation of key material for a symmetric KMS key; cannot target a key in another account.
• GenerateDataKey: Returns plaintext and KMS-encrypted copies of a symmetric data key.
• GenerateDataKeyWithoutPlaintext: Returns only the encrypted symmetric data key.
• GenerateDataKeyPair: Generates an asymmetric data key pair with plaintext and encrypted forms.
• GenerateDataKeyPairWithoutPlaintext: Generates an asymmetric data key pair without returning plaintext.
• Resource quota exceeded: expect a limits-exceeded error when creating another resource.
• Request quota exceeded: expect throttling, such as ThrottlingException with HTTP status 400.
• Throttling responses: consider backoff and retry, a service quota increase, or data key caching depending on the cause.
• Data key caching: use the AWS Encryption SDK local crypto materials cache when data key reuse can reduce repeated KMS work.

Flashcards

Q: An application must encrypt a small database password directly with a KMS key. Which KMS operation fits this requirement?

A: Use Encrypt (aws kms encrypt). It is intended for encrypting small amounts of arbitrary plaintext such as passwords and identifiers.

Q: When should an application choose GenerateDataKey instead of Encrypt?

A: Choose GenerateDataKey when the application will encrypt data outside KMS and needs a plaintext data key plus an encrypted copy protected by a KMS key.

Q: What does GenerateDataKeyWithoutPlaintext return?

A: It returns a unique symmetric data key encrypted under the specified KMS key, but it does not return a plaintext copy.

Q: What is the key difference between GenerateDataKey and GenerateDataKeyPair?

A: GenerateDataKey creates a symmetric data key, while GenerateDataKeyPair creates an asymmetric data key pair. Each also has a WithoutPlaintext variant.

Q: An application must move existing ciphertext from one KMS key to another without exposing plaintext to the application. Which operation should it use?

A: Use ReEncrypt. KMS performs the decrypt-and-re-encrypt process internally.

Q: When might ReEncrypt be used with the same KMS key?

A: It can be used to re-encrypt ciphertext when changing the encryption context while retaining the same KMS key.

Q: What does EnableKeyRotation do, and what account limitation applies?

A: It enables automatic rotation of key material for a specified symmetric KMS key. It cannot be performed on a KMS key in a different AWS account.

Q: How do resource quotas differ from request quotas in KMS?

A: Resource quotas limit how many resources can be created and can produce a limits-exceeded error. Request quotas limit API-call activity and can produce throttling.

Q: A KMS call fails with ThrottlingException and a message to reduce call frequency. What is the first application-level response?

A: Implement backoff and retry so subsequent calls are delayed rather than sent immediately at the same rate.

Q: When is a service quota increase more appropriate than data key caching?

A: Request an increase when the workload consistently requires more KMS API capacity. Caching is more appropriate when repeated data key generation can be reduced through safe reuse.

Q: What problem does data key caching address?

A: It reduces repeated generation of data keys and related cryptographic material when an application can reuse them and cryptographic operations are too slow, expensive, limited, or resource intensive.

Q: Which AWS component provides the local crypto materials cache feature used for data key caching?

A: The AWS Encryption SDK provides the local crypto materials cache feature.

Q: Why is backoff and retry not the primary fix for a resource quota error?

A: Retries do not increase the number of resources the account is allowed to create. A resource-limit problem requires reducing resource use or considering a quota increase.

Practice Questions

1. A service encrypts customer records outside KMS. It needs a data key in plaintext for the encryption operation and wants to store a KMS-protected copy beside the encrypted records. Which operation should it use?

A. Encrypt
B. GenerateDataKey
C. GenerateDataKeyWithoutPlaintext
D. ReEncrypt

Correct answer: B. GenerateDataKey

GenerateDataKey returns both the plaintext data key and a copy encrypted under the specified KMS key, matching the described external-encryption workflow.

2. An application receives repeated KMS errors stating that it has exceeded the rate at which it may call KMS. Which response best addresses the immediate problem?

A. Create more KMS resources
B. Enable key rotation
C. Add backoff and retry logic
D. Use ReEncrypt instead of Decrypt for every request

Correct answer: C. Add backoff and retry logic

The message indicates request-rate throttling. Delaying retries reduces call frequency; a quota increase may be appropriate if the high volume is sustained.

3. An organization wants to change the KMS key protecting existing ciphertext, and the plaintext must not be exposed to the application. Which operation is most appropriate?

A. GenerateDataKey
B. EnableKeyRotation
C. ReEncrypt
D. Decrypt

Correct answer: C. ReEncrypt

ReEncrypt performs the decrypt-and-re-encrypt process entirely within KMS and is designed for changing the key protecting ciphertext.

4. A team receives a limits-exceeded exception when attempting to create another resource of a particular KMS resource type. What kind of limit has been reached?

A. A request quota
B. A resource quota
C. A data key cache limit
D. An encryption-context mismatch

Correct answer: B. A resource quota

A limits-exceeded error during resource creation indicates a resource quota, not a request-rate throttling condition.

5. An application generates numerous data keys, and cryptographic operations have become unacceptably slow and resource intensive. The application can reuse data keys. Which feature should the team evaluate?

A. AWS Encryption SDK local crypto materials cache
B. EnableKeyRotation on every request
C. Decrypt retries with no delay
D. GenerateDataKeyWithoutPlaintext for all operations

Correct answer: A. AWS Encryption SDK local crypto materials cache

The local crypto materials cache stores data keys and related cryptographic material for reuse, reducing repeated KMS work when the workload supports it.

WordPress Metadata

Suggested Slug:
aws-kms-api-cli-throttling-data-key-caching

Meta Description:
Study AWS KMS API and CLI operations, data key workflows, quota errors, retry strategies, service quota increases, and data key caching for the SOA-C03 exam.

Tags:
AWS KMS, AWS CLI, AWS APIs, encryption, data keys, key rotation, throttling, service quotas, AWS Encryption SDK, SOA-C03