GenerateDataKeyPair
Generates a unique asymmetric data key pair.
Description
The `GenerateDataKeyPair` operation generates a unique asymmetric data key pair. The operation returns a plaintext public key and a copy of the private key that is encrypted under a symmetric KMS key that you specify.
note
- You can use the public key to encrypt data or verify signatures outside of QKMS.
- To decrypt data or generate signatures, you must use the private key inside QKMS.
- The private key that this operation returns exists in plaintext only within QKMS.
Request Syntax
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.GenerateDataKeyPair
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyPairSpec": "RSA_2048",
"EncryptionContext": {
"Purpose": "Test"
}
}
Values in italics indicate user input and should be replaced with actual values.
Request Parameters
Headers
| Name | Description | Required | Type |
|---|---|---|---|
| Content-Type | Must be "application/x-amz-json-1.1" | Yes | string |
| X-Amz-Target | Must be "TrentService.GenerateDataKeyPair" | Yes | string |
Request Body
| Name | Description | Required | Type |
|---|---|---|---|
| KeyId | Specifies the KMS key that encrypts the private key in the data key pair. The value can be the ID or ARN of a KMS key. | Yes | string |
| KeyPairSpec | Determines the type of data key pair that is generated. The supported values are RSA_2048, RSA_3072, RSA_4096, ECC_NIST_P256, ECC_NIST_P384, ECC_NIST_P521, or ECC_SECG_P256K1. | Yes | string |
| EncryptionContext | A key-value pair that specifies the encryption context to be used for authenticated encryption. This value must match the encryption context used when decrypting the private key. | No | map |
| GrantTokens | A list of grant tokens. Use grant tokens when your permission to call this operation comes from a new grant that has not yet achieved eventual consistency. | No | array |
Examples
Example 1: Generate an RSA key pair
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.GenerateDataKeyPair
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyPairSpec": "RSA_2048"
}
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
Content-Type: application/x-amz-json-1.1
{
"KeyId": "arn:verenc:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyPairSpec": "RSA_2048",
"PrivateKeyCiphertextBlob": "Base64-encoded encrypted private key",
"PublicKey": "Base64-encoded public key"
}
Values in italics indicate variable response values.
Example 2: Generate an ECC key pair with encryption context
POST / HTTP/1.1
Content-Type: application/x-amz-json-1.1
X-Amz-Target: TrentService.GenerateDataKeyPair
{
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyPairSpec": "ECC_NIST_P256",
"EncryptionContext": {
"Purpose": "Test"
}
}
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
Content-Type: application/x-amz-json-1.1
{
"KeyId": "arn:verenc:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyPairSpec": "ECC_NIST_P256",
"PrivateKeyCiphertextBlob": "Base64-encoded encrypted private key",
"PublicKey": "Base64-encoded public key"
}
Values in italics indicate variable response values.
Response Syntax
HTTP/1.1 200 OK
Content-Type: application/x-amz-json-1.1
{
"KeyId": "string",
"KeyPairSpec": "string",
"PrivateKey": "blob",
"PrivateKeyCiphertextBlob": "blob",
"PublicKey": "blob"
}
Values in italics indicate variable response values.
Response Elements
| Name | Description | Required | Type |
|---|---|---|---|
| KeyId | The Amazon Resource Name (ARN) of the KMS key that encrypted the private key. | No | String |
| KeyPairSpec | The type of data key pair that was generated. | No | String |
| PrivateKey | The encrypted copy of the private key. When you use the private key, you must first decrypt it. | No | String |
| PrivateKeyCiphertextBlob | The encrypted copy of the private key. Use this value to decrypt the private key outside of QKMS. | No | String |
| PublicKey | The public key (plaintext). | No | String |
Special Errors
| Error Code | Description |
|---|---|
| DependencyTimeoutException | The system timed out while trying to fulfill the request. |
| InvalidKeyUsageException | The request was rejected because the specified KeyId value cannot be used for this operation. |
| KeyUnavailableException | The request was rejected because the specified KMS key was not available. |
| KMSInternalException | The request was rejected because an internal error occurred. |
| KMSInvalidStateException | The request was rejected because the key state is not valid for this operation. |
| NotFoundException | The request was rejected because the specified entity or resource could not be found. |
Permissions
To use the `GenerateDataKeyPair` operation, you must have the following permissions:
- `kms:GenerateDataKeyPair` on the KMS key (specified in the policy)
Try It Out
Test GenerateDataKeyPair
Generate an asymmetric data key pair.
Coming Soon
This feature is currently under development and will be available soon.