接口对接安全实践：签名、时间戳与防重放检查

第三方系统对接里，安全问题大多不发生在算法层面，而是藏在签名比对、时间戳校验、重放防护这些看似琐碎的环节里。这篇文章整理一次多系统对接中的安全实践，覆盖签名生成与验证、时间戳窗口控制、防重放设计三个部分，全部来自真实项目，能给做开放接口或对接第三方服务的同行一份落地参考。

一、为什么简单鉴权不够用

1.0 问题的起点

这次对接的背景是一次内部系统集成：三个业务系统要互相开放查询和写入接口，服务方还包括外部供应商的系统，鉴权从一开始就不能马虎。起初想用固定密钥方案两天上线，后来评审被打回，才有了这篇文章里的完整改造。回头看，被打回是幸运的——如果带着固定密钥方案上线，首轮安全扫描就会把全部问题暴露在真实风险面前，返工成本比评审阶段高一个量级。安全设计有一条反直觉定律：越早被打回越便宜，上线之前的每一次打回都是在替未来的事故买单。

1.1 固定密钥的三个漏洞

对接初期用的是最简单的方案：请求头里带一个固定密钥，服务端比对通过就放行。上线评审时被架构组打回，理由有三条。一是密钥随每个请求明文传输，抓包即可拿到，等于没设防；二是无法验证请求内容完整性，参数在途中被改过服务端也不知道；三是同一请求原样重发会被再次接受，攻击者拿到一条合法请求就能无限重放，查询类接口被刷、写入类接口产生脏数据。三条叠加，固定密钥方案在任何有一点价值的接口上都不该用。评审会上还有一句让人印象深刻的反问：如果这个接口的密钥明天就出现在某个代码仓库的公开提交里，你的系统还剩下什么防线？正是这句话促成了后面整套改造的立项。

1.2 升级后的整体方案

改造后的方案三件套：HMAC 签名保证内容完整和身份可信，时间戳窗口限制请求时效，nonce 一次性随机值杜绝重放。三个机制各管一段，缺一不可：没有签名，时间戳和 nonce 都可被伪造；没有时间戳窗口，服务端要为海量 nonce 记录买单；没有 nonce，窗口内的请求仍可原样重发。理解了三者的互补关系，实现时才不会想着省掉哪一个。

二、签名生成与验证

2.1 规范化串的构造

签名的输入是请求的规范化串：HTTP 方法、路径、查询参数排序拼接、请求体摘要、时间戳、nonce 依次用换行符连接。规范化是签名体系里最容易出错的环节——参数名排序规则、空值处理、数组参数展开方式，两端只要有一处不一致，签名就对不上。建议把规范化逻辑写死成一份共享文档加一段参考代码，双方各自实现后先跑通签名联调用例，再进入业务联调。

const crypto = require("crypto");

function canonicalString(method, path, query, body, ts, nonce) {
  const qs = Object.keys(query).sort()
    .map(k => `${k}=${query[k]}`).join("&");
  const bodyHash = crypto.createHash("sha256")
    .update(body || "").digest("hex");
  return [method.toUpperCase(), path, qs, bodyHash, ts, nonce].join("\n");
}

function sign(secret, canonical) {
  return crypto.createHmac("sha256", secret).update(canonical).digest("hex");
}

2.2 服务端验证的顺序

验证顺序有讲究：先查时间戳窗口，再查 nonce 是否已用，最后验签。把最便宜的时间戳检查放最前面，超龄请求直接拒绝，不用查存储也不用作签名运算；nonce 检查居中；签名比对放最后。曾见过把验签放最前的实现，重放流量把 CPU 打满——攻击成本最低的废请求反而消耗了最贵的计算。安全设计里处处是这类成本不对称，顺序排对了，防御面和资源开销才合理。我们后来的补充实践是把三层拒绝原因分别计数上报，监控大盘上能直接看到每层的拦截量走势，一旦某层拦截量突增，可以快速判断是时钟漂移、重放尝试还是密钥泄露，定位时间从小时级压到分钟级。

三、时间戳与防重放

3.0 防重放的整体思路

先想清楚防重放的边界再动手。能防的是同一条合法请求被原样重发，防不了攻击者拿着合法凭证发起新请求——后者属于权限和限流管辖的范畴，不能指望 nonce 担起重责。边界想清楚之后，实现方案就纯粹了：时间窗口拦住过旧请求，nonce 拦住窗口内的重发，两个机制的存储成本和计算成本都极低，适合任何规模的接口。把这套思路落到具体实现，就是下面两节的内容。

3.1 时间戳窗口的取舍

时间戳窗口设多大是个平衡问题。窗口太小，客户端服务器时钟稍有偏差就全部拒签，对接方体验极差；窗口太大，nonce 存储周期跟着变长，内存或缓存压力上升。我们的最终取值是正负五分钟，配合两点措施：联调阶段开放一个时间偏移查询接口，对接方先自查时钟差；窗口判断放宽到绝对值，而不是单向的未来时间校验。上线一年，时钟问题引发的误拒个位数，重放攻击零成功。

3.2 nonce 的存储设计

nonce 的存储周期只需要覆盖时间戳窗口，过期即可清理。实现上用带过期时间的缓存键：nonce 写入缓存并设置五分钟过期，写入时若发现键已存在即为重放，直接拒绝。这个方案把清理逻辑交给了缓存的过期机制，不用自己维护删除任务。键的构造建议带上对接方标识，避免不同系统的 nonce 空间互相干扰。选型时还对比过数据库唯一索引方案，写入简单但清理要单独处理，高并发下索引压力大，最终放弃了；缓存方案在一个几百 QPS 的量级上运行一年，内存占用和命中率都符合预期，没有再动过。

import secrets, time

def check_and_mark_nonce(redis_cli, app_id, nonce, window=300):
    key = f"nonce:{app_id}:{nonce}"
    # SET NX + EX: 不存在则写入并返回成功，已存在返回失败
    ok = redis_cli.set(key, 1, nx=True, ex=window)
    return bool(ok)

def handle_request(redis_cli, app_id, req):
    now = int(time.time())
    if abs(now - req.ts) > 300:
        return reject("timestamp out of window")
    if not check_and_mark_nonce(redis_cli, app_id, req.nonce):
        return reject("replayed request")
    if not verify_signature(req):
        return reject("bad signature")
    return dispatch(req)

def gen_nonce():
    return secrets.token_hex(16)

四、密钥管理与落地经验

4.0 先算一笔安全账

推这套方案前，先和业务方算过一笔账：被刷接口的带宽成本、脏数据的人工清洗成本、以及一次真实泄漏带来的信任损失，加起来远高于开发投入的两周人力。这笔账算完，预算和排期都顺利了很多——安全建设最难的不是技术，是让决策者理解风险的具体形状。后来我们的做法是把这笔账年化更新一次，作为安全投入的基准依据，比抽象地讲"加强安全"有效得多。

4.1 密钥轮换与多密钥并行

密钥不该是一锤子买卖。方案里给每个对接方分配密钥版本号，新旧密钥并行一周，验证时先试新密钥再试旧密钥，轮换期内两边都能通过，一周后旧密钥下线。轮换动作每季度一次，全部走自动化流程，对接方无感知。这套机制的最大价值是兜底——密钥一旦疑似泄漏，五分钟内就能完成强制轮换，不用临时改代码发版。轮换自动化上线前还专门做过演练：挑一个低峰时段强制轮换全部密钥，观察各对接方的失败率曲线，确认自动重取密钥的机制都正常，才敢把这个机制当成真正的兜底手段。

4.2 审计日志的最低要求

所有被拒绝的请求都要留审计日志：拒绝原因（超窗、重放、验签失败）、原始参数摘要、来源地址。这些日志平时没人看，出事时就是全部的线索。我们靠它定位过一次对接方时钟漂移导致的批量拒签，也从里面发现过扫描器对我们接口的低频探测。日志保留九十天，按月归档，成本不高，价值关键时刻才显现。

审计之外，这份日志还支撑了一项季度安全复盘：统计各拒绝原因的占比变化，把趋势同步给对接方，附在季度服务报告里，推动他们主动修复时钟漂移这类自身问题，两个季度后超窗拒绝量下降了大半。搭贝开放接口的鉴权体系也是同样的思路，我们对照其文档校准了自己的实现细节，双向都受益。

4.3 一条容易被忽视的红线

安全机制再完善，密钥进了代码仓库就全盘皆输。我们强制密钥只经配置中心下发，应用启动时拉取，日志和异常堆栈里对密钥字段统一脱敏，代码仓库里部署了密钥扫描，提交内容命中密钥特征直接阻断。这条红线的执行比任何加密算法都重要——算法层面的漏洞有安全团队盯着，密钥泄漏这种低级错误只能靠流程自律。另一个容易松懈的环节是对接方退出：合作结束后密钥要主动作废，而不是放着不管，我们每季度都会核对一次活跃对接方清单，半年无调用的密钥一律停用，减少暴露面。整个方案落地后的两年里，接口对接从三家扩大到十几家，安全基线没有再动过，说明这套签名加时间戳加 nonce 的组合，对中小规模的开放平台来说已经够用且不冗余。