1. 通信流程与加密机制

1.1 通信流程

  • 客户端通过 CipherHUBClient 类与服务端通信，所有业务请求都通过 /api POST 接口，先加密后发送。
  • 客户端首先通过 /get_protection_key 获取服务端分发的 ECC 公钥（PEM 格式），用于后续会话密钥协商。
  • 客户端通过 /get_api_list 获取支持的 API 列表。
  • 业务请求通过 /api，请求体为加密后的数据结构。

1.2 加密与签名

  • 密钥交换：客户端用服务端分发的 ECC 公钥，临时生成 ECC 密钥对，使用 ECDH 协议协商出 32 字节对称密钥（HKDF-SHA512 派生）。
  • 数据加密：业务明文用 ChaCha20-Poly1305（12字节随机nonce，PKCS7填充）加密，密文与nonce拼接。
  • 签名：用协商出的对称密钥对明文做 HMAC-SHA512，生成签名。
  • 请求结构：包含密钥ID、加密数据、临时公钥、签名、时间戳、请求ID。

2. 主要接口说明

2.1 获取保护密钥

  • 接口：GET /get_protection_key
  • 返回：
    • key_id：字符串，唯一标识
    • public_key：PEM格式字符串
    • algorithm：目前仅支持 ECC_ECDH

2.2 获取API列表

  • 接口：GET /get_api_list
  • 返回：字符串数组，所有支持的 action 名称

2.3 业务请求

  • 接口：POST /api
  • 请求体：EncryptedRequest（JSON）
    • key_id：保护密钥ID
    • encrypted_data：ChaCha20-Poly1305加密后的密文+nonce，hex编码
    • encrypted_key：临时ECC公钥，hex编码
    • signature：HMAC-SHA512签名，hex编码
    • timestamp：ISO8601字符串
    • request_id：唯一请求ID
  • 响应体：ResponseCipherData（JSON）
    • encrypted_data：加密响应数据，hex编码
    • nonce：12字节nonce，hex编码
    • signature：HMAC-SHA512签名，hex编码
  • 解密流程：客户端用临时密钥解密响应，校验签名。

3. 业务参数与限制

3.1 通用参数

  • request_id：字符串，唯一标识本次请求
  • action：字符串，API名称，详见 /get_api_list 返回
  • 其他参数见各业务API定义

3.2 业务API参数与限制

所有业务API参数均有严格校验，常见限制如下（详见 api/api_model.py 的 ConstantValues）：

  • 明文/密文最大长度：16MB（max_data_length）
  • 密钥长度：AES256/SM4为32字节，AES128为16字节，ZUC为16字节
  • IV/Nonce长度：一般为12或16字节
  • 密码最大长度：64字节
  • 盐最大长度：64字节
  • 附加信息最大长度：256字节
  • 生成随机数最大长度：128字节
  • PEM密钥格式有最小/最大长度限制
  • 具体API如 SM2/RSA/ECC 签名、加解密、密钥交换等，详见各自的 Request 类定义（如 SM2SignRequest、BlockCipherRequest 等），每个字段均有类型和长度校验。

例：BlockCipherRequest

  • input_data_in_hex：明文/密文，hex字符串，1B~16MB
  • key_in_hex：密钥，hex字符串，16/32字节
  • iv_in_hex：IV，hex字符串，16字节
  • algorithm：字符串，算法名
  • process_type：加密/解密
  • action：固定为 BlockCipher

例：SM2SignRequest

  • sm2_private_key_in_pem：PEM格式私钥，长度400~512
  • sm2_private_key_password：密码，最长64字节
  • data_in_hex：待签名数据，hex字符串
  • sign_raw_data_mode：布尔，是否对原文签名
  • action：固定为 SM2Sign

4. 编码方式

  • 所有二进制数据（如密文、密钥、签名、nonce等）均用 hex 字符串编码传输。
  • 所有结构体均用 JSON 编码。
  • 时间戳用 ISO8601 字符串。

5. 错误处理

  • 所有接口返回均有 code 和 msg 字段，见 ApiError 和 ErrorCode 枚举。
  • 校验失败、解密失败、签名校验失败等均有详细错误码和信息。

6. 客户端调用示例

见 client_demo/ 目录下各脚本，均为标准用法示例。典型流程如下：

1
2
3
4
5
6
7

from sdk.client_request import CipherHUBClient
from api.hello_api import HelloRequest

client = CipherHUBClient()
hello = HelloRequest(request_id='test', client_msg='hello')
payload = hello.model_dump()
response = client.request_to_cipher_hub_api(payload)

7. 参考结构体（部分）

EncryptedRequest

1
2
3
4
5
6
7
8

{
  "key_id": "string",
  "encrypted_data": "hexstring",
  "encrypted_key": "hexstring",
  "signature": "hexstring",
  "timestamp": "2025-07-01T12:00:00",
  "request_id": "string"
}

ResponseCipherData

1
2
3
4
5

{
  "encrypted_data": "hexstring",
  "nonce": "hexstring",
  "signature": "hexstring"
}