Generates a data key.
Usage notes
The GenerateDataKey operation returns the plaintext data key and ciphertext data key. You can use the plaintext data key to encrypt data outside Key Management Service (KMS). The Plaintext parameter specifies the plaintext data key. KMS does not record or store randomly generated data keys. When you store encrypted data, you also need to store the ciphertext data key, which is specified by CiphertextBlob, and store Iv, Aad, and Algorithm.
The key specified by KeyId in the request is used only to encrypt the plaintext data key. The key is not used to generate a data key
Request message definition
message GenerateDataKeyRequest {
string KeyId = 1;
int32 NumberOfBytes = 2;
bytes Aad = 3;
}Request parameters
| Parameter | Type | Required | Example | Description |
|---|---|---|---|---|
| KeyId | string | Yes | key-hzz62f1cb66fa42qo**** | The globally unique ID of the key. You can also set the value to an alias that is bound to the key. |
| NumberOfBytes | int | Yes | 32 | The length of the data key to be generated. |
| Aad | binary | No | Binary data | The Galois/Counter Mode (GCM) mode that is used to authenticate the data when the data key is encrypted. Important Only the GCM mode is supported when you encrypt a data key. If you specify this parameter, you must specify the parameter when you call the Decrypt operation. |
Response message definition
message GenerateDataKeyResponse {
string KeyId = 1;
bytes Iv = 2;
bytes Plaintext = 3;
bytes CiphertextBlob = 4;
string RequestId = 5;
string Algorithm = 6;
}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 identifier of the key to which the alias is bound is returned in the response. |
| Iv | bytes | Binary data | The initial vector that is used when the data key is encrypted. Note When you call the Decrypt operation to decrypt the data key, you must specify a valid Iv value to decrypt the data key. |
| Plaintext | bytes | Binary plaintext | The plaintext data key. |
| CiphertextBlob | bytes | Binary ciphertext | The ciphertext data key. |
| Algorithm | string | AES_GCM | The encryption algorithm. |
| RequestId | string | 475f1620-b9d3-4d35-b5c6-3fbdd941423d | The ID of the request, which is used to locate and troubleshoot issues. |
Error codes
For more information about error codes, see Common error codes.