文档

GenerateDataKeyPair

更新时间:

调用GenerateDataKeyPair接口生成非对称的数据密钥对。

使用说明

本接口通过随机数生成器产生数据密钥对,使用对称密钥的初始版本对数据密钥对加密,并返回数据密钥对的公钥明文、私钥明文、私钥密文。您可以使用数据密钥对,在KMS之外进行签名验签。

请保存私钥密文(PrivateKeyCiphertextBlob)、初始向量(Iv)、加密算法(Algorithm)、认证数据(Aad),以便后续使用Decrypt对私钥密文进行解密。

KMS提供了如下接口,用于生成数据密钥对,具体之间的区别请参见下表。

API

使用场景

API的返回数据

加密时的密钥版本

解密时的API接口

GenerateDataKey

加密的密钥未设置自动轮转,且您需要立即获取私钥明文。

公钥明文、私钥明文、私钥密文。

密钥的初始版本。

Decrypt

GenerateDataKeyPairWithoutPlaintext

加密的密钥未设置自动轮转,且您暂时不使用私钥明文或者需要更高的安全性。

公钥明文、私钥密文,不返回私钥明文。

密钥的初始版本。

Decrypt

AdvanceGenerateDataKeyPair

加密的密钥设置了自动轮转,且您需要立即获得私钥明文。

说明

关于密钥轮转的相关内容,请参见密钥轮转

公钥明文、私钥明文、私钥密文。

密钥的主版本。

AdvanceDecrypt

AdvanceGenerateDataKeyPairWithoutPlaintext

加密的密钥设置了自动轮转,且您暂时不使用私钥明文或者需要更高的安全性。

公钥明文、私钥密文,不返回私钥明文。

密钥的主版本。

AdvanceDecrypt

注意事项

针对生成数据密钥对的接口GenerateDataKeyPair、 GenerateDataKeyPairWithoutPlaintext、AdvanceGenerateDataKeyPair和AdvanceGenerateDataKeyPairWithoutPlaintext,一般情况下每个KMS实例,每次仅支持处理一个请求,请您控制好并发请求。如超出并发限制,KMS将返回429报错(Concurrency Limit Exceeded)。

请求参数

名称

类型

是否必选

示例值

描述

KeyId

string

key-hzz62f1cb66fa42qo****

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

说明

仅支持软件密钥管理实例中的对称密钥。

KeyPairSpec

string

RSA_2048

指定生成的数据密钥对的类型。取值:

  • RSA_2048

  • RSA_3072

  • RSA_4096

  • EC_P256

  • EC_P256K

Aad

bytes

二进制数据

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

重要

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

KeyFormat

string

PEM

生成的数据密钥对格式。取值:

  • PEM

  • DER

响应数据

名称

类型

示例值

描述

KeyId

string

key-hzz62f1cb66fa42qo****

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

Iv

bytes

二进制数据

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

说明

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

KeyPairSpec

string

RSA_2048

生成的数据密钥对的类型。

PrivateKeyCiphertextBlob

bytes

二进制数据

数据密钥对的私钥密文。

PrivateKeyPlaintext

bytes

二进制数据

数据密钥对的私钥明文。

  • 当请求参数中KeyFormat为DER时,返回DER格式的PKCS#8私钥明文。

  • 当请求参数中KeyFormat为PEM时,返回PEM格式的PKCS#8私钥明文。

PublicKey

bytes

二进制数据

数据密钥对的公钥明文。

  • 当请求参数中KeyFormat为DER时,返回DER格式的X.509公钥明文。

  • 当请求参数中KeyFormat为PEM时,返回PEM格式的X.509公钥明文。

Algorithm

string

AES_GCM

加密算法。仅支持AES_GCM。

RequestId

string

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

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

错误码

HTTP状态码

错误码

错误信息

描述

429

Rejected.Throttling

Concurrency Limit Exceeded.

并发超过限制。

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