signx —— HMAC 接口签名(防篡改 + 限窗防重放)
Bearer token 只能证明"你是谁",证明不了"这次请求没被改"。 signx 把 method / path / 时间戳 / 请求体绑进一个 HMAC,写操作上校验, 篡改任何一项都失配。
功能
signx 提供四个纯函数,无状态、无配置、无依赖:
| 函数 | 作用 |
|---|---|
Sign |
算签名(客户端侧),返回小写 hex |
Verify |
验签(服务端侧),常量时间比较 |
ParseHeader |
拆 X-Signature 头 |
ValidTS |
校验时间戳是否落在时钟漂移窗口内 |
签名构造(逐字确定,两端必须一致)
拼接串 = METHOD + "\n" + PATH + "\n" + TS + "\n" + sha256(BODY)
sig = hex(HMAC-SHA256(secret, 拼接串))
METHOD大写,如POSTPATH含前导/,不含 query stringTS是 unix 秒的十进制字符串BODY取原始字节的 sha256
客户端 header:
X-Signature: t=<unix_seconds>,sig=<hex>
ParseHeader 认 t / ts / timestamp 和 sig / signature,逗号分隔,
两边空格会 trim;ts 或 sig 缺一个就返 false。
它不解决什么
- 不做 nonce、不记录已用过的签名 ⇒ 只挡"跨窗口重放",不挡窗口内重放
- 不管 secret 怎么存、怎么轮换(框架层没有 secret 的配置项)
- 不做鉴权(那是 auth):签名证明的是"请求没被改",不是"你是谁"
配置
yaml 侧
该包无 yaml 配置。
config.Server 结构体里没有 Sign 字段 —— secret 只能由调用方以 []byte
传进 middleware.Sign(secret)。框架层不提供 secret 的存放位置。
代码侧
| 入口 | 说明 |
|---|---|
middleware.Sign(secret []byte, opts ...func(*signxCfg)) |
HMAC 共享密钥;GET / HEAD / OPTIONS 直接透传,其余方法都要验签 |
middleware.WithSkew(n int64) |
允许的时钟漂移(秒),默认 300(5 分钟) |
middleware.WithClock(now func() int64) |
注入时钟(测试用) |
⚠️ middleware.Sign 的文档注释里写的 cfg.Sign.Secret 是个不存在的字段 ——
config.Server 里没有 Sign 块,照抄那行编译不过。
使用方法
客户端:算签名
secret := []byte("s3cr3t-shared-key")
ts := strconv.FormatInt(time.Now().Unix(), 10)
body := []byte(`{"phone":"13800001234","scene":"login"}`)
sig := signx.Sign(secret, "POST", "/rapid-admin/v1/auth/sms-code", ts, body)
header := "t=" + ts + ",sig=" + sig // → X-Signature
服务端:拆头 → 校验时间窗 → 验签
ts, sig, ok := signx.ParseHeader(raw)
if !ok {
// errcode.SignatureMissing (50600)
}
if !signx.ValidTS(ts, time.Now().Unix(), 300) {
// errcode.SignatureExpired (50601)
}
if !signx.Verify(secret, method, path, ts, body, sig) {
// errcode.SignatureInvalid (50602)
}
错误码落在 5xxxx 段(框架 / 运行时):
| 业务码 | 值 | HTTP |
|---|---|---|
errcode.SignatureMissing |
50600 | 500 |
errcode.SignatureExpired |
50601 | 500 |
errcode.SignatureInvalid |
50602 | 500 |
中间件(现成的,但还没接进链路)
h.Use(middleware.Sign(secret, middleware.WithSkew(300)))
中间件自己拆头、校验 ts、读 body、验签,失败就 response.Fail + c.Abort()。
读 body 用 c.Request.Body()(已缓冲的字节),读不到才 fallback 到 BodyStream
并一次性读掉,验签成功后用 c.Request.SetBody 写回,下游 handler 仍能读到。
完整可运行示例见 examples/signx/main.go。
注意事项
- ⚠️ 签名失败返的是 HTTP 500,不是 401/403。三个码(50600 / 50601 / 50602)都在
5xxxx段,errcode.HTTPStatus把50000-59999兜底成 500。 ⚠️internal/api/middleware/sign.go的注释写着"401/403",与实现不符 —— 前端按 HTTP 状态码分支的话,签名失败会被当成"服务器内部错误"。 - ⚠️ 签名不覆盖 query string。中间件取的是
path := string(c.Path()),不含?a=1。⇒ 如果业务把 query 参数当输入(页码、筛选条件),改 query 签名照样通过。 - ⚠️ "防重放"只有时间窗,没有 nonce。包名写着防重放,机制却只是"ts 距现在
不超过 5 分钟"。同一个签名在窗口内可以重放任意次,
signx不记录已用过的 ts。 ⇒ 真正的重复提交防护靠 idempotentx 或服务端 nonce 表。 - ⚠️
middleware.Sign目前零调用方。全仓grep "middleware.Sign("只命中它 自己文件里的注释;internal/api/router/router.go只挂了middleware.Idempotency()。 中间件是现成的,但没接进链路,而且没有 secret 的配置项 —— 接的时候得自己 解决 secret 从哪来、怎么轮换。 - ⚠️ hex 必须小写。
Sign返回小写 hex,而Verify是字符串全等比较 (不是解码后比字节)。客户端做大写转换 ⇒ 恒定返SignatureInvalid。 - ⚠️ body 必须是原始字节,只序列化一次。签名覆盖的是
sha256(body);JSON 的 key 顺序、空格、数字格式全在字节里。序列化两次、或"签名的字节"和"发出的字节" 不是同一份 ⇒ 必然失配。 - ⚠️
ValidTS接受未来时间戳。它取绝对值差,所以客户端时钟快 5 分钟以内 会通过而不是被拒。 - ⚠️ 中间件的挂载位置要在任何会消费 body 的中间件之后 —— 它读不到已缓冲的
body 时会 fallback 去读
BodyStream,那时 body 可能已经被上游读空了。 - ⚠️
ParseHeader对未知键静默跳过,对重复键后者覆盖前者。t=1,t=2取 2。 - ⚠️
Verify先比长度再做常量时间比较(len(want) != len(got)在subtle.ConstantTimeCompare之前)。sig 长度固定 64(hex sha256),实际不构成 泄露,但别照抄这个写法去比变长数据。 - ⚠️ 中间件只挡读方法 —— GET / HEAD / OPTIONS 直接透传不验签,其余方法 (POST / PUT / PATCH / DELETE 等)都要验签。
相关
- 源码:
internal/pkg/signx/ - 中间件:
internal/api/middleware/sign.go - 可运行示例:
examples/signx/main.go——go run ./examples/signx - 错误码分段与 HTTP 映射 → errcode
- 重复提交防护(签名管不了的那一半) → idempotentx
- JWT 签发 / 解析 / 吊销 → auth