API文档

安全机制

1. 签名验证

算法: HMAC-SHA256
密钥长度: 支持 16-128 字符
签名长度: 固定 64 字符（十六进制）
安全特性: 防篡改、防抵赖

工作原理:

客户端使用 SecretKey 对请求参数进行 HMAC-SHA256 签名
服务器使用相同的 SecretKey 验证签名
签名不匹配则拒绝请求

签名生成过程:

import hmac
import hashlib

def generate_signature(method, path, params, secret_key):
    # 1. 按字母顺序排列参数（排除signature）
    sorted_params = "&".join(
        f"{'{'}k{'}'}={'{'}v{'}'}" for k, v in sorted(params.items())
        if k != 'signature'
    )

    # 2. 构造签名字符串
    sign_str = f"{'{'}method{'}'}{'{'}path{'}'}{'{'}params['timestamp']{'}'}{'{'}params['nonce']{'}'}{'{'}sorted_params{'}'}"

    # 3. HMAC-SHA256 签名
    signature = hmac.new(
        secret_key.encode(),
        sign_str.encode(),
        hashlib.sha256
    ).hexdigest()

    return signature

2. 时间戳验证

有效窗口: ±300 秒（5分钟）
时钟同步: 建议使用 NTP 同步
防重放: 超出时间窗口的请求被拒绝

时间戳要求:

使用 Unix 时间戳（秒级）
必须是10位数字
时间偏差不能超过 ±5 分钟

时间同步检查:

# 检查系统时间
date +%s

# 与NTP服务器同步
sudo ntpdate -u pool.ntp.org

3. Nonce 机制

唯一性: 每个请求必须使用不同的 Nonce
长度要求: 8-128 字符
缓存时间: 10 分钟
自动过期: 避免内存泄漏

Nonce 生成建议:

import uuid

# 推荐使用 UUID
nonce = str(uuid.uuid4())

# 或使用时间戳+随机数
import time
import random
nonce = f"{'{'}int(time.time()){'}'}{'{'}random.randint(10000, 99999){'}'}"

防重放攻击:

服务器缓存最近10分钟内使用过的 Nonce
相同 Nonce 的请求会被拒绝
超过10分钟的 Nonce 自动从缓存中移除

4. 频率限制

限制维度: AccessKey + clientIP 组合
独立计数: 每个 AccessKey 在每个 IP 上独立限流
灵活配置: 支持按需调整

频率限制规则:

每个 AccessKey 在每个 IP 上有独立的频率限制
超出限制返回 HTTP 429 错误
限流窗口为滑动窗口

应对频率限制:

import time
import random

def api_request_with_backoff(request_func, max_retries=3):
    """使用指数退避策略重试"""
    for attempt in range(max_retries):
        try:
            return request_func()
        except APIError as e:
            if e.code == 429:  # 频率限制
                if attempt == max_retries - 1:
                    raise
                # 指数退避: 2^n + 随机抖动
                delay = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
            else:
                raise

安全最佳实践

1. 密钥管理

✅ 正确做法:
- SecretKey 存储在环境变量或密钥管理服务中
- 定期轮换密钥
- 不同环境使用不同的密钥
❌ 错误做法:
- 将 SecretKey 硬编码在代码中
- 将 SecretKey 提交到版本控制系统
- 在日志中打印 SecretKey

2. 请求安全

✅ 正确做法:
- 使用 HTTPS 协议
- 每次请求生成新的 Nonce
- 使用当前时间戳
❌ 错误做法:
- 使用 HTTP 明文传输
- 重复使用相同的 Nonce
- 使用固定的时间戳

3. 错误处理

✅ 正确做法:
- 记录详细的错误日志（不包含敏感信息）
- 实现指数退避重试机制
- 监控异常请求频率
❌ 错误做法:
- 在错误消息中暴露系统内部信息
- 无限重试失败的请求
- 忽略认证错误

4. 监控告警

建议监控指标:
- 签名验证失败率
- 频率限制触发次数
- 异常时间戳请求
- Nonce 重复使用次数
告警阈值:
- 签名失败率 > 5%
- 频率限制触发 > 10次/分钟
- 异常请求 > 100次/小时