Generates an asymmetric data key pair encrypted with the primary version of a symmetric key, returning the plaintext public key and ciphertext private key without exposing the plaintext private key.
Usage notes
This operation generates a data key pair using a random number generator, encrypts the key pair with the primary version of a symmetric key, and returns only the plaintext public key and ciphertext private key. The plaintext private key is never returned. Use this operation for signature verification outside Key Management Service (KMS).
Securely store the ciphertext private key (PrivateKeyCiphertextBlob), encryption algorithm (Algorithm), and authentication data (Aad). You need these values when you call AdvanceDecrypt to decrypt the ciphertext private key.
KMS provides four operations for generating data key pairs. The following table describes when to use each operation.
| API | Scenario | Response data | Key version for encryption | Operation for decryption |
|---|---|---|---|---|
| GenerateDataKey | Automatic rotation is not configured for keys, and you need to immediately obtain the plaintext private key. | Plaintext public key, plaintext private key, and ciphertext private key | The initial version of the key | Decrypt |
| GenerateDataKeyPairWithoutPlaintext | Automatic rotation is not configured for keys, and you do not use the plaintext private key or require higher security. | Plaintext public key and plaintext private key | The initial version of the key | Decrypt |
| AdvanceGenerateDataKeyPair | Automatic rotation is configured for keys, and you need to immediately obtain the plaintext private key. Note For more information about key rotation, see Configure key rotation. | Plaintext public key, plaintext private key, and ciphertext private key | The primary version of the key | AdvanceDecrypt |
| AdvanceGenerateDataKeyPairWithoutPlaintext | Automatic rotation is configured for keys, and you do not use the plaintext private key or require higher security. | Plaintext public key and plaintext private key | The primary version of the key | AdvanceDecrypt |
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 concurrent requests exceed 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 key. You can set this parameter to an alias that is bound to the key. Note Only symmetric keys in KMS instances of the software key management type are supported. |
| KeyPairSpec | string | Yes | RSA_2048 | The type of the data key pair. Valid values: RSA_2048, RSA_3072, RSA_4096, EC_P256, EC_P256K |
| Aad | bytes | No | Binary data | The additional authenticated data (AAD) used to encrypt the data key pair in Galois/Counter Mode (GCM). Important If you specify this parameter, you must pass the same value when you call the Decrypt operation. |
| KeyFormat | string | Yes | PEM | The format of the data key pair. Valid values: PEM, DER |
Response parameters
| Parameter | Type | Example | Description |
|---|---|---|---|
| KeyId | string | key-hzz62f1cb66fa42qo**** | The globally unique ID of the key. If KeyId in the request is set to an alias, the globally unique ID of the key to which the alias is bound is returned. |
| Iv | bytes | Binary data | The initialization vector (IV) used to encrypt the data key pair. Note When you call the Decrypt operation to decrypt the data key pair, you must specify a valid value for Iv. |
| KeyPairSpec | string | RSA_2048 | The type of the data key pair. |
| PrivateKeyCiphertextBlob | bytes | Binary data | The ciphertext private key of the data key pair. |
| PublicKey | bytes | Binary data | The plaintext public key of the data key pair. The format depends on the KeyFormat value in the request: if KeyFormat is set to DER, an X.509 public key in DER format is returned; if KeyFormat is set to PEM, an X.509 public key in PEM format is returned. |
| Algorithm | string | AES_GCM | The encryption algorithm. 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 a list of error codes, see Service error codes.