文档

GenerateDataKey

更新时间:

调用GenerateDataKey接口生成数据密钥。

使用说明

概述

本接口通过随机数生成器产生数据密钥,使用KMS密钥的初始版本对数据密钥加密,并返回数据密钥的明文和密文。您可以使用返回的数据密钥明文(Plaintext),在KMS之外对数据进行加密。请保存数据密钥密文(CiphertextBlob)、初始向量(Iv)、加密算法(Algorithm)和认证数据(Aad),以便后续对数据进行解密。

关于密钥规格以及加密模式的详细信息,请参见密钥管理类型和密钥规格

重要
  • 对数据密钥加密时仅支持GCM加密模式。

  • 数据密钥内容由KMS通过高质量的随机数生成器产生,与加密它的KMS密钥材料内容无关。

AdvanceGenerateDataKey的区别

GenerateDataKey和AdvanceGenerateDataKey都用于生成数据密钥,区别为:

  • GenerateDataKey:加密时使用密钥的初始版本,加密后您需要存储数据密钥密文(CiphertextBlob)、初始向量(Iv)、加密算法(Algorithm)和认证数据(Aad),然后使用DecryptAdvanceDecrypt解密。

  • AdvanceGenerateDataKey:仅当密钥为软件密钥管理实例的对称密钥时支持使用该接口。加密时使用密钥的主版本,加密后您需要存储数据密钥密文(CiphertextBlob)和认证数据(Aad),然后使用AdvanceDecrypt解密。

    重要

    如果密钥为软件密钥管理实例的对称密钥,且开启了自动轮转,生成数据密钥时请使用AdvanceGenerateDataKey,以避免轮转功能不生效。关于密钥轮转的相关内容,请参见密钥轮转

请求参数

名称

类型

是否必选

示例值

描述

KeyId

string

key-hzz62f1cb66fa42qo****

密钥的全局唯一标识符。该参数也可以被指定为密钥别名。

NumberOfBytes

int

32

生成的数据密钥的长度。

Aad

binary

二进制数据

对数据密钥加密时使用的GCM加密模式认证数据。

重要

对数据密钥加密时仅支持GCM加密模式。如果指定了该参数,调用Decrypt解密时需要指定相同的参数。

响应数据

名称

类型

示例值

描述

KeyId

string

key-hzz62f1cb66fa42qo****

密钥的全局唯一标识符。如果请求中的KeyId参数使用的是密钥别名,在响应中会返回对应密钥的全局唯一标识符。

Iv

bytes

二进制数据

加密数据密钥时使用的初始向量。

说明

调用Decrypt对数据密钥解密时必须传入正确的Iv才能成功解密。

Plaintext

bytes

二进制明文

数据密钥明文。

CiphertextBlob

bytes

二进制密文

数据密钥密文。

Algorithm

string

AES_GCM

加密算法。

RequestId

string

475f1620-b9d3-4d35-b5c6-3fbdd941423d

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

错误码

访问公共错误码查看更多错误码。