181 lines
4.6 KiB
Markdown
181 lines
4.6 KiB
Markdown
# API签名工具 - C#实现
|
||
|
||
本目录包含API签名机制的C#语言实现，提供了签名计算与验证的完整功能。
|
||
|
||
## 功能特点
|
||
|
||
- 支持多种签名算法（MD5, SHA1, SHA256, HMAC-SHA256）
|
||
- 支持自定义签名参数名称
|
||
- 支持URL参数签名
|
||
- 内置防重放攻击机制（时间戳+nonce）
|
||
- 跨平台（.NET Standard 2.0 兼容）
|
||
- 提供命令行工具进行测试
|
||
- 无外部依赖，仅使用.NET标准库
|
||
|
||
## 项目结构
|
||
|
||
根据实际项目文件结构：
|
||
|
||
```plaintext
|
||
csharp/
|
||
├── src/
|
||
│ ├── ApiSigner/
|
||
│ │ ├── ApiSigner.cs # 签名工具实现
|
||
│ │ ├── ApiSigner.csproj # 项目文件
|
||
│ │ ├── SignatureAlgorithm.cs # 签名算法定义
|
||
│ │ ├── SignOptions.cs # 签名配置
|
||
│ │ └── SignVerifyResult.cs # 验证结果类型
|
||
│ │
|
||
│ ├── ApiSigner.Cli/
|
||
│ │ ├── ApiSigner.Cli.csproj # 命令行项目文件
|
||
│ │ └── Program.cs # 命令行入口
|
||
│ │
|
||
│ └── ApiSigner.sln # 解决方案文件
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 构建项目
|
||
|
||
```bash
|
||
dotnet build src/ApiSigner.sln
|
||
```
|
||
|
||
### 运行命令行工具
|
||
|
||
```bash
|
||
dotnet run --project src/ApiSigner.Cli/ApiSigner.Cli.csproj [选项]
|
||
```
|
||
|
||
### 命令行选项
|
||
|
||
| 选项 | 描述 |
|
||
|------|------|
|
||
| `-a, --algorithm` | 签名算法: MD5, SHA1, SHA256, HMAC-SHA256 |
|
||
| `-u, --url` | API基础URL |
|
||
| `-p, --param` | 请求参数，格式为key=value，可多次使用 |
|
||
| `-k, --key` | 访问密钥ID |
|
||
| `-s, --secret` | 密钥 |
|
||
| `-c, --channel` | 合作渠道方ID |
|
||
| `-h, --help` | 显示帮助信息 |
|
||
|
||
### 常用命令示例
|
||
|
||
**基本用法**
|
||
|
||
```bash
|
||
dotnet run --project src/ApiSigner.Cli/ApiSigner.Cli.csproj
|
||
```
|
||
|
||
**自定义参数**
|
||
|
||
```bash
|
||
dotnet run --project src/ApiSigner.Cli/ApiSigner.Cli.csproj \
|
||
-u "https://api.example.com/user/info" \
|
||
-p "userId=12345" -p "action=getInfo" \
|
||
-k "YOUR_ACCESS_KEY" \
|
||
-s "YOUR_SECRET_KEY" \
|
||
-c "3"
|
||
```
|
||
|
||
**指定签名算法**
|
||
|
||
```bash
|
||
dotnet run --project src/ApiSigner.Cli/ApiSigner.Cli.csproj -a SHA256
|
||
```
|
||
|
||
**帮助信息**
|
||
|
||
```bash
|
||
dotnet run --project src/ApiSigner.Cli/ApiSigner.Cli.csproj --help
|
||
```
|
||
|
||
### API接口测试实例
|
||
|
||
使用真实API接口进行测试：
|
||
|
||
```bash
|
||
# 未签名的API调用测试 - 返回错误
|
||
curl "https://api-v1.sound-force.com:8443/p/album/single/media-url?channelId=3&singleId=381980"
|
||
# 返回: {"code":400,"data":null,"msg":"Missing AccessKeyId","success":false}
|
||
|
||
# 生成访问https://api-v1.sound-force.com:8443/p/album/single/media-url的签名URL
|
||
dotnet run --project src/ApiSigner.Cli/ApiSigner.Cli.csproj \
|
||
-a MD5 \
|
||
-u "https://api-v1.sound-force.com:8443/p/album/single/media-url" \
|
||
-p "singleId=381980" \
|
||
-k "YOUR_ACCESS_KEY" \
|
||
-s "YOUR_SECRET_KEY" \
|
||
-c "3"
|
||
|
||
# 使用curl测试API接口
|
||
signedUrl=$(dotnet run --project src/ApiSigner.Cli/ApiSigner.Cli.csproj \
|
||
-a MD5 \
|
||
-u "https://api-v1.sound-force.com:8443/p/album/single/media-url" \
|
||
-p "singleId=381980" \
|
||
-k "YOUR_ACCESS_KEY" \
|
||
-s "YOUR_SECRET_KEY" \
|
||
-c "3" | grep -A 1 "签名后的URL:" | tail -n 1)
|
||
curl -v "$signedUrl"
|
||
```
|
||
|
||
请注意：
|
||
|
||
- 替换`YOUR_ACCESS_KEY`为实际的访问密钥ID
|
||
- 替换`YOUR_SECRET_KEY`为实际的密钥
|
||
- 示例使用的渠道ID为`3`，请根据实际情况调整
|
||
|
||
使用有效的密钥和签名后，API接口将返回成功响应(状态码200)并提供媒体URL数据。
|
||
|
||
### 代码集成
|
||
|
||
```csharp
|
||
using SoundForce.ApiSigner;
|
||
|
||
// 创建签名选项
|
||
var options = new SignOptions { Algorithm = SignatureAlgorithm.Md5 };
|
||
|
||
// 创建签名工具
|
||
var signer = new ApiSigner(options);
|
||
|
||
// 准备请求参数
|
||
var parameters = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
|
||
{
|
||
["singleId"] = "381980"
|
||
};
|
||
|
||
// 执行签名
|
||
var signedParams = signer.SignRequest(
|
||
parameters,
|
||
"YOUR_ACCESS_KEY",
|
||
"YOUR_SECRET_KEY",
|
||
"3"
|
||
);
|
||
|
||
// 或签名URL
|
||
var signedUrl = signer.SignUrl(
|
||
"https://api-v1.sound-force.com:8443/p/album/single/media-url",
|
||
parameters,
|
||
"YOUR_ACCESS_KEY",
|
||
"YOUR_SECRET_KEY",
|
||
"3"
|
||
);
|
||
```
|
||
|
||
### 环境变量
|
||
|
||
该工具支持从`.env`文件加载以下配置：
|
||
|
||
- `ACCESS_KEY_ID`: 访问密钥ID
|
||
- `SECRET_KEY`: 密钥
|
||
- `CHANNEL_ID`: 渠道ID
|
||
- `SIGN_ALGORITHM`: 签名算法
|
||
- `API_BASE_URL`: API基础URL
|
||
|
||
## 注意事项
|
||
|
||
1. 在生产环境中，应该妥善保管SecretKey，不要硬编码在代码中
|
||
2. 服务端需要自行实现nonce存储与验证以防止重放攻击
|
||
3. 时间戳验证需要考虑服务器与客户端之间可能存在的时间差
|
||
4. 默认情况下，命令行工具从`.env`文件或环境变量读取配置
|