全部产品
Search
文档中心

密钥管理服务:AdvanceGenerateDataKey

更新时间:Aug 08, 2023

用于生成数据密钥,对数据按照KMS信封加密方式加密。

使用说明

概述

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

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

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

和GenerateDataKey的区别

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

  • AdvanceGenerateDataKey:加密时使用密钥的主版本,加密后您需要存储数据密钥密文(CiphertextBlob)和认证数据(Aad),然后使用AdvanceDecrypt解密。

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

重要

如果密钥开启了自动轮转,生成数据密钥时请使用AdvanceGenerateDataKey,以避免轮转功能不生效。关于密钥轮转的相关内容,请参见密钥轮转

使用限制

仅当密钥为KMS软件密钥管理实例中的对称密钥时,支持使用本接口。关于密钥规格以及加密模式的详细信息,请参见密钥管理类型和密钥规格

请求参数

名称

类型

是否必选

示例值

描述

KeyId

string

key-hzz62f1cb66fa42qo****

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

重要

密钥必须为KMS软件密钥管理实例中的对称密钥。

NumberOfBytes

int

32

生成的数据密钥的长度。

Aad

binary

二进制数据

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

重要

如果指定了该参数,调用AdvanceDecrypt解密时需要指定相同的参数。

响应数据

名称

类型

示例值

描述

CiphertextBlob

bytes

二进制密文

数据密钥密文。

说明

CiphertextBlob中还包含密钥标识(KeyId)、加密算法(Algorithm)、加密数据时使用的初始向量(Iv)等信息,通过AdvanceDecrypt解密时仅需传入CiphertextBlob、认证数据(Aad)。

Plaintext

bytes

二进制明文

数据密钥明文。

KeyId

string

key-hzz62f1cb66fa42qo****

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

KeyVersionId

string

key-hzz62f1cb66fa42qo****-17kedv****

加密数据密钥的密钥版本标志符。

Algorithm

string

AES_GCM

加密算法。

Iv

bytes

二进制数据

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

RequestId

string

c0065a6d-7784-4ef2-a692-288fdcbc7b9d

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

错误码

HTTP状态码

错误码

错误消息

描述

404

Forbidden.OnlySymmetricKeySupported

The key %s is not a symmetric key. The API only supports symmetric keys.

仅支持使用对称密钥。

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