# 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不匹配