Generates an asymmetric data key pair encrypted under the initial version of a symmetric key, and returns the plaintext public key, plaintext private key, and ciphertext private key. Use the key pair for signature verification outside Key Management Service (KMS).
Usage notes
The data key pair is generated using a random number generator and encrypted in Galois/Counter Mode (GCM) using the initial version of a symmetric key.
Store the following fields in a secure location. They are required when you call the Decrypt operation to decrypt the ciphertext private key:
PrivateKeyCiphertextBlob: the ciphertext private keyIv: the initial vector (IV)Algorithm: the encryption algorithmAad: the additional authenticated data (AAD)
KMS provides four operations to generate data key pairs. The following table describes when to use each one.
| API | Scenario | Response data | Key version for encryption | 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 plaintext private key | Initial version | Decrypt |
| AdvanceGenerateDataKeyPair | Automatic key rotation configured; need the plaintext private key immediately. For more information about key rotation, see Configure key rotation. | 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 |
Limits
Each KMS instance processes only one request at a time for the following operations: GenerateDataKeyPair, GenerateDataKeyPairWithoutPlaintext, AdvanceGenerateDataKeyPair, and AdvanceGenerateDataKeyPairWithoutPlaintext. Control the rate of concurrent requests. 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 ID of the key. 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 data key pair. Valid values: RSA_2048, RSA_3072, RSA_4096, EC_P256, EC_P256K |
| KeyFormat | string | Yes | PEM | The format of the key pair. Valid values: PEM, DER |
| Aad | bytes | No | Binary data | The additional authenticated data (AAD) used when encrypting the key pair in Galois/Counter Mode (GCM). If specified, pass the same value when calling the Decrypt operation. |
Response elements
| Parameter | Type | Example | Description |
|---|---|---|---|
| KeyId | string | key-hzz62f1cb66fa42qo**** | The ID of the key. If the request used an alias, the ID of the key bound to that alias is returned. |
| KeyPairSpec | string | RSA_2048 | The type of the data key pair. |
| Algorithm | string | AES_GCM | The encryption algorithm. Only AES_GCM is supported. |
| Iv | bytes | Binary data | The initial vector (IV) used to encrypt the data key pair. Pass this value to the Decrypt operation when decrypting the ciphertext private key. |
| PrivateKeyCiphertextBlob | bytes | Binary data | The ciphertext private key of the data key pair. |
| PrivateKeyPlaintext | bytes | Binary data | The plaintext private key of the data key pair. The format depends on the KeyFormat value in the request: PEM returns a PKCS#8 private key in PEM format; DER returns a PKCS#8 private key in DER format. |
| PublicKey | bytes | Binary data | The plaintext public key of the data key pair. The format depends on the KeyFormat value in the request: PEM returns an X.509 public key in PEM format; DER returns an X.509 public key in DER format. |
| RequestId | string | 475f1620-b9d3-4d35-b5c6-3fbdd941423d | The request ID. |
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 complete list of error codes, see Service error codes.