文档

GenerateDataKey

更新时间:

调用GenerateDataKey接口生成一个随机的数据密钥,用于本地数据加密。

注意事项

  • 非KMS实例中的密钥:进行密码运算时,仅支持通过阿里云SDK调用OpenAPI。
  • KMS实例中的密钥:进行密码运算时,支持如下两种方式。

QPS限制

本接口的单用户QPS限制为750次/秒。超过限制,API调用将会被限流,这可能影响您的业务,请合理调用。

详细说明

API随机生成的数据密钥通过您指定的主密钥(CMK)加密后,返回数据密钥的密文和明文。您可以使用返回的数据密钥明文,在KMS之外对数据进行本地离线加密。在存储加密后的数据时,也需要存储数据密钥的密文。您可以通过响应中的Plaintext字段获取到数据密钥的明文,通过CiphertextBlob字段获取到数据密钥的密文。

在请求中指定的CMK,仅会被用作数据密钥的加密,和数据密钥的生成无关。KMS不会记录或存储随机生成的数据密钥,您需要负责对数据密钥(密文)进行持久化。

建议您使用以下方式在本地进行数据加密:

1.调用GenerateDataKey接口,获得用于数据加密的密钥。

2.使用数据密钥的明文(通过响应中的Plaintext字段返回),在本地完成离线数据加密,随后清除内存中的数据密钥明文。

3.将数据密钥的密文(通过响应中的CiphertextBlob字段返回),和本地离线加密后的数据一并进行存储。

在本地解密数据:

  • 调用Decrypt接口解密本地存储的数据密钥的密文。该操作将返回数据密钥的明文。
  • 使用数据密钥的明文,在本地完成离线数据解密,随后清除内存中的数据密钥明文。

本文将提供一个示例,为ID为key-hzz630494463ejqjx****的密钥生成随机的数据密钥。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称

类型

是否必选

示例值

描述

Action String GenerateDataKey

要执行的操作。取值:GenerateDataKey

KeyId String key-hzz630494463ejqjx****

密钥的ID,也可以指定为密钥别名或密钥资源名称(ARN)。关于别名的详细介绍,请参见管理密钥别名

说明 访问其他阿里云账号下的密钥时,必须输入密钥ARN。密钥ARN的格式为acs:kms:${region}:${account}:key/${keyid}
KeySpec String AES_256

指定生成的数据密钥的长度,取值:

  • AES_256:256比特的对称密钥。
  • AES_128:128比特的对称密钥。
说明 建议使用KeySpec或者NumberOfBytes来指定数据密钥长度。如果两者都不指定,KMS生成256比特的数据密钥;如果两者都被指定,KMS会忽略KeySpec参数。
NumberOfBytes Integer 256

指定生成的数据密钥的长度,单位为字节。

取值:1~1024。

默认值:

  • 当KeySpec取值为AES_256时,NumberOfBytes默认值为32。
  • 当KeySpec取值为AES_128时,NumberOfBytes默认值为16。
EncryptionContext Map {"Example":"Example"}

key/value对的JSON字符串。

如果指定了该参数,则在调用Decrypt接口时需要提供同样的参数。更多信息,请参见EncryptionContext

DryRun String false

是否开启DryRun模式。

  • true:开启
  • false(默认值):关闭

DryRun模式用于测试API调用,验证您是否具有相应资源的权限,以及请求参数是否配置正确。DryRun模式开启后,KMS会始终返回失败并提示失败原因。失败原因包含如下:

  • DryRunOperationError:不配置DryRun参数时,请求会成功。
  • ValidationError:请求中指定的参数有误。
  • AccessDeniedError:您无权在KMS资源上执行该操作。

关于公共请求参数的详情,请参见公共参数

返回数据

名称

类型

示例值

描述

KeyVersionId String 2ab1a983-7072-4bbc-a582-584b5bd8****

密钥版本ID。主密钥版本的全局唯一标识符。

KeyId String key-hzz630494463ejqjx****

密钥ID。如果请求中的KeyId参数使用的是密钥别名、密钥ARN,在响应中也会返回密钥ID。

CiphertextBlob String ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****

数据密钥被指定密钥的主版本加密后的密文。

RequestId String 7021b6ec-4be7-4d3c-8a68-1e85d4d515a0

本次调用请求的ID,是由阿里云为该请求生成的唯一标识符,可用于排查和定位问题。

Plaintext String QmFzZTY0IGVuY29kZWQgcGxhaW50****

数据密钥的明文经过Base64编码后的值。

示例

请求示例

http(s)://[Endpoint]/?Action=GenerateDataKey
&KeyId=key-hzz630494463ejqjx****
&KeySpec=AES_256
&NumberOfBytes=256
&DryRun=false
&公共请求参数

正常返回示例

XML格式

HTTP/1.1 200 OK
Content-Type:application/xml

<GenerateDataKeyResponse>
    <KeyVersionId>2ab1a983-7072-4bbc-a582-584b5bd8****</KeyVersionId>
    <KeyId>key-hzz630494463ejqjx****</KeyId>
    <CiphertextBlob>ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****</CiphertextBlob>
    <RequestId>7021b6ec-4be7-4d3c-8a68-1e85d4d515a0</RequestId>
    <Plaintext>QmFzZTY0IGVuY29kZWQgcGxhaW50****</Plaintext>
</GenerateDataKeyResponse>

JSON格式

HTTP/1.1 200 OK
Content-Type:application/json

{
  "KeyVersionId" : "2ab1a983-7072-4bbc-a582-584b5bd8****",
  "KeyId" : "key-hzz630494463ejqjx****",
  "CiphertextBlob" : "ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****",
  "RequestId" : "7021b6ec-4be7-4d3c-8a68-1e85d4d515a0",
  "Plaintext" : "QmFzZTY0IGVuY29kZWQgcGxhaW50****"
}

错误码

HttpCode

错误码

错误信息

描述

400 UnsupportedOperation This action is not supported. 不支持的操作
404 Forbidden.AliasNotFound The specified Alias is not found. 指定的别名找不到
404 Forbidden.KeyNotFound The specified Key is not found. 指定的密钥不存在。
409 Rejected.Disabled The request was rejected because the key state is Disabled. 请求被拒绝,因为密钥状态为已禁用。
409 Rejected.PendingDeletion The request was rejected because the key state is PendingDeletion. 请求被拒绝,原因是密钥状态为待删除。
409 Rejected.Unavailable The request was rejected because the key state is Unavailable. 请求被拒绝,原因是密钥状态为不可用。

访问错误中心查看更多错误码。