API签名机制
1. 概述
API签名机制是一种安全措施，用于验证API请求的合法性和完整性，同时防止请求被篡改或重放。本文档描述了我们的API签名机制的工作原理、实现方式以及集成指南。
2. 签名机制原理
2.1 基本流程
- 客户端获取API密钥（AccessKeyId）和对应的密钥（SecretKey）
- 客户端按照规则构造请求参数，包含必要的认证信息
- 客户端使用SecretKey对请求参数进行签名计算
- 客户端将签名和请求参数一起发送到服务器
- 服务器验证签名，通过验证后处理请求
2.2 安全特性
- 身份认证：确保API调用者是合法授权的用户
- 数据完整性：防止请求被篡改
- 防重放攻击：通过时间戳和随机数（nonce）机制防止请求被重放
- 密钥保护：SecretKey不在请求中直接传输
3. 签名参数说明
3.1 基本参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| AccessKeyId | String | 是 | 访问密钥ID |
| channelId | String | 是 | 合作渠道方ID，标识调用方身份 |
| timestamp | Long | 是 | 请求时间戳（毫秒） |
| nonce | String | 是 | 随机字符串，用于防重放攻击 |
| signature | String | 是 | 请求签名 |
3.2 签名算法
支持的签名算法：
- MD5（默认，最快）
- SHA1
- SHA256
- HMAC-SHA256（最安全）
4. 签名计算方法
- 收集所有请求参数（URL参数、表单参数），不包括signature参数
- 按参数名称字典序升序排序
- 构造规范化的请求字符串：
key1=value1&key2=value2&...（URL编码非字母数字字符） - 在请求字符串末尾添加密钥：
key1=value1&key2=value2&...&key=YOUR_SECRET_KEY - 使用指定算法计算签名：
signature = HASH_ALGORITHM(规范化请求字符串) - 将签名以十六进制形式添加到请求参数
5. 安全注意事项
- SecretKey必须妥善保管，不可泄露
- 服务端验证时间戳，拒绝处理超过5分钟的请求
- 服务端记录并验证nonce，拒绝处理重复的nonce（防重放）
- 采用HTTPS传输增强安全性
- channelId与AccessKeyId必须匹配，防止身份冒用
6. 集成说明
我们提供了多种语言的API签名工具实现，存放在各自对应的目录中：
/go- Go语言实现/rust- Rust语言实现/java- Java语言实现/kotlin- Kotlin语言实现/python- Python语言实现/typescript- TypeScript语言实现/csharp- C#语言实现
每种语言实现都包含完整的签名计算和验证功能，以及详细的使用示例。开发者可以根据项目需求选择合适的语言实现，并参考示例进行集成。
7. 快速测试
每个语言实现目录中都包含可以直接运行的测试程序，方便开发者测试签名机制。测试程序默认使用根目录下的.env文件中的配置参数，您可以根据需要修改这些参数。
```
# .env文件示例
ACCESS_KEY_ID=your-access-key-id
SECRET_KEY=your-secret-key
CHANNEL_ID=your-channel-id
API_BASE_URL=https://api.example.com/v1
```
8. 常见问题
8.1 签名验证失败的常见原因
- 时间戳超出允许范围（服务器时间与客户端时间差异过大）
- 使用了已过期或已使用过的nonce
- 参数排序不正确
- URL编码处理不正确
- 签名算法不匹配
- 密钥错误
- channelId与AccessKeyId不匹配