Go 接口签名怎么防重放：timestamp、nonce 和 HMAC 校验实战

线上支付回调、开放 API、内部管理接口很容易碰到一类问题：请求本身看起来完全合规，参数也没有被篡改，攻击者只要把抓到的完整请求包反复发几次，就可能导致接口重复扣库存、重复发放权益、重复触发后台任务。Go 里做接口签名校验，不能只把参数拼接完算个 HMAC 就完事，还要把 timestamp、nonce、密钥保管规则、权限边界判断和审计日志环节串到同一条校验链路上。

先看要保护的资产：不是签名算法，而是业务动作

很多人写接口签名只会封装一个工具函数：拿到 query 参数、请求体、密钥，算出一串摘要，再和请求头里带的签名做对比。这种写法确实能挡住一部分参数篡改的攻击，但没触及更核心的问题：这套签名机制到底在保护什么业务逻辑。

如果接口只是查询公开的内容列表，签名校验失败最多就是拒绝访问；如果接口可以创建订单、发放福利、修改核心配置，重放请求带来的风险级别完全不一样。做安全设计可以从业务动作往回推演：哪些接口绝对不能重复提交，哪些参数会直接影响金额或者权限等级，哪些请求就算签名完全正确也必须走二次校验流程。

攻击路径：历史请求为什么还能产生新影响

典型的重放攻击根本不需要修改任何参数。攻击者只要抓到一次完整的请求内容，包括路径、全部参数、时间戳、nonce 和合法签名，就可以在有效时间窗口内反复发送。如果服务端只校验 HMAC 合法性，不检查时间有效性也不判断 nonce 是否已经用过，就会把第二次提交的重复请求当成全新请求正常处理。

这里很容易产生认知偏差：签名校验通过只能证明“这份请求在生成的时候没有被篡改”，完全不等于“这份请求现在还允许被接收”。防重放逻辑要拆成三步执行：先判断时间戳是不是落在允许的窗口范围内，再用完全对齐的规则重新计算签名，最后把 nonce 写入短期缓存；如果 nonce 已经存在，直接拒绝后续请求。

Go 中间件的校验顺序别写反

服务端的校验逻辑顺序可以固定下来：基础字段合法性检查、时间窗口有效性判断、签名串重新计算、常量时间对比签名结果、nonce 原子去重判断、最后再流转到实际业务逻辑。调整好执行顺序不是为了形式好看，是为了减少不必要的无效计算，同时降低规则被绕过的概率。

package signcheck

import (
	"crypto/hmac"
	"crypto/sha256"
	"crypto/subtle"
	"encoding/hex"
	"net/http"
	"sort"
	"strconv"
	"strings"
	"time"
)

type NonceStore interface {
	SaveOnce(nonce string, ttl time.Duration) bool
}

func Middleware(secret []byte, store NonceStore, next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		tsText := r.Header.Get("X-Timestamp")
		nonce := r.Header.Get("X-Nonce")
		gotSign := r.Header.Get("X-Signature")
		if tsText == "" || nonce == "" || gotSign == "" {
			http.Error(w, "missing signature headers", http.StatusUnauthorized)
			return
		}

		ts, err := strconv.ParseInt(tsText, 10, 64)
		if err != nil {
			http.Error(w, "bad timestamp", http.StatusUnauthorized)
			return
		}
		now := time.Now().Unix()
		if ts  now+60 {
			http.Error(w, "timestamp expired", http.StatusUnauthorized)
			return
		}

		base := canonicalString(r, tsText, nonce)
		wantSign := sign(base, secret)
		if subtle.ConstantTimeCompare([]byte(gotSign), []byte(wantSign)) != 1 {
			http.Error(w, "bad signature", http.StatusUnauthorized)
			return
		}

		if !store.SaveOnce(nonce, 5*time.Minute) {
			http.Error(w, "replay request", http.StatusUnauthorized)
			return
		}

		next.ServeHTTP(w, r)
	})
}

func canonicalString(r *http.Request, tsText, nonce string) string {
	q := r.URL.Query()
	keys := make([]string, 0, len(q))
	for k := range q {
		if k == "signature" {
			continue
		}
		keys = append(keys, k)
	}
	sort.Strings(keys)

	var b strings.Builder
	b.WriteString(r.Method)
	b.WriteByte('\n')
	b.WriteString(r.URL.Path)
	b.WriteByte('\n')
	b.WriteString(tsText)
	b.WriteByte('\n')
	b.WriteString(nonce)
	for _, k := range keys {
		b.WriteByte('\n')
		b.WriteString(k)
		b.WriteByte('=')
		b.WriteString(q.Get(k))
	}
	return b.String()
}

func sign(base string, secret []byte) string {
	mac := hmac.New(sha256.New, secret)
	mac.Write([]byte(base))
	return hex.EncodeToString(mac.Sum(nil))
}

这里用了 subtle.ConstantTimeCompare，避免普通字符串直接对比带来的时间侧信道泄露风险。真实项目里还要把请求体摘要、租户ID、应用ID等字段纳入签名串，最核心的要求就是客户端和服务端必须用完全一致的拼接规则生成签名，不能有任何差异。

nonce 存储要支持原子去重

nonce 不是随便存个字符串做判断就行。它需要在短时间窗口内保证全局唯一，而且判断 nonce 有没有存在和写入新 nonce 的操作必须是原子操作。用内存 map 可以在单机演示场景跑通逻辑，但多实例部署的场景下，很容易漏掉其他节点收到的重复请求。生产环境更适合把 nonce 存入 Redis，用 SET key value NX EX 300 的方式一次完成占位和设置过期时间，不用额外两步操作。

nonce 的存储键最好带上调用方身份标识，比如 api_nonce:{appID}:{nonce}。这样不同应用就算生成了完全相同的随机串，也不会出现互相拦截的误判问题。nonce 的过期时间一般和 timestamp 的允许有效窗口对齐，时间窗口设得越长，存储压力就越大；窗口设得太短，客户端时钟稍有偏差就容易被误拦截。大部分业务可以先从5分钟的时间窗口开始跑，后续再根据实际网络情况调整。

签名通过之后，权限范围还要继续收窄

签名校验通过只能证明请求来自持有合法密钥的一方，不能直接判定它有权限访问系统里的所有接口。很多安全事故不是签名算法出了错，而是同一个 secret 被多个业务系统共用，最后低权限服务的密钥泄露之后，攻击者直接就能调用高权限的核心接口。

更稳妥的方案是给每个调用方分配独立的 appID 和 secret，服务端通过 appID 查表拿到对应的密钥，同时绑定好这个 appID 允许访问的接口范围、IP 白名单、调用频率上限和密钥过期时间。密钥还要支持平滑轮换：新旧密钥短时间内并行生效，确认所有客户端都切换完新密钥之后，再下线旧密钥。

审计日志要能完整还原拦截原因

签名校验失败直接返回 401 远远不够。排查问题的时候真正需要的信息包括：是哪个appID发的请求、访问的是什么路径、对应的nonce是什么、时间偏差有多大、是签名不匹配还是nonce重复、请求来源IP是什么。日志里不要记录完整的secret，也不要把完整的原始签名串直接打印出来，保留必要的字段和短哈希值就足够排查问题了。

• app_id：调用方身份，用来定位是哪把密钥参与了校验。
• path 与 method：确认本次请求影响的接口范围。
• nonce_hash：记录nonce的短哈希，方便排查重复请求又不会泄露原始值。
• time_skew：客户端请求携带的时间和服务端当前时间的差值。
• reject_reason：比如 bad_signature、expired、replay。
• remote_ip：用来定位异常请求来源和调整限流规则。

上线前的检查清单

签名方案正式上线之前，至少要做一轮反向校验测试。不要只测“合法请求能不能正常通过”，还要覆盖参数排序变化、空参数传入、过期时间戳、重复nonce、错误密钥、跨路径复用签名、不同appID用相同nonce这些异常场景。

• 客户端和服务端用完全相同的参数生成的签名结果100%匹配。
• 超过有效时间窗口的请求稳定返回 401。
• 同一个nonce第二次提交的时候会被直接拦截。
• 不同appID生成的相同nonce不会互相拦截。
• 签名失败的日志可以快速定位原因，同时不会泄露任何密钥信息。
• 密钥平滑轮换的流程已经过灰度验证可以正常跑通。

常见问题

接口签名可以完全替代 HTTPS 吗？

不能。HTTPS 负责传输层加密和链路身份校验，接口签名负责请求内容完整性和调用方身份核验，二者解决的是不同维度的问题，生产环境的对外接口一般会同时启用两种机制。

timestamp 和 nonce 只留一个可以吗？

不建议。只有timestamp的话，同一个时间窗口内的历史请求还是可以被反复重放；只有nonce的话，全量缓存的存储压力会非常大，也没办法自然实现过期淘汰。两个字段配合使用的鲁棒性好很多。

签名串里要不要把请求体也加进去？

对外接口最好加。通用做法是把整个请求体做SHA-256摘要，再把这个摘要值拼到签名串里，既可以防止请求内容被篡改，也不用把大体积的请求体直接拼进签名文本里，效率更高。

nonce 全部存在 Redis 里会不会变成性能瓶颈？

高QPS的接口要提前评估Redis的写入量级，但这类写入都是短TTL的单key原子操作，压力比复杂的多条件查询低很多。真正要重点考虑的是键的设计规则、过期时间配置，还有Redis故障场景下的降级处理方案。

小结

Go 接口签名的核心从来不是把 HMAC 函数调通就行，而是把“请求有没有被篡改、有没有过期、是不是重复提交、有没有对应权限、出了问题能不能追溯”这些环节串成一条完整的校验链路。把 timestamp、nonce、HMAC、权限收窄和审计日志都落地到代码和运维规则里，接口就不会被一份抓来的旧请求随便绕过。