将明文数据加密为密文。_密钥管理服务(KMS)-阿里云帮助中心

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

使用说明

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

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

AdvanceEncrypt：加密时使用密钥的主版本，加密后需要使用AdvanceDecrypt解密。
Encrypt：加密时使用密钥的初始版本，加密后可以使用Decrypt或AdvanceDecrypt解密。

重要

如果密钥开启了自动轮转，加密时请使用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。

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