edit-icon download-icon

GenerateDataKey

Last Updated: Apr 02, 2018

Description

Returns a data encryption key that you can use in your application to encrypt data locally.
This operation returns a plaintext copy of the data key in the Plaintext field of the response, and an encrypted copy of the data key in the CiphertextBlob field. The data key is encrypted under the CMK specified in the KeyId field of the request.

Note:

  • We recommend that you use the following pattern to encrypt data locally in your application:
    1. Use this operation (GenerateDataKey) to get a data encryption key.
    2. Use the plaintext data encryption key (returned in the Plaintext field of the response) to encrypt data locally, then erase the plaintext data key from memory.
    3. Store the encrypted data key (returned in the CiphertextBlob field of the response) alongside the locally encrypted data.
  • To decrypt data locally:
    1. Use the Decrypt operation to decrypt the encrypted data key into a plaintext copy of the data key.
    2. Use the plaintext data key to decrypt data locally, then erase the plaintext data key from memory.
  • When neither KeySpec nor NumberOfBytes is specified, the default value of KeySpec is AES_256.
  • When both NumberOfBytes and KeySpec are specified, NumberOfBytes prevails.

Request parameters

Name Type Required Description
KeyId String Yes Globally unique identifier of CMK. You can user aliases to call this API. For more information, see Alias Instructions.
KeySpec String No The length of the data key. Valid value: AES_256 and AES_128. AES_256 refers to a 256-bit symmetric key. AES_128 refers to a 128-bit symmetric key.
NumberOfBytes Integer No The length of the data key in bytes. Valid value: 1 to 1,024.
String No
EncryptionContext String to string map No A set of key-value pairs that represents additional authenticated data. For more information, see EncryptionContext.

Response parameters

Name Type Description
KeyId String Globally unique identifier of CMK. If you use an alias in request, the CMK ID of the alias is returned.
Plaintext String The data encryption key. The value is Base64-encoded.
CiphertextBlob String The encrypted data encryption key. The value is Base64-encoded.

Examples

Request example

  1. https://kms.cn-hangzhou.aliyuncs.com/?Action=GenerateDataKey
  2. &KeyId=<cmkid or aliasname>
  3. &KeySpec=AES_256
  4. &EncryptionContext={"Example":"Example"}
  5. &<Common Request Parameters>

Response example

JSON format

  1. //json response
  2. {
  3. "CiphertextBlob": "CiphertextBlob",
  4. "KeyId": "599fa825-17de-417e-9554-bb032cc626f0",
  5. "Plaintext": "Plaintext",
  6. "RequestId": "7021b6ec-4be7-4d3c-8a68-1e85d4d515a0"
  7. }

XML format

  1. //xml response
  2. <KMS>
  3. <CiphertextBlob>CiphertextBlob</CiphertextBlob>
  4. <KeyId>599fa825-17de-417e-9554-bb032cc626f0</KeyId>
  5. <Plaintext>Plaintext</Plaintext>
  6. <RequestId>7021b6ec-4be7-4d3c-8a68-1e85d4d515a0</RequestId>
  7. </KMS>
Thank you! We've received your feedback.