以加密请求体方式创建请求

1. 接口描述

接口请求域名： ess.tencentcloudapi.com 。

该接口支持对请求内容进行加密传输。调用方需使用约定的 AES-CBC 或 SM4-CBC 算法对请求内容进行加密，并使用 HMAC-SHA256 或 HMAC-SM3 算法对 IV 和加密后的数据进行完整性校验，防止请求内容被篡改。

请求端加密流程

1. 每次请求使用密码学安全的随机源生成 16 字节 的 IV。每次请求必须重新生成，严禁复用。
2. 使用约定的 AES-CBC 或 SM4-CBC 算法对原始请求体进行加密，使用 PKCS#7 Padding。
3. 将加密后的密文原始字节进行标准 Base64 编码，作为 EncryptedData 参数。
4. 将 IV 原始字节进行标准 Base64 编码，作为 IV 参数。
5. 对 IV 原始字节和密文原始字节直接拼接（不添加分隔符），计算 HMAC-SHA256 或 HMAC-SM4：HMAC(Key, IVBytes || CiphertextBytes)
6. 将 HMAC 的结果进行 标准 Base64 编码，作为 EncryptionSignature 参数。

响应端解密流程

1. 先判断本接口自身是否返回外层错误，此时错误为明文（标准腾讯云错误体），有则直接失败处理。
2. 分别对 IV、EncryptedData、EncryptionSignature 做标准 Base64 解码，得到原始字节。
3. 将 IV 与密文原始字节直接拼接（无分隔符），计算 HMAC-SHA256 或 HMAC-SM4：HMAC(Key, IVBytes || CiphertextBytes)。
4. 与响应中 EncryptionSignature 解码后的字节做恒定时间比较，不一致立即失败，不得继续解密。
5. 使用约定的 AES-CBC 或 SM4-CBC，以 IV 和密钥解密 EncryptedData，去除 PKCS#7 Padding 得到明文。
6. 先用腾讯云标准错误体反序列化明文，判断被加密业务接口是否返回 Error。
7. 无业务错误时，再用目标业务接口的响应结构体反序列化明文，取出实际业务参数。

响应端错误处理

1. 外层错误（本接口本身调用失败）：返回标准腾讯云错误 JSON（含 Error.Code / Error.Message），无 EncryptedData，不需要解密即可处理。
2. 内层错误（业务接口执行失败）：外层成功，但解密后的明文里包含 Error.Code / Error.Message，按目标业务接口的错误规范处理。

处理过程示例

# ========== 前置约定 ==========
AESKey  : 加密 密钥（AES 32 字节，SM4 16 字节）
HMACKey : HMAC 密钥（与加密密钥需要不同）
ALGO    : AES-CBC 或 SM4-CBC，双方约定
HMAC    : ALGO == AES-CBC ? HMAC-SHA256 : HMAC-SM3

# ========== 请求端：加密并调用 ==========
function CallWithEncryption(bizAction, bizRequestObj):
    # 1. 序列化业务请求
    plaintext = JSON.stringify(bizRequestObj)
    # 2. 生成 16 字节随机 IV（每次新生成，禁止复用）
    iv = SecureRandom(16)
    # 3. 对称加密（PKCS#7 Padding）
    ciphertext = SymmetricEncrypt(ALGO, AESKey, iv, plaintext)
    # 4. 计算完整性签名：HMAC(Key, IV || Ciphertext)
    signature = HMAC(HMACKey, concat(iv, ciphertext))
    # 5. 组装外层请求参数
    encReq = {
        RequestAction:       bizAction,
        IV:                  Base64(iv),
        EncryptedData:       Base64(ciphertext),
        EncryptionSignature: Base64(signature),
    }
    # 6. 调用 CreateRequestWithEncryption
    #    TC3-HMAC-SHA256 鉴权由官方 SDK 自动完成
    encResp = CloudAPI.CreateRequestWithEncryption(encReq)
    # 7. 外层错误：明文，直接抛出
    if encResp.Error != nil:
        raise OuterError(encResp.Error)
    # 8. 解密并返回业务响应
    return DecryptResponse(encResp.Response)

# ========== 响应端：校验并解密 ==========
function DecryptResponse(resp):
    # 1. Base64 解码
    ivBytes  = Base64Decode(resp.IV)
    ctBytes  = Base64Decode(resp.EncryptedData)
    sigBytes = Base64Decode(resp.EncryptionSignature)
    # 2. 重新计算 HMAC
    expected = HMAC(HMACKey, concat(ivBytes, ctBytes))
    # 3. 恒定时间比较，失败立即终止（不得继续解密）
    if not ConstantTimeEqual(expected, sigBytes):
        raise SignatureMismatch
    # 4. 对称解密，去除 PKCS#7 Padding
    plaintext = SymmetricDecrypt(ALGO, AESKey, ivBytes, ctBytes)
    # 5. 先按腾讯云错误体解析，判断业务是否失败
    bizErr = TryParseTencentCloudError(plaintext)
    if bizErr != nil:
        raise BusinessError(bizErr)
    # 6. 按目标业务接口的响应结构反序列化
    return JSON.parse(plaintext, BizResponseSchema)

AES-CBC 示例

以下示例参数及结果可用于验证 AES-CBC 加密和 HMAC-SHA256 签名算法的实现是否正确。

加密密钥：AES-CBC-Key-1234
签名密钥：AES-HMAC-Key-123
IV：1234567890abcdef
请求内容：{"Request": "This is a test."}

最终请求参数：

{
  "RequestAction": "DescribeFlowComponents",
  "IV": "MTIzNDU2Nzg5MGFiY2RlZg==",
  "EncryptedData": "Iqp2W1jislwMNmE7bH9dKZZiMQsfkAPyvAAqDFRnWLw=",
  "EncryptionSignature": "4TT3PUCZgZT7YmEPtXDm5PDcM6xT7FoYHfMW8xunB5I="
}

SM4-CBC 示例

以下示例参数及结果可用于验证 SM4-CBC 加密和 HMAC-SM4 签名算法的实现是否正确。

加密密钥：SM4-CBC-Key-1234
签名密钥：SM4-HMAC-Key-123
IV：fedcba0987654321
请求内容：{"Request": "This is a test."}

最终请求参数：

{
  "RequestAction": "DescribeFlowComponents",
  "IV": "ZmVkY2JhMDk4NzY1NDMyMQ==",
  "EncryptedData": "GwUovQhNUPaUnVM/UDXMtPOYTpTSi2B1oyZDFbyyvns=",
  "EncryptionSignature": "nHB/v/AvOaDCQ66esFNnp12lHKcGkwaLGid0Warl/KE="
}

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。

3. 输出参数

4. 示例

示例1 以加密请求体方式创建请求

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateRequestWithEncryption
<公共请求参数>

{
    "RequestAction": "DescribeFlowComponents",
    "IV": "ZeuAMEj5nEGZUtekyKqxKw==",
    "EncryptedData": "v7vwDVtF+ftVANPClwZxrCCKM1dgOq+X5rCDGdlNqwQ6wRzndA8QxLc7YA+txKeU92cqTdtuji3e+Il+uVJ0qQ4fnVM/A5WmLEp6adq7+iW7LxHc9qo72suf630bdYHrA9iuzr0nqUd05ronubzSFQ==",
    "EncryptionSignature": "uSnCx/PE/CTlckq5tZ+xqJMC2dd5Bg8Zg/ATSK0apkI="
}

输出示例

{
    "Response": {
        "EncryptedData": "60m8IgrRfRDWarWGd1KngYXdG0zYRNAv29iRMsR333F4nNoZhQvhXZo61DbUcm8YlEUfdLhDjK9f9fRXMr+ARH+3vOI/3k+owr3IYJAQeQ4p0zky95j8znlae3JBOwm06P/ED+dU90s9tb8pM3n0S06TpAxBZxryVmPpnqFyuDlbt9W5eb1KVz56WbPTp4QyjKWksc6tezquKe9FLx8u/x1/ZzHaunur2+StM2KkSZ8=",
        "EncryptionSignature": "z2aKvBr/WkSXWKwpu0LX2V1S2ZGP9K3LLP1hEfhJOWM=",
        "IV": "z/p4htlS/UwLpHwxHbyrFw==",
        "RequestId": "bde98308-b4b9-49c1-b46b-51d1d55d41da"
    }
}

5. 开发者资源

腾讯云 API 平台

腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。

SDK

云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。

• Tencent Cloud SDK 3.0 for Python: CNB, GitHub, Gitee
• Tencent Cloud SDK 3.0 for Java: CNB, GitHub, Gitee
• Tencent Cloud SDK 3.0 for PHP: CNB, GitHub, Gitee
• Tencent Cloud SDK 3.0 for Go: CNB, GitHub, Gitee
• Tencent Cloud SDK 3.0 for Node.js: CNB, GitHub, Gitee
• Tencent Cloud SDK 3.0 for .NET: CNB, GitHub, Gitee
• Tencent Cloud SDK 3.0 for C++: CNB, GitHub, Gitee
• Tencent Cloud SDK 3.0 for Ruby: CNB, GitHub, Gitee

命令行工具

• Tencent Cloud CLI 3.0

6. 错误码

该接口暂无业务逻辑相关的错误码，其他错误码详见 公共错误码。