密钥轮换与重放攻击防御:时间戳签名与密钥版本管理

文章导读
API 接口被重放,常常比密钥泄露还难排查。密钥泄露之后你会收到告警,但重放攻击是利用一段已经合法的签名请求,在不知道密钥的情况下反复提交。比如订单回调、状态确认这类接口,如果只验签名不检查请求新鲜度,攻击者把请求原样再发一遍,服务端照样执行。所以需要把时间戳、nonce 和密钥版本一起纳入签名,服务端按顺序校验,才能把重放请求挡在外面。
📋 目录
  1. Ⅰ 重放要防,先确认请求里能查到密钥版本
  2. Ⅱ 时间戳签名请求的构造方式
  3. Ⅲ 服务端验签顺序:从时间窗口到 nonce
  4. Ⅳ 密钥轮换的操作节奏
  5. Ⅴ 日志里要看什么,以及回滚边界
A A

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 和访问控制。即使请求可以被构造,没有密钥也过不了验签。