Asymmetric Data Key Pairs Without Plaintext for Secure Encryption - Key Management Service

Generates an asymmetric data key pair, encrypts the private key with the initial version of a symmetric key, and returns the plaintext public key and ciphertext private key without exposing the plaintext private key.

Usage notes

Important

This operation is supported only for KMS instances of the software key management type. KMS instances of the hardware key management type are not supported.

This operation uses a random number generator to create a data key pair, then encrypts it with the initial version of a symmetric key. The plaintext public key is returned directly. The plaintext private key is never returned — only its encrypted form (ciphertext private key) is returned. Use this operation when you need to perform signature verification outside KMS without requiring access to the plaintext private key.

After the operation completes, store the following values in a secure location. You need them when you call Decrypt to decrypt the ciphertext private key.

PrivateKeyCiphertextBlob: the ciphertext private key
Iv: the initialization vector (IV)
Algorithm: the encryption algorithm
Aad: the additional authenticated data (AAD), if specified

Choose the right operation

KMS provides four operations for generating data key pairs. The following table describes when to use each.

API	Scenario	Response data	Encryption key version	Decryption operation
GenerateDataKey	No automatic key rotation; need the plaintext private key immediately	Plaintext public key, plaintext private key, and ciphertext private key	Initial version	Decrypt
GenerateDataKeyPairWithoutPlaintext	No automatic key rotation; do not need the plaintext private key, or require higher security	Plaintext public key and ciphertext private key	Initial version	Decrypt
AdvanceGenerateDataKeyPair	Automatic key rotation configured; need the plaintext private key immediately	Plaintext public key, plaintext private key, and ciphertext private key	Primary version	AdvanceDecrypt
AdvanceGenerateDataKeyPairWithoutPlaintext	Automatic key rotation configured; do not need the plaintext private key, or require higher security	Plaintext public key and ciphertext private key	Primary version	AdvanceDecrypt

Note

For more information about key rotation, see Configure key rotation.

Precautions

Each KMS instance processes only one request at a time for the GenerateDataKeyPair, GenerateDataKeyPairWithoutPlaintext, AdvanceGenerateDataKeyPair, and AdvanceGenerateDataKeyPairWithoutPlaintext operations. Control concurrent requests to avoid exceeding this limit. If the number of concurrent requests exceeds the limit, KMS returns a 429 error (Concurrency Limit Exceeded).

Request parameters

Parameter	Type	Required	Example	Description
KeyId	string	Yes	`key-hzz62f1cb66fa42qo****`	The globally unique ID of the symmetric key to use for encryption. You can also set this parameter to an alias bound to the key. Only symmetric keys in KMS instances of the software key management type are supported.
KeyPairSpec	string	Yes	`RSA_2048`	The type of the asymmetric data key pair. Valid values: `RSA_2048`, `RSA_3072`, `RSA_4096`, `EC_P256`, `EC_P256K`
KeyFormat	string	Yes	`PEM`	The format of the data key pair. Valid values: `PEM`, `DER`
Aad	bytes	No	Binary data	The additional authenticated data (AAD) for Galois/Counter Mode (GCM) encryption. If you specify this parameter, you must pass the same value when you call the Decrypt operation to decrypt the ciphertext private key.

Response parameters

Parameter	Type	Example	Description
KeyId	string	`key-hzz62f1cb66fa42qo****`	The globally unique ID of the key. If the request set `KeyId` to an alias, the actual key ID that the alias is bound to is returned.
KeyPairSpec	string	`RSA_2048`	The type of the data key pair.
PublicKey	bytes	Binary data	The plaintext public key of the data key pair in X.509 format. The encoding format matches the `KeyFormat` value in the request: `DER` returns a DER-encoded key; `PEM` returns a PEM-encoded key.
PrivateKeyCiphertextBlob	bytes	Binary data	The ciphertext private key of the data key pair. Store this value securely and use it with `Iv`, `Algorithm`, and `Aad` to decrypt the private key via the Decrypt operation.
Iv	bytes	Binary data	The initialization vector (IV) used to encrypt the data key pair. Required when calling Decrypt to decrypt the ciphertext private key.
Algorithm	string	`AES_GCM`	The encryption algorithm used to encrypt the data key pair. Only `AES_GCM` is supported.
RequestId	string	`475f1620-b9d3-4d35-b5c6-3fbdd941423d`	The request ID, used to locate and troubleshoot issues.

Error codes

HTTP status code	Error code	Error message	Description
429	Rejected.Throttling	Concurrency Limit Exceeded.	The number of concurrent requests exceeds the limit.

For the full list of error codes, see Service error codes.