Randomly generates a data key and uses a key and a public key to encrypt the data key. This operation returns the data key ciphertext that is encrypted by using the key and the data key ciphertext that is encrypted by using the public key.
Usage notes
Keys outside Key Management Service (KMS) instances: To perform cryptographic operations, use Alibaba Cloud SDK to call operations.
Keys in KMS instances: To perform cryptographic operations, use one of the following methods:
Method 1 (recommended): Use KMS Instance SDK to call KMS Instance API operations. For more information, see KMS Instance SDK and KMS Instance API.
Method 2: Use Alibaba Cloud SDK to call operations. The authentication method supports only RAM roles whose trusted entities are Alibaba Cloud services. For more information, see Create a RAM role for a trusted Alibaba Cloud service.
QPS limits
You can call this operation up to 750 times per second per account. If the number of the calls per second exceeds the limit, throttling is triggered. As a result, your business may be affected. We recommend that you take note of the limit when you call this operation.
Description
We recommend that you perform the following steps to import your data key to a cryptographic module:
1. Call the GenerateAndExportDataKey operation to obtain the data key ciphertext that is encrypted by using a key and the data key ciphertext that is encrypted by using a public key.
2. Save the data key ciphertext that is encrypted by using the key in Secrets Manager or a storage service such as ApsaraDB. The data key ciphertext is used for backup and restoration.
3. Import the data key ciphertext that is encrypted by using the public key to a cryptographic module where paired private key is stored. Then, you can use the data key to encrypt or decrypt data.
The key that you specify in the request of this operation is only used to encrypt the data key and is not involved in the generation of the data key. KMS does not record or store the data key that is randomly generated by calling this operation. You must take note of the data key and the returned data key ciphertext.
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
Action | String | Yes | GenerateAndExportDataKey | The operation that you want to perform. Set the value to GenerateAndExportDataKey. |
KeyId | String | Yes | 1234abcd-12ab-34cd-56ef-12345678**** | The ID of the key. The ID must be globally unique. You can also set this parameter to an alias that is bound to the key. |
KeySpec | String | No | AES_256 | The type of the data key. Valid values:
Note We recommend that you use KeySpec or NumberOfBytes to specify the length of a data key. If none of the parameters are specified, KMS generates a 256-bit data key. If both parameters are specified, KMS ignores KeySpec. |
NumberOfBytes | Integer | No | 32 | The length of the data key. Valid values: 1 to 1024. Unit: bytes. |
EncryptionContext | Map | No | {"Example":"Example"} | The JSON string that consists of key-value pairs. If you specify this parameter, an equivalent value is required when you decrypt or re-encrypt the data key. For more information, see EncryptionContext. |
PublicKeyBlob | String | Yes | MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAndKfC2ReLL2+y8a0+ZBBeAft/uBYo86GZiYJuflqgUzKxpyuvlo3uQkBv6b+nx+0tz8g8v7GhpPWMSW5L9mNHYsvYFsa7jTxsYdt17yj6GlUHPuMIs8hr5qbwl38IHU1iIa7nYWwE2fb3ePOvLDACRJVgGpU0yxioW80d2QD+9aU4jF5dlAahcfgsNzo2CXzCUc1+xbmNuq7Rp+H9VJB9dyYOwqnW3RhOLBo21FzpORapf0UiRlrHRpk1V6ez+aE1dofaYh/9bh0m6ioxj7j5hpZbWccuEZTMBKd+cbuBkRhJzc6Tti6qwZbDiu4fUwbZS0Tqpuo1UadiyxMW******** | A Base64-encoded public key. |
WrappingKeySpec | String | Yes | RSA_2048 | The key type of the public key specified by PublicKeyBlob. For more information about key types, see Introduction to asymmetric keys. Valid values:
|
WrappingAlgorithm | String | Yes | RSAES_OAEP_SHA_256 | The encryption algorithm based on which you use the public key specified by PublicKeyBlob to encrypt the data key. For more information about encryption algorithms, see AsymmetricDecrypt. Valid values:
|
Response parameters
Parameter | Type | Example | Description |
KeyVersionId | String | 2ab1a983-7072-4bbc-a582-584b5bd8**** | The version ID of the key that is used to encrypt the plaintext. The primary version of the key is used. |
KeyId | String | 599fa825-17de-417e-9554-bb032cc6**** | The ID of the key. The ID must be globally unique. Note If KeyId is set to an alias of the key, the ID of the key to which the alias is bound is returned. |
CiphertextBlob | String | ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS**** | The data key ciphertext that is encrypted by using the primary version of the key. |
RequestId | String | 7021b6ec-4be7-4d3c-8a68-1e85d4d515a0 | The ID of the request, which is used to locate and troubleshoot issues. |
ExportedDataKey | String | BQKP+1zK6+ZEMxTP5qaVzcsgXtWplYBKm0NXdSnB5FzliFxE1bSiu4dnEIlca2JpeH7yz1/S6fed630H+hIH6DoM25fTLNcKj+mFB0Xnh9m2+HN59Mn4qyTfcUeadnfCXSWcGBouhXFwcdd2rJ3n337bzTf4jm659gZu3L0i6PLuxM9p7mqdwO0cKJPfGVfhnfMz+f4alMg79WB/NNyE2lyX7/qxvV49ObNrrJbKSFiz8Djocaf0IESNLMbfYI5bXjWkJlX92DQbKhibtQW8ZOJ//ZC6t0AWcUoKL6QDm/dg5koQalcleRinpB+QadFm894sLbVZ9+N4GVs******* | The data key ciphertext that is encrypted by using the public key. |
Examples
Sample requests
http(s)://[Endpoint]/?Action=GenerateAndExportDataKey
&KeyId=1234abcd-12ab-34cd-56ef-12345678****
&KeySpec=AES_256
&NumberOfBytes=32
&PublicKeyBlob=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAndKfC2ReLL2+y8a0+ZBBeAft/uBYo86GZiYJuflqgUzKxpyuvlo3uQkBv6b+nx+0tz8g8v7GhpPWMSW5L9mNHYsvYFsa7jTxsYdt17yj6GlUHPuMIs8hr5qbwl38IHU1iIa7nYWwE2fb3ePOvLDACRJVgGpU0yxioW80d2QD+9aU4jF5dlAahcfgsNzo2CXzCUc1+xbmNuq7Rp+H9VJB9dyYOwqnW3RhOLBo21FzpORapf0UiRlrHRpk1V6ez+aE1dofaYh/9bh0m6ioxj7j5hpZbWccuEZTMBKd+cbuBkRhJzc6Tti6qwZbDiu4fUwbZS0Tqpuo1UadiyxMW********
&WrappingKeySpec=RSA_2048
&WrappingAlgorithm=RSAES_OAEP_SHA_256
&Common request parametersSample success responses
XML format
HTTP/1.1 200 OK
Content-Type:application/xml
<GenerateAndExportDataKeyResponse>
<KeyVersionId>2ab1a983-7072-4bbc-a582-584b5bd8****</KeyVersionId>
<KeyId>599fa825-17de-417e-9554-bb032cc6****</KeyId>
<CiphertextBlob>ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****</CiphertextBlob>
<RequestId>7021b6ec-4be7-4d3c-8a68-1e85d4d515a0</RequestId>
<ExportedDataKey>BQKP+1zK6+ZEMxTP5qaVzcsgXtWplYBKm0NXdSnB5FzliFxE1bSiu4dnEIlca2JpeH7yz1/S6fed630H+hIH6DoM25fTLNcKj+mFB0Xnh9m2+HN59Mn4qyTfcUeadnfCXSWcGBouhXFwcdd2rJ3n337bzTf4jm659gZu3L0i6PLuxM9p7mqdwO0cKJPfGVfhnfMz+f4alMg79WB/NNyE2lyX7/qxvV49ObNrrJbKSFiz8Djocaf0IESNLMbfYI5bXjWkJlX92DQbKhibtQW8ZOJ//ZC6t0AWcUoKL6QDm/dg5koQalcleRinpB+QadFm894sLbVZ9+N4GVs*******</ExportedDataKey>
</GenerateAndExportDataKeyResponse>JSON format
HTTP/1.1 200 OK
Content-Type:application/json
{
"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. | The specified parameter is invalid. |
404 | Forbidden.KeyNotFound | The specified Key is not found. | The specified key does not exist. |
For a list of error codes, see Service error codes.