99 lines
3.4 KiB
Markdown
99 lines
3.4 KiB
Markdown
# API签名机制
|
||
|
||
## 1. 概述
|
||
|
||
API签名机制是一种安全措施，用于验证API请求的合法性和完整性，同时防止请求被篡改或重放。本文档描述了我们的API签名机制的工作原理、实现方式以及集成指南。
|
||
|
||
## 2. 签名机制原理
|
||
|
||
### 2.1 基本流程
|
||
|
||
1. 客户端获取API密钥（AccessKeyId）和对应的密钥（SecretKey）
|
||
2. 客户端按照规则构造请求参数，包含必要的认证信息
|
||
3. 客户端使用SecretKey对请求参数进行签名计算
|
||
4. 客户端将签名和请求参数一起发送到服务器
|
||
5. 服务器验证签名，通过验证后处理请求
|
||
|
||
### 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. 签名计算方法
|
||
|
||
1. 收集所有请求参数（URL参数、表单参数），**不包括signature参数**
|
||
2. 按参数名称字典序升序排序
|
||
3. 构造规范化的请求字符串：`key1=value1&key2=value2&...`（URL编码非字母数字字符）
|
||
4. 在请求字符串末尾添加密钥：`key1=value1&key2=value2&...&key=YOUR_SECRET_KEY`
|
||
5. 使用指定算法计算签名：`signature = HASH_ALGORITHM(规范化请求字符串)`
|
||
6. 将签名以十六进制形式添加到请求参数
|
||
|
||
## 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不匹配
|