CipherHUB网站能力完整说明

本文档描述由 web_app、api、handlers、main_service 共同提供的完整网站能力，包括前后端通信机制、支持的算法细节、请求链路与数据约定。

1. 整体架构概览

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

┌─────────────────┐     HTTPS/HTTP      ┌──────────────────────────────────┐
│  web_app        │ ──────────────────► │  main_service (FastAPI)          │
│  nicegui_app    │   EncryptedRequest  │    /get_protection_key            │
│  (Streamlit /   │   ResponseCipherData│    /get_api_list                  │
│   NiceGUI)      │ ◄────────────────── │    POST /api                      │
└────────┬────────┘                     └───────────────┬──────────────────┘
         │                                              │
         │  sdk.client_request.CipherHUBClient          │  request_gateway
         │  • 信道加密 (ECDH + ChaCha20 + HMAC)         │  • 解密请求、校验签名
         │  • request_to_cipher_hub_api(payload)        │  • 调用 handlers
         ▼                                              ▼
┌─────────────────┐                     ┌──────────────────────────────────┐
│  api/*          │                     │  handlers/*                       │
│  请求/响应模型   │                     │  • handler_map[action] → Handler  │
│  action 枚举     │                     │  • parse_request() → do_process() │
└─────────────────┘                     └──────────────────────────────────┘

• **web_app **：前端 UI，通过 sdk 调用后端，不直接拼 HTTP，仅组业务 payload（api 下的 Request 模型）。
• main_service：FastAPI 应用，提供 /get_protection_key、/get_api_list、POST /api，在 request_gateway 中解密请求并调用 handlers。
• api：定义所有 Action、请求/响应 Pydantic 模型及业务侧算法枚举、长度限制。
• handlers：按 action 分发到具体 Handler，完成 parse_request 与 do_process，返回符合 api 的 Response。

2. 前后端通信机制

2.1 入口与协议

2.2 信道保护（传输层加解密）

业务报文在进入 /api 前、离开 /api 后均被加密与完整性保护，此处只做要点归纳：

1. 密钥协商
   • 客户端 GET /get_protection_key 拿到服务端 ECC 公钥（algorithm=ECC_ECDH）。
   • 信道保护密钥由 channel_protection 使用 ECC（默认 SECP521R1）生成，protection_keys 在服务启动时初始化（默认 256 个 key_id）。
   • 客户端用该公钥做 ECDH，派生会话用对称密钥（相关逻辑在 channel_protection.ecc_ecdh）。
2. 请求
   • 业务 payload（JSON，含 action、request_id 及各业务字段）先序列化，再：
     • 用协商出的对称密钥 + ChaCha20-Poly1305 加密（明文先做 PKCS7 填充），nonce 12 字节，密文与 nonce 拼接后以 hex 放在 encrypted_data；
     • 用同一对称密钥对明文做 HMAC-SHA512，结果 hex 放入 signature；
   • 请求体为 EncryptedRequest：key_id、encrypted_data、encrypted_key（客户端临时 ECC 公钥 hex）、signature、timestamp、request_id。
3. 响应
   • 服务端将 JSON 响应用同一会话对称密钥加密，并附 HMAC-SHA512。
   • 客户端用 sdk.client_request.decrypt_response 解密并校验签名后，再按业务 Response 模型解析。

2.3 业务请求统一结构

每个业务请求在加密前的 JSON 至少包含：

• request_id：字符串，8～64 字符，唯一标识本次请求。
• action：字符串，必须等于 api.supported_apis.ApiAction 中某一枚举的 .value。

其余字段由各业务 Request 模型定义（见第 4 节）。前端只负责按 api 中 Request 构造 dict/模型并 model_dump()，由 CipherHUBClient.request_to_cipher_hub_api(payload) 完成信道加密与发送。

2.4 服务端请求处理链路

1. POST /api 收到 EncryptedRequest。
2. request_gateway.process_request_cipher：校验 key_id，用对应服务端保护密钥与请求中的 encrypted_key 做 ECDH，得到对称密钥，解密 encrypted_data 并验证 signature，得到请求明文（JSON 字节串）。
3. 将请求明文反序列化为 CommonRequest（含 action、request_id），校验 action 合法性。
4. handlers.api_process.delivery_request：根据 action 从 handler_map 取对应 Handler 类，实例化后：
   • parse_request()：将请求体解析为该 action 的 Request 子类；
   • do_process(request)：执行业务，返回该 action 的 Response 子类；
   • 返回 response.model_dump()。
5. 将返回的 dict 序列化为 JSON，用同一对称密钥做 ChaCha20-Poly1305 加密与 HMAC-SHA512，以 ResponseCipherData 形式返回给客户端。

3. 支持的 API（Action）与 Handler 映射

api.supported_apis.ApiAction 与 handlers.handler_map 一致，下表为「Action 名称 → 功能与 Handler」的对应关系。

所有 Handler 继承 handlers.abstract_handler.ApiProcessAbstract，实现 parse_request(self) -> CommonRequest 与 do_process(self, request) -> CommonResponse。

4. 支持的算法与参数细节

以下均以 api 与 handlers 中实现的枚举、校验和常量为准（api.api_model.ConstantValues 等）。

4.1 哈希（HashSum）

4.2 HMAC（HmacSum）

4.3 分组加密（BlockCipher，CBC）

4.4 流式/AEAD 加密（StreamCipher）

4.5 ZUC（ZUCCipher）

4.6 随机数（GenerateRandomData）

4.7 RSA

• 密钥生成（GenerateRSA）
  • RSAModSize：2048、3072、4096
  • 请求：GenerateRSARequest.key_size、private_key_password（≤64 字节）
  • 响应：public_key_in_pem、private_key_in_pem（PKCS#8，可加密）
• 加密（RSAEncryption）
  • RSAEncryptionPaddingMode：RSAES_PKCS1_V1_5、RSAES_OAEP_SHA_1、RSAES_OAEP_SHA_224、RSAES_OAEP_SHA_256、RSAES_OAEP_SHA_384、RSAES_OAEP_SHA_512
  • 明文上限：501 字节（如 RSA4096+PKCS1v1.5，见 rsa_encryption_plain_max_length）
  • 公钥：PEM，长度在 rsa_pem_public_key_min_length～rsa_pem_public_key_max_length 之间
• 解密（RSADecryption）
  • 与加密相同的 Padding 枚举，请求中含 rsa_padding_mode、cipher_data_in_hex（通常由 base64 密文转 hex）、rsa_private_key_in_pem、password
• 签名（RSASign）
  • RSASignPaddingMode：PKCS1v1.5 与 PSS，各搭配 SHA1/SHA224/SHA256/SHA384/SHA512（如 RSA_SIGN_PKCS1_V1_5_SHA256、RSA_SIGN_PSS_SHA256 等）
  • 支持对原始数据签名或对预计算摘要签名（由具体 Request 字段控制）
• 验签（RSAVerification）
  • 与签名算法一一对应，请求中含公钥、原文或摘要、签名等

4.8 ECC

• 密钥生成（GenerateECC）
  • ECCCurve：ECC_SECP_256R1、ECC_SECP_384R1、ECC_SECP_521R1、ECC_SECP256K1、ECC_ED25519、ECC_X25519
  • 请求：curve、private_key_password（≤64 字节）
• 密钥协商（ECCKeyExchange）
  • 可用于 ECDH 的曲线：SECP256R1/384R1/521R1、SECP256K1、X25519（不含 Ed25519）
  • 请求：alice_ecc_private_key_in_pem、alice_ecc_private_key_password、bob_ecc_public_key_in_pem、hash_algorithm（不支持 Sm3）、salt、additional_info、derived_key_length（默认 32，限制 16～1024 字节）
  • 使用 ECDH 共享秘密 + HKDF 派生对称密钥
• 签名 / 验签（ECCSign、ECCVerification）
  • 支持曲线：SECP256R1/384R1/521R1、SECP256K1、Ed25519（X25519 不参与签名）

4.9 SM2（国密）

• 密钥生成（GenerateSM2）
  • 请求：private_key_password（≤64 字节），曲线固定为国密 SM2
• 加密（SM2Encryption）
  • SM2CipherFormat：C1C3C2_ASN1、C1C3C2、C1C2C3_ASN1、C1C2C3
  • 明文 1B～16MB；公钥 PEM 长度满足 sm2_pem_public_key_* 限制
• 解密（SM2Decryption）
  • 与加密相同的密文格式、私钥 PEM 及密码
• 签名 / 验签（SM2Sign、SM2Verify）
  • 支持对原始数据或摘要签名；摘要通常以 hex 或 base64 传入（由 sign_raw_data_mode 等字段区分）
  • 签名格式、公/私钥 PEM 长度见 ConstantValues 中 sm2_* 相关项
• 私钥结构解析（SM2PrivateKeyStructureParse）
  • 解析 SM2 私钥 PEM 的 ASN.1 结构，返回曲线、d、公钥点等（用于调试与合规检查）
• 公钥转 Hex（SM2PublicKeyToHex）
  • 将 SM2 公钥 PEM 转为 hex 表示

4.10 数据填充（DataPadding）

• DataPadding：PKCS#7 等填充与去填充，供其他流程或测试使用，对应 DataPaddingHandler。

5. 通用常量与错误码

5.1 常用数据限制（ConstantValues）

5.2 业务错误（ApiError）

api.api_model.ApiError 与各 Handler 返回的 CommonResponse.code 使用同一套语义，例如：unknown_action、invalid_request_body、process_internal_error、各算法对应的 *_failed（如 block_cipher_encrypt_failed、rsa_decrypt_cipher_failed、ecc_key_exchange_failed 等）。

信道层错误使用 channel_protection.error_model.ErrorCode（如 InvalidRequest、InvalidSymmetricKey）。

6. 前端（web_app / nicegui_app）与后端的关系

• 职责划分
  • 前端：UI、多语言（i18n）、表单校验与展示、将用户输入转为 api 中 Request 的 model_dump()，并调用 CipherHUBClient.request_to_cipher_hub_api(payload)。
  • 后端：信道加解密、action 路由、参数校验（在 api 的 Request 校验与 Handler 内）、算法实现、返回 Response。
• 请求参数一致性
  • web_app 与 nicegui_app 使用同一套 api 请求模型（如 HashSumRequest、BlockCipherRequest、RSAEncryptionRequest 等），保证与 handlers 和 main_service 的约定一致；前端仅换 UI 框架，不改 action 与字段语义。
• 能力覆盖
  • 当前 web_app（及对齐的 nicegui_app）中已对接的能力包括：Hello、GenerateRandomData、HashSum、HmacSum、BlockCipher、StreamCipher、ZUCCipher、GenerateRSA/ECC/SM2、RSA/ECC/SM2 加解密与签名验签、ECCKeyExchange、SM2PrivateKeyStructureParse，以及格式转换等本地或组合能力；每项对应到上述某一 action 或本地逻辑。

7. 参考：Action 与 api 模块对应

更细的字段说明、校验规则与枚举取值以各 api/*.py 中的 Pydantic 模型及 ConstantValues 为准。