API 接口被重放,常常比密钥泄露还难排查。密钥泄露之后你会收到告警,但重放攻击是利用一段已经合法的签名请求,在不知道密钥的情况下反复提交。比如订单回调、状态确认这类接口,如果只验签名不检查请求新鲜度,攻击者把请求原样再发一遍,服务端照样执行。所以需要把时间戳、nonce 和密钥版本一起纳入签名,服务端按顺序校验,才能把重放请求挡在外面。
重放要防,先确认请求里能查到密钥版本
签名密钥不会只用一个不换,所以请求里必须带 key_id 和 version。key_id 用来定位是哪一套业务密钥,version 用来定位是第几代密钥。服务端拿到这两个字段后,去配置或数据库里找对应的 secret,然后才能重新计算签名。不要把这些信息藏在 Header 之外的一个隐式字段里,客户端发请求时一定要显式传递,方便日志审计和轮换。
CREATE TABLE api_key_version (
key_id VARCHAR(64) NOT NULL,
version INT NOT NULL,
secret_encrypted TEXT NOT NULL,
status TINYINT NOT NULL DEFAULT 1 COMMENT '1 active, 0 retired',
effective_at DATETIME NOT NULL,
retire_at DATETIME NULL,
created_at DATETIME NOT NULL,
PRIMARY KEY (key_id, version)
);secret_encrypted 字段不要存明文,至少用 KMS 加密或本机密钥加密后再写入。status 和 retire_at 用来控制版本生命周期。验证时,如果该 key_id+version 的记录 status=0 或当前时间超过 retire_at,直接拒绝。轮换时先插入新版本,并把旧版本设为“将在某时间退役”,而不是马上删掉。
时间戳签名请求的构造方式
客户端的签名必须覆盖请求中的关键参数,同时加上 timestamp 和 nonce。timestamp 用于判断请求新鲜度,nonce 用于标记一个签名请求已经用过。加 nonce 的原因是防止在时间窗口内被重放。例如 300 秒内,同一个请求如果只有 timestamp 校验,攻击者可以在这 300 秒内重复提交;nonce 能保证同一个签名请求只能成功一次。
下面是一个最小可用的签名示例,适合表单提交或者查询参数场景。
import hashlib
import hmac
import time
import uuid
def sign_request(method, path, params, secret, key_id, version, now=None):
now = now or int(time.time())
nonce = uuid.uuid4().hex
payload = {
'key_id': key_id,
'version': version,
'method': method.upper(),
'path': path,
'timestamp': now,
'nonce': nonce
}
payload.update({k: params[k] for k in sorted(params.keys()) if k not in payload})
canonical = '&'.join('{}={}'.format(k, payload[k]) for k in sorted(payload.keys()))
signature = hmac.new(secret.encode(), canonical.encode(), hashlib.sha256).hexdigest()
payload['signature'] = signature
return payload这段代码中,参数会先排序,再拼成 canonical string,最后用当前密钥的 secret 做 HMAC-SHA256。实际开发中,如果请求体是 JSON,不要用这种方式,而是对 Canonical JSON 字符串做摘要。另外,params 里如果包含嵌套对象,需要先转成规整字符串,否则两边很难保持一致。
服务端验签顺序:从时间窗口到 nonce
服务端要按顺序判断,不能直接上来就查 nonce。我常用的顺序是:先检查时间戳是否在允许窗口内,再用 key_id+version 找到密钥,然后按相同规则重算签名,比对通过后再查 nonce。这个顺序可以避免攻击者用伪造签名抢先把 nonce 占掉,也能减少对 Redis 或数据库的无效查询。
下面是一个 Flask 风格的示例,Redis 用于保存 nonce:
import time
import hmac
import hashlib
def verify_request(request, get_secret, redis):
key_id = request.form.get('key_id')
version = request.form.get('version')
ts = int(request.form.get('timestamp', 0))
nonce = request.form.get('nonce')
signature = request.form.get('signature')
now = int(time.time())
if abs(now - ts) > 300:
return 'timestamp expired'
secret = get_secret(key_id, version)
if secret is None:
return 'unknown key version'
expected = hmac.new(secret.encode(), canonical_string(request.form), hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, signature):
return 'signature mismatch'
nonce_key = 'nonce:{}:{}:{}:{}'.format(key_id, version, ts, nonce)
if not redis.set(nonce_key, '1', nx=True, ex=600):
return 'nonce reused'
return None时间窗口设置在 ±300 秒意味着客户端和服务端的时钟差不能超过 5 分钟。如果你以前没有做过这类限制,建议先不要设为 30 秒,否则客户端时钟漂移会导致大量请求失败。可以先定为 600 秒,统计一段时间内的时间差分布,再逐步收紧。nonce 的过期时间要为 600 秒,因为最早允许的请求可能在 300 秒之后到达,最晚允许的请求可能在 300 秒之前,两个极端相差 600 秒,所以 nonce 至少保留 600 秒。
这里还有一点要注意:服务端如果部署了多实例,Redis 要用共享实例,不能放在单机内存。nonce 存储必须使用原子操作,set nx 比先 SELECT 再 INSERT 安全得多。
密钥轮换的操作节奏
轮换步骤并不复杂,难在平滑。如果只把服务端的 secret 改了,旧的请求签名会全部失效,影响正在排障的调用方。我通常这样处理:先创建一个新版本,但保留旧版本有效;然后让客户端分模块切换,每次只换一部分调用方;最后观察旧版本的请求日志,连续一段时间没有旧 key_id 出现,才把旧版本标记为 retired。
openssl rand -base64 32生成后要妥善保存,在写入数据库或配置文件时建议加密。不要在代码库中直接提交该值。另外,切换密钥时,建议同时更新客户端的 key_id 和 version,而不是只更新 secret。因为如果服务端通过 version 决定使用哪一段密钥,客户端 version 不变,就无法找到新密钥。
验证方式:在服务端日志里持续观察新版本的请求是否增加、旧版本的请求是否归零。如果出现签名错误,优先检查客户端和服务端配置中的 version 是否一致,以及密钥是否包含多余的换行符。
日志里要看什么,以及回滚边界
验签失败要记录详细原因,但不能记录完整签名和密钥。日志至少要有时间差、key_id、version、nonce 前几位、失败原因。这样当调用方报告验签失败时,你可以先看时间差,如果秒级偏高,优先处理 NTP。如果 key_id 未知,说明客户端配置错误。
回滚边界要注意:如果上线新版本后问题较多,只要旧版本密钥尚未删除,还可以让客户端切换回旧 key_id 和旧 version。但是,已经用过的 nonce 不会因此失效,因为 nonce_key 中包含了 key_id 和 version,切换回旧版本后,旧版 nonce 仍然有效,不影响。所以新旧版本可以共存,这是回滚的前提。
最后想强调,时间戳签名防重放只是防御层的一部分,不能替代 HTTPS 和访问控制。即使请求可以被构造,没有密钥也过不了验签。