生成一个随机的数据密钥。可以用数据密钥进行本地数据的加密。
接口说明
注意事项
-
RAM 用户或 RAM 角色调用该 OpenAPI 需要被授予的权限策略详情，请参见访问控制。
-
本接口可以通过共享网关或专属网关调用。详细介绍，请参见阿里云 SDK。
共享网关：通过公网、VPC 域名访问 KMS，该方式需要打开公网开关。具体操作，请参见通过公网访问 KMS 实例中的密钥。
专属网关：通过 KMS 私网地址（
<YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com）访问 KMS。
QPS 限制
通过共享网关调用：本接口的单用户 QPS 限制为 1000 次/秒。超过限制，API 调用将会被限流，这可能影响您的业务，请合理调用。
通过专属网关调用：本接口的单用户 QPS 限制以您 KMS 实例的计算性能规格为准。详细介绍，请参见性能数据。
详细说明
此 API 随机生成一个数据密钥，并通过您指定的对称主密钥（Symmetric CMK）加密后，返回数据密钥的密文。此 API 和 GenerateDataKey 提供完全相同的功能，唯一的区别是此 API 不会返回数据密钥的明文。
您在请求中指定的 CMK，仅用于数据密钥的加密，不会用于数据密钥的生成。KMS 不会记录或存储随机生成的数据密钥。
此 API 适用于不需要立即使用数据密钥完成数据加密的系统。系统需要加密时，通过调用 Decrypt 接口解开数据密钥的密文。
此 API 也适用于具有不同信任等级的分布式系统。例如：您的系统将数据按照既定划分策略存储到不同的分区中。其中的一个模块会预先创建不同的数据分区，对每一个分区分别产生不同的数据密钥。这一模块完成控制平面的初始化之后，并不参与数据的生产和消费，它是密钥分发者。而数据平面的模块，在产生和消费数据的时候，首先获取分区的数据密钥密文，在解开之后使用数据密钥的明文对数据执行加密或者解密操作，随后清除内存中的数据密钥明文。在这样的系统中，密钥分发者不需要获取到数据密钥的明文，只需要使用相关 CMK 的 GenerateDataKeyWithoutPlaintext 的权限；而数据的生产和消费者，不需要产生新的数据密钥，只需要使用相关 CMK 的 Decrypt 的权限。
调试
您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。
调试
授权信息
请求参数
|
名称 |
类型 |
必填 |
描述 |
示例值 |
| KeyId |
string |
是 |
主密钥（CMK）的全局唯一标识符。该参数也可以被指定为 CMK 绑定的别名，详情请参见别名使用说明。 |
599fa825-17de-417e-9554-bb032cc6**** |
| KeySpec |
string |
否 |
指定生成的数据密钥的长度，取值：
说明
建议使用 KeySpec 或者 NumberOfBytes 来指定数据密钥长度。如果两者都不指定，KMS 生成 256 位的数据密钥；如果两者都被指定，KMS 会忽略 KeySpec 参数。 |
AES_256 |
| NumberOfBytes |
integer |
否 |
指定生成的数据密钥的长度。 |
256 |
| EncryptionContext |
object |
否 |
key/value 对的 JSON 字符串，如果指定了该参数，则在调用 Decrypt 时需要提供同样的参数，详情请参见 EncryptionContext 说明。 |
{"Example":"Example"} |
| DryRun |
string |
否 |
是否开启 DryRun 模式。
DryRun 模式用于测试 API 调用，验证您是否具有相应资源的权限，以及请求参数是否配置正确。DryRun 模式开启后，KMS 会始终返回失败并提示失败原因。失败原因包含如下：
|
false |
返回参数
|
名称 |
类型 |
描述 |
示例值 |
|
object |
|||
| KeyVersionId |
string |
用于加密明文的密钥版本标志符。是指定 CMK 的主版本。 |
2ab1a983-7072-4bbc-a582-584b5bd8**** |
| KeyId |
string |
CMK 的全局唯一标识符。 说明
如果请求中的 KeyId 参数使用的是 CMK 的别名，在响应中会返回别名对应的 CMK 标志符。 |
599fa825-17de-417e-9554-bb032cc6**** |
| CiphertextBlob |
string |
数据密钥被指定 CMK 的主版本加密后的密文。 |
ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS**** |
| RequestId |
string |
本次调用请求的 ID，是由阿里云为该请求生成的唯一标识符，可用于排查和定位问题。 |
7021b6ec-4be7-4d3c-8a68-1e85d4d515a0 |
示例
正常返回示例
JSON格式
{
"KeyVersionId": "2ab1a983-7072-4bbc-a582-584b5bd8****",
"KeyId": "599fa825-17de-417e-9554-bb032cc6****",
"CiphertextBlob": "ODZhOWVmZDktM2QxNi00ODk0LWJkNGYtMWZjNDNmM2YyYWJmS7FmDBBQ0BkKsQrtRnidtPwirmDcS0ZuJCU41xxAAWk4Z8qsADfbV0b+i6kQmlvj79dJdGOvtX69Uycs901qOjop4bTS****",
"RequestId": "7021b6ec-4be7-4d3c-8a68-1e85d4d515a0"
}错误码
|
HTTP status code |
错误码 |
错误信息 |
描述 |
|---|---|---|---|
| 400 | InvalidParameter | The specified parameter is not valid. | 参数非法。 |
| 404 | InvalidAccessKeyId.NotFound | The Access Key ID provided does not exist in our records. | |
| 404 | Forbidden.KeyNotFound | The specified Key is not found. | 指定的密钥不存在。 |
访问错误中心查看更多错误码。
变更历史
更多信息，参考变更详情。