用于将明文数据通过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时本参数有效。
如果未指定本参数,KMS将随机生成。 重要 推荐您不指定本参数,由KMS随机生成。 |
Aad | binary | 否 | 二进制数据 | 对数据密钥加密时使用的GCM加密模式认证数据。 当加密算法(Algorithm)是AES_GCM时,您可以根据业务需要使用本参数。 重要 如果指定了本参数,调用AdvanceDecrypt解密时需要指定相同的参数。 |
PaddingMode | string | 否 | PKCS7_PADDING | 填充模式。 仅当加密算法(Algorithm)为AES_CBC或AES_ECB时,需要指定本参数。 取值:
|
响应数据
名称 | 类型 | 示例值 | 描述 |
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。 |
访问公共错误码查看更多错误码。