跳到主要内容

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

1. 接口描述​

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

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

image

请求端加密流程

  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, bizApplicationId, 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,
        ApplicationId:       bizApplicationId,
        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": "ChannelDescribeFlowComponents",
  "ApplicationId: "yD******************************,
  "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": "ChannelDescribeFlowComponents",
  "ApplicationId: "yD******************************,
  "IV": "ZmVkY2JhMDk4NzY1NDMyMQ==",
  "EncryptedData": "GwUovQhNUPaUnVM/UDXMtPOYTpTSi2B1oyZDFbyyvns=",
  "EncryptionSignature": "nHB/v/AvOaDCQ66esFNnp12lHKcGkwaLGid0Warl/KE="
}

默认接口请求频率限制：20次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数​

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

参数名称必选类型描述
Action是String公共参数，本接口取值：CreateRequestWithEncryption。
Version是String公共参数，本接口取值：2021-05-26。
Region否String公共参数，本接口不需要传递此参数。
RequestAction是String

操作的接口名称。取值参考接口文档输入参数章节关于公共参数 Action 的说明。


示例值：ChannelDescribeFlowComponents
ApplicationId是String

第三方应用的唯一标识，对应通用参数 Agent.AppId。


示例值：yD**
IV是String

加密算法使用的初始化向量。固定为 16 字节，将 IV 原始字节使用标准 Base64 编码后传入。


示例值：mJc2aKe4B71d9p62y6bp2A==
EncryptedData是String

使用 AES-CBC 或 SM4-CBC 加密请求内容得到的密文。加密前请求内容采用 PKCS#7 Padding；将密文原始字节使用标准 Base64 编码后传入。


示例值：riUP2CKf+QGCfN9VMjTgCbsPidmXJulBUD8jxdg3YZwecWCF1CTg+4zB1nEICbGPRedPjF0+zZ1ybTDEc/xG/nQ5J7n4+uNiWCCOqRsjDcwzoD1gZ+y1W++qdjjCns/z8SMxciKmSS7h/cL5kwUARg==
EncryptionSignature否String

用于校验请求数据完整性。对 IV 原始字节和密文原始字节直接拼接（不加拼接符）后计算 HMAC-SHA256，再将计算结果使用标准 Base64 编码后传入。


示例值：vzOw7yV+oAaYBmpbDDGfl7OGxuN3M38IjpJG/mTnEzE=

3. 输出参数​

参数名称类型描述
IVString

加密算法使用的初始化向量。固定为 16 字节，将 IV 原始字节使用标准 Base64 编码后传入。


示例值：xJVzDCv28EtziawMOIhgGA==
EncryptedDataString

使用 AES-CBC 或 SM4-CBC 加密返回内容得到的密文。加密前返回内容采用 PKCS#7 Padding；将密文原始字节使用标准 Base64 编码后传入。


示例值：vPMmeHGhjZOh5uBcnTmcsgamkGHPrwVCcf9ifqAp03M/pdi3yalY86ytw5fL1VbUg+97j/DZpcejEld5mq5Qa1Sk+L6WIgKc8Wc2Bu5LNB5ktM6b5Xy09MXdWvxQV0l40XlhEEQ2bNqI/G7AfJpRLxNLRbK2VH/DFy+ga8o6snHQE3OojM3ZQgM6gLcQ/6MudNChL95Bf3SEWnrr4lqKLdZWJxOOj/XR/iQD/VSr1XE=
EncryptionSignatureString

用于校验请求数据完整性。对 IV 原始字节和密文原始字节直接拼接（不加拼接符）后计算 HMAC-SHA256，再将计算结果使用标准 Base64 编码后传入。


示例值：ReXDVVwCHf1bgoW/al4NAs9r2dzWWfmV0zVNDl1Kne8=
RequestIdString唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

4. 示例​

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

输入示例​

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

{
    "RequestAction": "ChannelDescribeFlowComponents",
    "ApplicationId": "yD******************************",
    "IV": "mJc2aKe4B71d9p62y6bp2A==",
    "EncryptedData": "riUP2CKf+QGCfN9VMjTgCbsPidmXJulBUD8jxdg3YZwecWCF1CTg+4zB1nEICbGPRedPjF0+zZ1ybTDEc/xG/nQ5J7n4+uNiWCCOqRsjDcwzoD1gZ+y1W++qdjjCns/z8SMxciKmSS7h/cL5kwUARg==",
    "EncryptionSignature": "vzOw7yV+oAaYBmpbDDGfl7OGxuN3M38IjpJG/mTnEzE="
}

输出示例​

{
    "Response": {
        "EncryptedData": "vPMmeHGhjZOh5uBcnTmcsgamkGHPrwVCcf9ifqAp03M/pdi3yalY86ytw5fL1VbUg+97j/DZpcejEld5mq5Qa1Sk+L6WIgKc8Wc2Bu5LNB5ktM6b5Xy09MXdWvxQV0l40XlhEEQ2bNqI/G7AfJpRLxNLRbK2VH/DFy+ga8o6snHQE3OojM3ZQgM6gLcQ/6MudNChL95Bf3SEWnrr4lqKLdZWJxOOj/XR/iQD/VSr1XE=",
        "EncryptionSignature": "ReXDVVwCHf1bgoW/al4NAs9r2dzWWfmV0zVNDl1Kne8=",
        "IV": "xJVzDCv28EtziawMOIhgGA==",
        "RequestId": "b91d7791-644f-4404-984b-b0c8a10e58b0"
    }
}

5. 错误码​

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

更多开发者交流反馈