All Products
Search
Document Center

Key Management Service:GenerateDataKeyPair

Last Updated:Nov 07, 2023

Generates an asymmetric data key pair.

Usage notes

This operation generates a data key pair by using a random number generator, encrypts the data key pair by using the initial version of a symmetric key, and returns the plaintext public key, plaintext private key, and ciphertext private key of the data key pair. You can use data key pairs to perform signature verification outside Key Management Service (KMS).

Store the ciphertext private key (PrivateKeyCiphertextBlob), initial vector (IV), encryption algorithm (Algorithm), and authentication data (Aad) in a secure location. The saved information is used when you call the Decrypt operation to decrypt the ciphertext private key.

KMS provides the following operations to generate data key pairs. The following table describes the differences between the operations.

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 can process only one request at a time for the GenerateDataKeyPair, GenerateDataKeyPairWithoutPlaintext, AdvanceGenerateDataKeyPair, and AdvanceGenerateDataKeyPairWithoutPlaintext operations. We recommend that you control 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 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 authentication data when you encrypt the data key pair in Galois/Counter Mode (GCM) mode.

Important

If you specify this parameter, you must specify the same parameter 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 initial vector that is 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.

PrivateKeyPlaintext

bytes

Binary data

The plaintext private key of the data key pair.

  • If KeyFormat is set to DER in the request parameters, the PKCS#8 plaintext private key in the DER format is returned.

  • If KeyFormat is set to PEM in the request parameters, the PKCS#8 plaintext private key in the PEM format is returned.

PublicKey

bytes

Binary data

The plaintext public key of the data key pair.

  • If KeyFormat is set to DER in the request parameters, the X.509 plaintext public key in the DER format is returned.

  • If KeyFormat is set to PEM in the request parameters, the X.509 plaintext public key in the PEM format is returned.

Algorithm

string

AES_GCM

The encryption algorithm. Only AES_GCM is supported.

RequestId

string

475f1620-b9d3-4d35-b5c6-3fbdd941423d

The ID of the request, which is 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.