Python接口安全设计实践_签名校验与时间戳方案【指导】_技术教程

签名校验必须包含时间戳以防止重放攻击，服务端通过校验timestamp与当前时间差值（如>300秒则拒绝）确保请求时效性，要求客户端和服务端时钟误差在容忍范围内。

签名校验为什么必须包含时间戳

不加时间戳的签名只是防篡改，不是防重放。攻击者截获一次合法请求后，可以无限次重放，服务端无法识别这是旧请求还是新请求。

时间戳的作用是让签名具备“时效性”。服务端收到请求后，会比对 timestamp 与当前服务器时间的差值，超出阈值（如 300 秒）即拒绝。这要求客户端和服务端时钟尽量同步，但不必完全一致——只要误差控制在容忍范围内即可。

timestamp 必须是秒级或毫秒级整数，推荐用 int(time.time())（秒）或 int(time.time() * 1000)（毫秒）
服务端应使用系统本地时间（非 NTP 校准后的时间），避免引入额外依赖
客户端传 timestamp=1715823456，服务端收到后计算 abs(server_time - 1715823456) > 300，超时则直接返回 401

Python 中生成标准 HMAC-SHA256 签名的写法

签名原文必须固定顺序、不可省略字段、不能带空格或换行。常见错误是拼接时用了字典默认遍历顺序（Python 3.7+ 虽然有序，但不显式排序仍属隐患），或漏掉 timestamp 和 nonce。

推荐签名原文格式：method|path|timestamp|nonce|body_md5（其中 body_md5 是请求体的 MD5 小写十六进制值，空体为 md5("").hexdigest()）

import hmac
import hashlib
import json
def gen_signature(secret_key: str, method: str, path: str, timestamp: int, nonce: str, body: bytes) -> str:
body_md5 = hashlib.md5(body).hexdigest()
msg = f"{method}|{path}|{timestamp}|{nonce}|{body_md5}".encode()
key = secret_key.encode()
sig = hmac.new(key, msg, hashlib.sha256).digest()
return sig.hex()

secret_key 应从环境变量或配置中心加载，禁止硬编码
nonce 每次请求唯一，建议用 uuid.uuid4().hex 或 16 字节随机字符串
若接口支持 GET 无 body，body 传 b"" 即可，不要传 None

Flask/FastAPI 中验证签名与时间戳的典型陷阱

验证逻辑必须放在中间件或装饰器最前侧，且在解析 JSON 之前完成。否则攻击者可能通过畸形 JSON 触发解析异常，绕过校验。

另一个高频问题是：从 request.headers 取 X-Signature 时未做大小写归一化，而某些代理（如 Nginx）会把下划线转成中划线或小写。

始终用 request.headers.get("X-Signature", "").strip()，并统一转小写比对
时间戳校验必须在签名比对之前做——如果先算签名再比时间，攻击者仍可重放旧签名
FastAPI 中若用 Depends() 做鉴权，需确保该依赖不依赖 Body()，否则会提前触发解析
Flask 示例中，request.get_data(cache=True) 必须调用一次，否则后续 request.json 会为空

body_md5 计算容易被忽略的边界情况

很多人直接对 request.get_json() 结果做 json.dumps 再哈希，这是错的：原始 body 可能含空格、换行、Unicode 转义，而 json.dumps 默认参数会导致输出不一致。

正确做法是直接读原始字节流，并注意编码。POST/PUT 的 body 不一定是 UTF-8，但绝大多数 API 约定为 UTF-8；若不确定，应以 Content-Type 中的 charset 为准，无声明时默认 UTF-8。

用 request.get_data() 获取原始 bytes，不要用 .stream.read() 后再 decode 再 encode
GET 请求没有 body，但签名公式里仍要参与 body_md5 计算，此时必须是空字符串的 MD5："d41d8cd98f00b204e9800998ecf8427e"
若前端发送的是 application/x-www-form-urlencoded，body 是键值对字符串（如 a=1&b=2），也应原样哈希，不要解析后再拼