全部产品
Search
文档中心

密钥管理服务:AdvanceEncrypt

更新时间:Jan 24, 2024

用于将明文数据通过KMS密钥加密为密文。

使用说明

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

AdvanceEncrypt和Encrypt都用于将明文数据加密为密文,区别为:

重要

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

注意事项

所有请求参数使用Protocol Buffers编码后(即Request Body),内容长度不能超过3 MB,超过3 MB后服务端会拒绝处理并返回HTTP 413状态码。建议单次加解密的数据不超过6 KB,超过6 KB时请使用信封加密方案。详细信息,请参见使用KMS密钥进行信封加密

说明

单次加解密的数据量越大,网络传输失败可能性越大,网络传输所需时间越长,KMS实例对数据进行加解密所需时间也越长。

请求参数

名称

类型

是否必选

示例值

描述

KeyId

string

key-hzz62f1cb66fa42qo****

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

重要

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

Plaintext

bytes

二进制数据

待加密的明文数据。

Algorithm

string

AES_GCM

加密算法。

如果未指定本参数,KMS会使用加密算法默认值。更多信息,请参见密钥管理类型和密钥规格

Iv

bytes

二进制数据

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

仅当加密算法(Algorithm)为AES_GCM、AES_CBC时本参数有效。

  • 加密算法(Algorithm)为AES_CBC时:Iv长度为16字节。

  • 加密算法(Algorithm)为AES_GCM时:Iv长度为12字节。

如果未指定本参数,KMS将随机生成。

重要

推荐您不指定本参数,由KMS随机生成。

Aad

binary

二进制数据

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

当加密算法(Algorithm)是AES_GCM时,您可以根据业务需要使用本参数。

重要

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

PaddingMode

string

PKCS7_PADDING

填充模式。

仅当加密算法(Algorithm)为AES_CBC或AES_ECB时,需要指定本参数。

取值:

  • PKCS7_PADDING(默认值):即PKCS#7填充。数据明文或密文内容的长度可以不是相应密码算法的块大小(K字节)的整数倍。

    当输入数据明文或密文内容长度为L字节时,系统将填充K -(L mod K)字节的内容,填充的每个字节均为K -(L mod K)。

  • NO_PADDING:不对数据明文填充。数据明文内容的长度必须为相应密码算法的块大小的整数倍。

响应数据

名称

类型

示例值

描述

CiphertextBlob

bytes

二进制数据

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

说明

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

Algorithm

string

AES_GCM

加密算法。

KeyId

string

key-hzz62f1cb66fa42qo****

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

KeyVersionId

string

key-hzz62f1cb66fa42qopd9s-17kedv****

加密时使用的密钥版本。本接口使用密钥当时的主版本。

Iv

bytes

二进制数据

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

仅当加密算法(Algorithm)为AES_GCM、AES_CBC时,本参数返回有效值,其他场景返回空值。

PaddingMode

string

PKCS7_PADDING

填充模式。仅当加密算法(Algorithm)为AES_CBC或AES_ECB时,本参数返回有效值,其他场景返回空值。

RequestId

string

c0037a6d-7784-4ef2-a692-288fdefc7b9d

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

错误码

HTTP状态码

错误码

错误消息

描述

404

Forbidden.OnlySymmetricKeySupported

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

仅支持使用对称密钥。

说明

非对称加密一般用于跨安全域的数据加密或密钥交换,这意味着通常有一端不使用阿里云KMS。

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