huang
4856a88d41
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 43s
4.4 KiB
4.4 KiB
Gateway Crypto Specification
Gateway API 的加密和签名工具函数，实现 AES-128-ECB 加密和 MD5 签名机制。
ADDED Requirements
Requirement: AES-128-ECB 加密
系统 SHALL 提供 aesEncrypt 函数，使用 AES-128-ECB 模式加密业务数据。
加密流程：
- 密钥生成：
MD5(appSecret)的原始字节数组（16字节） - 加密算法：AES-128-ECB
- 填充方式：PKCS5Padding
- 编码输出：Base64
Scenario: 加密业务数据
- WHEN 调用
aesEncrypt(data, appSecret) - AND
data为业务数据的 JSON 字节数组 - THEN 返回 Base64 编码的加密字符串
- AND 密钥为
MD5(appSecret)的 16 字节数组
Scenario: PKCS5 填充正确性
- WHEN 业务数据长度不是 AES 块大小（16 字节）的整数倍
- THEN 使用 PKCS5Padding 进行填充
- AND 填充字节值等于填充长度
Scenario: 加密输出格式
- WHEN 加密成功
- THEN 输出为 Base64 字符串
- AND 字符串不包含换行符
Scenario: 加密失败
- WHEN AES 加密过程失败
- THEN 返回
CodeGatewayEncryptError错误 - AND 错误信息包含原始错误
Requirement: MD5 签名生成
系统 SHALL 提供 generateSign 函数，生成 MD5 签名。
签名流程：
- 参数排序：
appId、data、timestamp按字母升序 - 拼接字符串：
appId=xxx&data=xxx×tamp=xxx&key=appSecret - MD5 加密
- 转大写十六进制
Scenario: 生成正确的签名
- WHEN 调用
generateSign(appID, encryptedData, timestamp, appSecret) - THEN 参数按字母序拼接：
appId→data→timestamp - AND 追加
&key=appSecret - AND MD5 加密后转大写十六进制
Scenario: 签名输出格式
- WHEN 签名生成成功
- THEN 输出为 32 位大写十六进制字符串
- AND 例如："ABCDEF1234567890ABCDEF1234567890"
Scenario: 签名可重现
- WHEN 使用相同的
appID、encryptedData、timestamp、appSecret - THEN 多次调用
generateSign生成相同的签名
Scenario: 时间戳格式
- WHEN 签名中使用时间戳
- THEN 时间戳为 Unix 秒级时间戳（10 位数字）
- AND 例如：1704067200
Requirement: 参数序列化
系统 SHALL 正确序列化请求参数，确保与 Gateway 期望格式一致。
Scenario: 业务数据序列化
- WHEN 业务数据为 Go 结构体
- THEN 使用
sonic.Marshal序列化为 JSON 字符串 - AND JSON 格式与 Gateway 文档一致
Scenario: 空字段处理
- WHEN 请求结构体中某些字段为空（omitempty）
- THEN 序列化时忽略空字段
- AND 减少请求体大小
Requirement: 加密/签名测试验证
系统 SHALL 提供加密和签名的单元测试，验证与 Gateway 文档一致性。
Scenario: 加密测试用例
- WHEN 使用已知的业务数据和 appSecret
- THEN 加密输出与 Gateway 文档示例一致
- AND 可以被 Gateway 正确解密
Scenario: 签名测试用例
- WHEN 使用已知的参数和 appSecret
- THEN 签名输出与 Gateway 文档示例一致
- AND Gateway 验证签名成功
Scenario: 端到端验证
- WHEN 运行集成测试，实际调用 Gateway API
- THEN 加密和签名被 Gateway 接受
- AND 响应状态码为 200
Requirement: 性能要求
系统 SHALL 确保加密和签名操作的性能满足要求。
Scenario: 加密性能
- WHEN 加密 1KB 的业务数据
- THEN 加密时间 < 1ms
- AND 内存分配最小化
Scenario: 签名性能
- WHEN 生成签名
- THEN 签名时间 < 0.5ms
- AND 无不必要的内存分配
Requirement: 安全性说明
系统 SHALL 在文档中说明 AES-ECB 模式的安全性限制。
Scenario: 安全性文档
- WHEN 查看加密函数的文档注释
- THEN 注释中说明 ECB 模式不推荐用于生产环境
- AND 说明这是 Gateway 强制要求，无法改变
- AND 建议使用 HTTPS 加密传输层
Requirement: 字符编码一致性
系统 SHALL 确保所有字符串操作使用 UTF-8 编码。
Scenario: 字符串编码
- WHEN 序列化业务数据
- THEN 使用 UTF-8 编码
- AND 中文字符正确处理
Scenario: 签名字符串编码
- WHEN 生成签名的拼接字符串
- THEN 使用 UTF-8 编码
- AND 与 Gateway 期望的编码一致