huang
62708892ec
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m2s
156 lines
4.4 KiB
Markdown
156 lines
4.4 KiB
Markdown
# Gateway Crypto Specification
|
||
|
||
Gateway API 的加密和签名工具函数，实现 AES-128-ECB 加密和 MD5 签名机制。
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: AES-128-ECB 加密
|
||
|
||
系统 SHALL 提供 `aesEncrypt` 函数，使用 AES-128-ECB 模式加密业务数据。
|
||
|
||
加密流程：
|
||
1. 密钥生成：`MD5(appSecret)` 的原始字节数组（16字节）
|
||
2. 加密算法：AES-128-ECB
|
||
3. 填充方式：PKCS5Padding
|
||
4. 编码输出：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 签名。
|
||
|
||
签名流程：
|
||
1. 参数排序：`appId`、`data`、`timestamp` 按字母升序
|
||
2. 拼接字符串：`appId=xxx&data=xxx×tamp=xxx&key=appSecret`
|
||
3. MD5 加密
|
||
4. 转大写十六进制
|
||
|
||
#### 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 期望的编码一致
|