Generates an asymmetric data key pair, encrypts it using the primary version of a symmetric key, and returns the plaintext public key, plaintext private key, and ciphertext private key.
Operation description
AdvanceGenerateDataKeyPair uses a random number generator to create an asymmetric data key pair. The key pair is encrypted in Galois/Counter Mode (GCM) using the primary version of a symmetric key in Key Management Service (KMS). Use this operation when automatic key rotation is configured for the symmetric key and you need immediate access to the plaintext private key. You can use data key pairs to perform signature verification outside KMS.
Store the ciphertext private key (PrivateKeyCiphertextBlob), encryption algorithm (Algorithm), and authentication data (Aad) in a secure location. These values are required when you call AdvanceDecrypt to decrypt the ciphertext private key.
Choose a data key pair operation
KMS provides four operations for generating data key pairs. The following table summarizes the differences.
| API | Use when | Response data | Key version for encryption | Decryption operation |
|---|---|---|---|---|
| GenerateDataKeyPair | No auto rotation; need the plaintext private key immediately | Plaintext public key, plaintext private key, ciphertext private key | Initial key version | Decrypt |
| GenerateDataKeyPairWithoutPlaintext | No auto rotation; plaintext private key not required or higher security preferred | Plaintext public key and plaintext private key | Initial key version | Decrypt |
| AdvanceGenerateDataKeyPair | Auto rotation configured; need the plaintext private key immediately | Plaintext public key, plaintext private key, ciphertext private key | Primary key version | AdvanceDecrypt |
| AdvanceGenerateDataKeyPairWithoutPlaintext | Auto rotation configured; plaintext private key not required or higher security preferred | Plaintext public key and plaintext private key | Primary key version | AdvanceDecrypt |
For more information about key rotation, see Configure key rotation.
Usage notes
Each KMS instance processes only one request at a time across all four data key pair generation operations: GenerateDataKeyPair, GenerateDataKeyPairWithoutPlaintext, AdvanceGenerateDataKeyPair, and AdvanceGenerateDataKeyPairWithoutPlaintext. Control concurrent requests to avoid hitting this limit. If concurrent requests exceed the limit, KMS returns HTTP 429 (Concurrency Limit Exceeded).
Request parameters
| Parameter | Type | Required | Example | Description |
|---|---|---|---|---|
| KeyId | string | Yes | key-hzz62f1cb66fa42qo**** | The globally unique ID of the symmetric key, or 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 authentication data (additional authenticated data, AAD) used when encrypting the data key pair in GCM mode. If you specify this parameter, pass the same value to AdvanceDecrypt when decrypting the ciphertext private key. |
Response elements
| Parameter | Type | Example | Description |
|---|---|---|---|
| KeyId | string | key-hzz62f1cb66fa42qo**** | The globally unique ID of the key. If KeyId in the request was set to an alias, this field returns the ID of the key the alias is bound to. |
| KeyPairSpec | string | RSA_2048 | The type of the data key pair. |
| Algorithm | string | AES_GCM | The encryption algorithm used to encrypt the data key pair. Only AES_GCM is supported. |
| Iv | bytes | Binary data | The initialization vector (IV) used to encrypt the data key pair. Pass this value to AdvanceDecrypt when decrypting the ciphertext private key. |
| PublicKey | bytes | Binary data | The plaintext public key. If KeyFormat is DER, returns an X.509 public key in DER format. If KeyFormat is PEM, returns an X.509 public key in PEM format. |
| PrivateKeyPlaintext | bytes | Binary data | The plaintext private key. If KeyFormat is DER, returns a PKCS#8 private key in DER format. If KeyFormat is PEM, returns a PKCS#8 private key in PEM format. |
| PrivateKeyCiphertextBlob | bytes | Binary data | The ciphertext private key. Store this value securely and use it with Algorithm and Aad to decrypt the private key via AdvanceDecrypt. |
| 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. | Concurrent requests exceeded the per-instance limit. |
For a complete list of error codes, see Service error codes.