GenerateAndExportDataKey - Key Management Service - Alibaba Cloud Documentation Center

Operation description

Notes

For more information about the access policy required for a RAM user or RAM role to call this operation, see Resource Access Management.
You can call this operation using a shared gateway or a dedicated gateway. For more information, see Alibaba Cloud SDK.
- Shared gateway: You can access KMS over the Internet or a VPC. To access KMS over the Internet, you must enable Internet access. For more information, see Access KMS instances over the Internet.
- Dedicated gateway: You can access KMS using the private endpoint of KMS (<YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com).

Description

We recommend that you import the data key to a cryptographic module for data encryption and data decryption as follows:

1. Call the GenerateAndExportDataKey operation to obtain the data key encrypted by a KMS key and a specified public key.

2. Save the ciphertext of the data key that is encrypted by the KMS key to KMS or a storage service, such as ApsaraDB, for key backup and recovery.

3. Import the ciphertext of the data key that is encrypted by the public key to the cryptographic module that contains the corresponding private key. This process distributes the key from KMS to the cryptographic module. You can then use the data key to encrypt and decrypt data.

Note

The KMS key that you specify in the request is used only to encrypt the data key and is not used to generate the data key. KMS does not record or store the randomly generated data key. You are responsible for recording the data key or its ciphertext.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

No authorization for this operation. If you encounter issues with this operation, contact technical support.

Request parameters

Parameter	Type	Required	Description	Example
KeyId	string	Yes	The ID of the key. You can also specify the alias or Amazon Resource Name (ARN) of the key. For more information about aliases, see Manage aliases. Note To access a key in another Alibaba Cloud account, you must specify the ARN of the key. The key ARN is in the format of `acs:kms:${region}:${account}:key/${keyid}`.	1234abcd-12ab-34cd-56ef-12345678****
KeySpec	string	No	The length of the data key that you want to generate. Valid values: AES_256: a 256-bit symmetric key. AES_128: a 128-bit symmetric key. Note We recommend that you use the KeySpec or NumberOfBytes parameter to specify the length of a data key. If you do not specify either of the parameters, KMS generates a 256-bit data key. If you specify both parameters, KMS ignores the KeySpec parameter.	AES_256
NumberOfBytes	integer	No	The length of the data key that you want to generate. Valid values: 1 to 1024. Unit: bytes.	32
EncryptionContext	object	No	A JSON string that consists of key-value pairs. If you specify this parameter, you must specify the same parameter when you call the Decrypt operation or other operations to re-encrypt the data key. For more information, see EncryptionContext.	{"Example":"Example"}
PublicKeyBlob	string	Yes	The public key that is encoded in Base64.	MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAndKfC2ReLL2+y8a0+ZBBeAft/uBYo86GZiYJuflqgUzKxpyuvlo3uQkBv6b+nx+0tz8g8v7GhpPWMSW5L9mNHYsvYFsa7jTxsYdt17yj6GlUHPuMIs8hr5qbwl38IHU1iIa7nYWwE2fb3ePOvLDACRJVgGpU0yxioW80d2QD+9aU4jF5dlAahcfgsNzo2CXzCUc1+xbmNuq7Rp+H9VJB9dyYOwqnW3RhOLBo21FzpORapf0UiRlrHRpk1V6ez+aE1dofaYh/9bh0m6ioxj7j5hpZbWccuEZTMBKd+cbuBkRhJzc6Tti6qwZbDiu4fUwbZS0Tqpuo1UadiyxMW********
WrappingKeySpec	string	Yes	The type of the key specified by PublicKeyBlob. For more information about key types, see Introduction to asymmetric keys. Valid values: RSA_2048 EC_SM2	RSA_2048
WrappingAlgorithm	string	Yes	The encryption algorithm that is used to encrypt the data key using the public key specified by PublicKeyBlob. For more information about encryption algorithms, see AsymmetricDecrypt. Valid values: RSAES_OAEP_SHA_256 RSAES_OAEP_SHA_1 SM2PKE	RSAES_OAEP_SHA_256
DryRun	string	No	Specifies whether to enable the dry run feature. true: enables the feature. false (default): disables the feature. The DryRun mode is used to test API calls and verify the permissions on the resources that you have access to and the validity of the request parameters. If you enable the DryRun mode, KMS always returns a failure response and the cause of the failure. The following failure causes are included: DryRunOperationError: The request would have succeeded if the DryRun parameter is not specified. ValidationError: The parameters specified in the request are invalid. AccessDeniedError: You are not authorized to perform this operation on the KMS resource.	false

Response parameters

Parameter	Type	Description	Example
	object
KeyVersionId	string	The ID of the key version that is used to encrypt the plaintext. It is the primary version of the specified KMS key.	2ab1a983-7072-4bbc-a582-584b5bd8****
KeyId	string	The ID of the key. If you use a key alias or key ARN in the request, the key ID is returned.	599fa825-17de-417e-9554-bb032cc6****
CiphertextBlob	string	The ciphertext of the data key. The data key is encrypted using the primary version of the specified KMS key.	ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****
RequestId	string	The ID of the request, which is a unique identifier generated by Alibaba Cloud. You can use the request ID to troubleshoot issues.	7021b6ec-4be7-4d3c-8a68-1e85d4d515a0
ExportedDataKey	string	The exported data key that is protected by the public key.	BQKP+1zK6+ZEMxTP5qaVzcsgXtWplYBKm0NXdSnB5FzliFxE1bSiu4dnEIlca2JpeH7yz1/S6fed630H+hIH6DoM25fTLNcKj+mFB0Xnh9m2+HN59Mn4qyTfcUeadnfCXSWcGBouhXFwcdd2rJ3n337bzTf4jm659gZu3L0i6PLuxM9p7mqdwO0cKJPfGVfhnfMz+f4alMg79WB/NNyE2lyX7/qxvV49ObNrrJbKSFiz8Djocaf0IESNLMbfYI5bXjWkJlX92DQbKhibtQW8ZOJ//ZC6t0AWcUoKL6QDm/dg5koQalcleRinpB+QadFm894sLbVZ9+N4GVs*******

Examples

Success response

JSON format

{
  "KeyVersionId": "2ab1a983-7072-4bbc-a582-584b5bd8****",
  "KeyId": "599fa825-17de-417e-9554-bb032cc6****",
  "CiphertextBlob": "ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****",
  "RequestId": "7021b6ec-4be7-4d3c-8a68-1e85d4d515a0",
  "ExportedDataKey": "BQKP+1zK6+ZEMxTP5qaVzcsgXtWplYBKm0NXdSnB5FzliFxE1bSiu4dnEIlca2JpeH7yz1/S6fed630H+hIH6DoM25fTLNcKj+mFB0Xnh9m2+HN59Mn4qyTfcUeadnfCXSWcGBouhXFwcdd2rJ3n337bzTf4jm659gZu3L0i6PLuxM9p7mqdwO0cKJPfGVfhnfMz+f4alMg79WB/NNyE2lyX7/qxvV49ObNrrJbKSFiz8Djocaf0IESNLMbfYI5bXjWkJlX92DQbKhibtQW8ZOJ//ZC6t0AWcUoKL6QDm/dg5koQalcleRinpB+QadFm894sLbVZ9+N4GVs*******"
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidParameter	The specified parameter is not valid.	An invalid value is specified for the parameter.
500	InternalFailure	InternalFailure
404	Forbidden.KeyNotFound	The specified Key is not found.	The error message returned because the specified CMK does not exist.
404	InvalidAccessKeyId.NotFound	The Access Key ID provided does not exist in our records.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.