安全 on 姚玉亮的网络日志

API Key 加密存储与演示模式内存 Mock 的设计

Sat, 02 May 2026 10:30:00 +0800

后门钥匙不能明文放在库里

alchemy-furnace 要接 DeepSeek、通义、智谱、Kimi 这些供应商，用户得在控制台填自己的 API Key。这种 Key 一旦明文存进 MySQL，等于把后门钥匙交给了任何能读到库的人：备份泄露、运维误操作、SQL 注入，任何一环出事都可能变成真实资金损失。在统一支付平台做支付的时候，我对"敏感数据绝不能明文落库"有切身体会，签名密钥、商户私钥那一套都要加密。

另一个现实问题是开源项目的演示体验。我想放一个在线 DEMO，访客不用配任何 Key 就能点几下体验炼丹流程。但 DEMO 绝不能真的扣我的 API 额度，更不能让访客通过 DEMO 触发任意 LLM 调用。于是有了 DEMO_MODE：开启后所有 LLM 调用走内存 Mock，不碰任何真实供应商。这篇讲这两块的设计。

AES-256-GCM，主密钥版本化

对称加密用 AES-256-GCM：它自带认证标签，密文被动过就解不开，能防篡改。主密钥不放数据库，通过环境变量 FURNACE_MASTER_KEY 注入，K8s 里用 Secret 管理。每条 Provider 配置存的是：

key_ciphertext：AES-GCM 加密后的 API Key（base64）
key_nonce：每次加密随机生成的 nonce
key_version：主密钥版本，支持轮转
不存明文，不存主密钥

为了支持主密钥轮转，我维护一个 key_version -> master_key 的映射（环境变量 FURNACE_MASTER_KEY_V1、_V2），加密时用最新版本，解密时按记录里的版本取对应密钥。轮转时跑一个后台任务把旧密文用新密钥重加密，不需要停机。

Go 侧的加密服务：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58


type CryptoService struct {
 keys map[int][]byte // version -> key
 latestVer int
}

func NewCryptoService(m map[int][]byte) *CryptoService {
 return &CryptoService{keys: m, latestVer: findLatest(m)}
}

func (c *CryptoService) Encrypt(plaintext string) (
 ciphertext string, nonce string, ver int, err error,
) {
 ver = c.latestVer
 key := c.keys[ver]
 block, err := aes.NewCipher(key)
 if err != nil {
 return "", "", 0, err
 }
 gcm, err := cipher.NewGCM(block)
 if err != nil {
 return "", "", 0, err
 }
 n := make([]byte, gcm.NonceSize())
 if _, err := rand.Read(n); err != nil {
 return "", "", 0, err
 }
 ct := gcm.Seal(nil, n, []byte(plaintext), nil)
 return base64.StdEncoding.EncodeToString(ct),
 base64.StdEncoding.EncodeToString(n), ver, nil
}

func (c *CryptoService) Decrypt(ctB64, nonceB64 string, ver int) (string, error) {
 key, ok := c.keys[ver]
 if !ok {
 return "", fmt.Errorf("unknown key version %d", ver)
 }
 ct, err := base64.StdEncoding.DecodeString(ctB64)
 if err != nil {
 return "", err
 }
 nonce, err := base64.StdEncoding.DecodeString(nonceB64)
 if err != nil {
 return "", err
 }
 block, err := aes.NewCipher(key)
 if err != nil {
 return "", err
 }
 gcm, err := cipher.NewGCM(block)
 if err != nil {
 return "", err
 }
 pt, err := gcm.Open(nil, nonce, ct, nil)
 if err != nil {
 return "", fmt.Errorf("decrypt: %w (tampered?)", err)
 }
 return string(pt), nil
}

Provider 配置保存时加密，读取时解密（仅在内存中短暂存在）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


func (s *ProviderService) SaveKey(ctx context.Context,
 provider, apiKey string) error {
 ct, nonce, ver, err := s.crypto.Encrypt(apiKey)
 if err != nil {
 return err
 }
 return s.repo.UpdateKey(ctx, provider, ct, nonce, ver)
}

func (s *ProviderService) GetDecryptedKey(ctx context.Context,
 provider string) (string, error) {
 cfg, err := s.repo.GetKey(ctx, provider)
 if err != nil {
 return "", err
 }
 return s.crypto.Decrypt(cfg.Ciphertext, cfg.Nonce, cfg.KeyVersion)
}

DEMO_MODE：把 LLMClient 整个换掉

一个布尔配置，开启之后：

LLMClient 被替换成 MockLLMClient，不发任何 HTTP 请求，直接返回基于输入生成的假响应（带合理延迟，模拟流式）。
供应商 Key 校验接口直接返回"演示模式，未配置真实 Key"。
数据库用 SQLite 内存库或独立的 demo 库，数据不与生产混用。
演示模式下创建的金丹、分身带 demo=true 标记，避免被误当成真实数据。

Python 引擎侧的 Mock client：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


import asyncio, random, time

class MockLLMClient:
 async def complete(self, *, provider, model=None,
 system, user, temperature=0.7, tools=None):
 await asyncio.sleep(random.uniform(0.3, 0.9))
 if "identity" in system.lower() or "身份" in system:
 return "你是一位融合了多学科视角的思考者，擅长跨领域类比。"
 if "fuse" in system.lower() or "融合" in system:
 return (
 "# 身份\n你是一位融合型助手。\n\n"
 "# 原则\n- 先结构化拆解再回答\n- 用类比解释复杂概念\n"
 )
 return f"[DEMO] 收到你的问题（{len(user)} 字），这是模拟回答。"

 async def stream(self, *, provider, model=None,
 system, user, temperature=0.7):
 full = await self.complete(
 provider=provider, system=system,
 user=user, temperature=temperature)
 for ch in full:
 await asyncio.sleep(0.02)
 yield {"content": ch, "tool_calls": None, "done": False}
 yield {"content": "", "tool_calls": None, "done": True}

引擎启动时按环境变量选 client：

1
2
3
4


if settings.DEMO_MODE:
 llm_client = MockLLMClient()
else:
 llm_client = UnifiedLLMClient(key_provider=key_provider)

几处权衡

GCM 的 nonce 绝对不能复用：同一密钥下 nonce 重复会彻底破坏安全性。每次加密都用 crypto/rand 生成新 nonce 并随密文一起存，这是标准做法，别图省事儿用自增 ID 当 nonce。

主密钥放环境变量就够安全吗？对一个中小型开源项目，环境变量加 K8s Secret 是合理基线；更高安全等级应该上 KMS（云厂商的密钥管理服务），让应用永远拿不到原始主密钥，只调 KMS 的加解密接口。我在代码里预留了 KeyProvider 接口，本地用环境变量实现，生产可以替换成 KMS 实现，业务代码不用改。

解密后的 Key 会短暂待在内存里。Go 的 string 不可清空，理论上可能留在内存。我传完请求后不长期持有它，httpx 请求结束就释放引用。对极致安全场景可以用 []byte 并在使用后清零，但 Go 标准库的 HTTP header 也是 string，收益有限，属于权衡。

DEMO_MODE 不能只挡写不挡读。最早我只在配置保存处判 demo 模式，结果对话接口照样因为拿不到 key 而报错。正确做法是在 LLMClient 这一层整体替换，业务逻辑无感知地走 Mock。同理，DEMO_MODE 下的数据库迁移和定时任务也要跳过，避免演示环境连到生产资源。

Mock 要足够"像"才能测前端。如果 Mock 一秒返回大段文本，前端的流式打字效果、SSE 进度条、loading 状态根本测不到。所以 Mock 带随机延迟、逐 chunk 吐出，甚至对不同任务返回不同结构的假 prompt，让前端能完整走通融合进度、血统展示、对话沙箱。这对开源项目降低体验门槛很重要。

还有一条纪律：别把测试环境的 demo key 提交到仓库。我在 .env.example 里只留 DEMO_MODE=true 和占位符，CI 跑测试时用 demo 模式，不需要任何真实 Key。

后来

API Key 加密和 DEMO_MODE 看起来是两件事，本质上都是在"可控边界内运行不可信输入"：加密让数据库泄露不等于 Key 泄露，主密钥版本化让轮转可行；DEMO_MODE 让任何人都能安全体验产品而不碰真实额度，靠在适配层整体替换 LLMClient 做到业务无感知。

安全设计不追求绝对，而是把风险分层、把接口留好，让默认配置就足够安全，更高需求可以平滑升级到 KMS。这是我从统一支付平台签名到统一认证中心密钥管理一路积累的习惯。

封面图：archer10 (Dennis) / Flickr · CC BY-SA 2.0

基于 RSA 非对称签名签发 JWT 的多系统单点登录实践

Fri, 12 Apr 2024 10:30:00 +0800

HMAC 差在哪

我们在某科技公司做统一认证中心时，多个业务系统（统一支付平台、数据治理服务、知识库问答服务等）各自维护登录态，用户在系统间跳转要反复登录。最初考虑过用 HMAC 对称签名签发 JWT，但那样每个下游系统都得持有同一把密钥，一处泄露，整个认证体系就崩了，轮换密钥还得挨个通知所有业务方，运维成本很高。

最后选了 RSA 非对称签名：统一认证中心持私钥签发 JWT，各业务系统只持公钥验签，私钥永远不离开认证中心。

私钥签发，公钥验签

整体流程是：用户在统一认证中心登录后，认证中心用 RSA 私钥签发 Access Token 和 Refresh Token，写进 Cookie 或通过 Authorization 头返回。业务系统在网关层用公钥本地验签，不需要每次回调统一认证中心，认证中心的压力也小。

JWT 里放了 user_id、app_id、team_id、roles、exp、iss、aud 这些声明。iss 固定为 passport，aud 是目标应用的 AppID，防止 token 被跨应用滥用。Access Token 有效期 2 小时，Refresh Token 7 天，刷新时轮转新 Token。

代码里就两个函数

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


import (
 "crypto/rsa"
 "time"

 "github.com/golang-jwt/jwt/v5"
)

type Claims struct {
 UserID int64 `json:"user_id"`
 AppID string `json:"app_id"`
 TeamID int64 `json:"team_id"`
 Roles []string `json:"roles"`
 JTI string `json:"jti"`
 jwt.RegisteredClaims
}

func (s *Service) SignToken(c *Claims, ttl time.Duration) (string, error) {
 c.RegisteredClaims = jwt.RegisteredClaims{
 Issuer: "passport",
 Audience: jwt.ClaimStrings{c.AppID},
 ExpiresAt: jwt.NewNumericDate(time.Now().Add(ttl)),
 IssuedAt: jwt.NewNumericDate(time.Now()),
 ID: c.JTI,
 }
 tok := jwt.NewWithClaims(jwt.SigningMethodRS256, c)
 return tok.SignedString(s.privKey) // *rsa.PrivateKey
}

func ParseToken(pub *rsa.PublicKey, tokenStr string) (*Claims, error) {
 claims := &Claims{}
 tok, err := jwt.ParseWithClaims(tokenStr, claims, func(t *jwt.Token) (interface{}, error) {
 if _, ok := t.Method.(*jwt.SigningMethodRSA); !ok {
 return nil, fmt.Errorf("unexpected signing method: %v", t.Header["alg"])
 }
 return pub, nil
 })
 if err != nil || !tok.Valid {
 return nil, err
 }
 return claims, nil
}

验签逻辑放在各业务系统的 gRPC/HTTP 拦截器里，公钥通过配置中心下发。密钥轮转也支持：统一认证中心同时挂载新老两把私钥签发，公钥端点暴露 JWKS，业务系统定期拉取缓存。

alg=none 和另外两个坑

一是 alg=none 攻击。ParseWithClaims 的回调里必须校验 t.Method 是 RS256，不能信任 header 里的 alg。

二是 JWT 无法主动失效。我们用 Redis 维护黑名单，退出登录时把 jti 写进去，直到 token 自然过期才出黑名单。代价是每次请求多一次 Redis 查询，用 pipeline 加本地短缓存，压到可接受。

三是密钥轮转初期踩过坑：新私钥签发的 token，老业务系统还没拉到新公钥，验签直接失败。后来改成两把私钥灰度签发、JWKS 缓存 10 分钟、切换前先发公钥再切私钥，才算平稳。

后来

RSA 非对称签名让私钥收敛在认证中心，下游只持公钥，安全性和可扩展性都比 HMAC 好。配合短有效期 Access Token、Refresh Token 轮转和 Redis 黑名单，多业务系统的 SSO 就立住了。后续要接微信、企微、飞书登录，也只是多一种签发来源，验签侧一行不用改。

封面图：pixishared / Flickr · CC BY-SA 2.0

OAuth2/OIDC 认证中心实现：authorize/token/userinfo 与 JWKS

Wed, 27 Mar 2024 10:30:00 +0800

自定义协议走不通了

统一认证中心第一版只做了内部系统的 SSO，用的是自定义的 cookie + session 方案。后来要接入外部第三方应用，还要让企业客户拿自己的飞书/企微做身份源（IdP），自定义协议就走不通了。于是我决定把它改造成标准的 OAuth2/OIDC Provider：任何符合协议的客户端都能接入，认证中心自己也能作为 RP 去对接外部 IdP。

标准协议听起来就是实现几个端点的事，真落地才发现一堆工程细节等着：授权码模式的 PKCE、state/nonce 防 CSRF、redirect_uri 严格校验、ID Token 的签名与 claims、JWKS 公钥轮换。

四个端点

OIDC 在 OAuth2 之上加了身份层，核心要实现四个端点：

GET /oauth/authorize：用户登录与授权同意，返回 code；
POST /oauth/token：用 code 换 access_token / id_token / refresh_token；
GET /oauth/userinfo：用 access_token 取用户信息；
GET /.well-known/openid-configuration 和 /oauth/jwks：发现文档与公钥集合。

授权码模式（Authorization Code）+ PKCE 作为默认，所有 public client 强制 PKCE；client credentials 留给服务间调用。

/authorize：先校验，再谈登录

这个端点先做参数校验，再看登录态，没登录就跳登录页，state 带上保证回跳：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47


func (h *OAuthHandler) Authorize(c *gin.Context) {
 var req AuthorizeReq
 if err := c.ShouldBindQuery(&req); err != nil {
 c.String(400, "invalid request")
 return
 }
 app, err := h.appSvc.VerifyRedirectURI(c, req.ClientID, req.RedirectURI)
 if err != nil {
 c.String(400, "invalid redirect_uri")
 return
 }
 if req.ResponseType != "code" {
 c.Redirect(302, appendErr(req.RedirectURI, "unsupported_response_type", req.State))
 return
 }
 // PKCE: code_challenge 必填
 if req.CodeChallenge == "" || req.CodeChallengeMethod != "S256" {
 c.Redirect(302, appendErr(req.RedirectURI, "invalid_request", req.State))
 return
 }

 userID, loggedIn := session.GetUserID(c)
 if !loggedIn {
 c.Redirect(302, "/login?redirect="+url.QueryEscape(c.Request.RequestURI))
 return
 }

 code, err := h.authSvc.CreateAuthCode(c, AuthCode{
 AppID: app.AppID,
 UserID: userID,
 RedirectURI: req.RedirectURI,
 Scope: req.Scope,
 Nonce: req.Nonce,
 CodeChallenge: req.CodeChallenge,
 ExpiresAt: time.Now().Add(60 * time.Second),
 })
 if err != nil {
 c.String(500, "server error")
 return
 }
 u, _ := url.Parse(req.RedirectURI)
 q := u.Query()
 q.Set("code", code)
 q.Set("state", req.State)
 u.RawQuery = q.Encode()
 c.Redirect(302, u.String())
}

/token：验完 code 和 PKCE 才发 token

客户端拿到 code 之后来换 token，服务端要校验 code 和 PKCE verifier，都过了才签发：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


func (h *OAuthHandler) Token(c *gin.Context) {
 if err := c.Request.ParseForm(); err != nil {
 c.JSON(400, tokenErr("invalid_request"))
 return
 }
 grant := c.PostForm("grant_type")
 clientID, secret, ok := c.Request.BasicAuth()
 if !ok {
 c.JSON(401, tokenErr("invalid_client"))
 return
 }
 app, err := h.appSvc.Authenticate(c, clientID, secret)
 if err != nil {
 c.JSON(401, tokenErr("invalid_client"))
 return
 }

 switch grant {
 case "authorization_code":
 code := c.PostForm("code")
 verifier := c.PostForm("code_verifier")
 ac, err := h.authSvc.ConsumeAuthCode(c, code, app.AppID)
 if err != nil {
 c.JSON(400, tokenErr("invalid_grant"))
 return
 }
 if !pkce.Verify(ac.CodeChallenge, verifier) {
 c.JSON(400, tokenErr("invalid_grant"))
 return
 }
 pair, err := h.tokenSvc.Issue(OIDCTokenInput{
 UserID: ac.UserID,
 AppID: app.AppID,
 Nonce: ac.Nonce,
 Scope: ac.Scope,
 AuthTime: ac.CreatedAt,
 })
 if err != nil {
 c.JSON(500, tokenErr("server_error"))
 return
 }
 c.JSON(200, gin.H{
 "access_token": pair.AccessToken,
 "id_token": pair.IDToken,
 "refresh_token": pair.RefreshToken,
 "token_type": "Bearer",
 "expires_in": 7200,
 "scope": ac.Scope,
 })
 case "refresh_token":
 // 省略：验证 refresh token 并重新签发
 }
}

PKCE 校验本身没什么玄机，就是 SHA256 + Base64URL：

1
2
3
4
5


func Verify(challenge, verifier string) bool {
 sum := sha256.Sum256([]byte(verifier))
 computed := base64.RawURLEncoding.EncodeToString(sum[:])
 return subtle.ConstantTimeCompare([]byte(computed), []byte(challenge)) == 1
}

ID Token 与 JWKS

ID Token 是 OIDC 的核心，标准 claims 一个不能少：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


func (s *Service) buildIDToken(input OIDCTokenInput, user *User) (string, error) {
 now := time.Now()
 claims := IDTokenClaims{
 Issuer: s.issuer,
 Subject: strconv.FormatInt(user.ID, 10),
 Audience: jwt.ClaimStrings{input.AppID},
 ExpiresAt: jwt.NewNumericDate(now.Add(2 * time.Hour)),
 IssuedAt: jwt.NewNumericDate(now),
 AuthTime: jwt.NewNumericDate(input.AuthTime),
 Nonce: input.Nonce,
 Name: user.Nickname,
 Picture: user.Avatar,
 Email: user.Email,
 Phone: user.Phone,
 }
 return jwt.NewWithClaims(jwt.SigningMethodRS256, claims).SignedString(s.privKey)
}

JWKS 端点暴露公钥，支持轮换：

1
2
3
4


func (h *OAuthHandler) JWKS(c *gin.Context) {
 set := h.keySvc.PublicKeySet() // 返回当前 + 上一把公钥
 c.JSON(200, gin.H{"keys": set})
}

公钥的 JSON 表示要用 jwk 格式（kty/n/e/x5c 等字段）。我用 lestrrat-go/jwx/jwk 来做序列化，不手写：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


import "github.com/lestrrat-go/jwx/jwk"

func (s *KeyService) PublicKeySet() jwk.Set {
 set := jwk.NewSet()
 for _, k := range s.activeKeys() {
 key, _ := jwk.New(k.PublicKey)
 key.Set(jwk.KeyIDKey, k.Kid)
 key.Set(jwk.AlgorithmKey, "RS256")
 key.Set(jwk.KeyUsageKey, "sig")
 set.AddKey(key)
 }
 return set
}

那些必须较真的细节

redirect_uri 必须精确匹配。早期为了图方便支持了前缀匹配，被安全团队指出有开放重定向风险，后来改成配置里的完整 URL 白名单，查询参数不参与匹配。

ID Token 的 nonce 一定要原样回传。客户端靠它防重放，如果我们漏传，严格的 OIDC 客户端会直接拒绝登录。

code 一次性使用，加短过期。我设成 60 秒过期、用后即删，而且同一个 code 被二次使用时，立即吊销该 app 下该用户的所有活跃 token，这也是 OAuth2 安全 BCP 的推荐做法。

公钥轮换要平滑。JWT header 里带 kid，资源服务器按 kid 从 JWKS 缓存公钥；换密钥时，新私钥签发的 token 带新 kid，旧公钥在 JWKS 里保留 7 天，让存量 token 自然过期。

/userinfo 默认只返回 sub，其他 claims 要看 access token 的 scope 里有没有 profile/email/phone。不能一股脑把用户信息全吐出去。

还有一条经验：别自己造 JWT 轮子。我签发用 golang-jwt/jwt/v5，JWK 处理用 lestrrat-go/jwx，两个都是社区主流，省得自己手写 base64 和 JSON 序列化时漏掉边界条件。

后来

实现标准 OAuth2/OIDC，工作量大头在把协议里那些 MUST/SHOULD 逐条落到工程里：PKCE、state/nonce、精确 redirect_uri、code 一次性、JWKS 轮换。改造完成后，任何标准 OIDC 客户端（NextAuth、Spring Security、Keycloak adapter）都能直接接入，飞书/企微作为外部 IdP 也能走同一个 OIDC 联邦框架，扩展性比自定义协议好得多：对接这件事，不再需要一对一谈判。

封面图：Strooks-traveller1 / Flickr · CC BY-SA 2.0

基于 RSA/SHA 签名的 OpenAPI 安全机制实现

Tue, 09 Jan 2024 10:30:00 +0800

为什么是 RSA，不是 HMAC

商户的服务器要调我们的下单、查询、退款接口，安全是第一道门槛。没法靠 Session，也不能让 AppSecret 在网络上裸奔。我参考了微信支付、支付宝那一套签名机制，最后定下 RSA 非对称签名加 SHA256 摘要，再用时间戳和随机串防重放。

为什么不全用 HMAC？因为 HMAC 是对称的，平台手里也捏着商户的密钥，一旦平台侧泄露，商户没法自证清白。换成 RSA 就没有这个问题：商户的私钥自己保管，平台只存公钥，谁发的、有没有被改，验签时责任边界清清楚楚。

签名串怎么拼

签名串的构造规则我们定得很死：

按 ASCII 升序排列所有非空业务参数（不含 sign、sign_type、sign_version）；
拼接成 key1=value1&key2=value2；
末尾追加上行请求体的 SHA256 摘要（JSON 原文，不做字段排序）；
商户私钥做 SHA256WithRSA 签名，Base64 编码后放在 X-Sign Header；
同时带 X-App-Id、X-Timestamp（秒）、X-Nonce。

定这么死是故意的。签名串最怕商户各自发挥：参数排序差一点、大小写差一点，验签就永远过不去，还查不出是哪边的问题。

构造逻辑我直接写成一个纯函数，平台和 SDK 共用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


func BuildSignString(query url.Values, body []byte) string {
 keys := make([]string, 0, len(query))
 for k := range query {
 if k == "sign" || k == "sign_type" {
 continue
 }
 if v := query.Get(k); v != "" {
 keys = append(keys, k)
 }
 }
 sort.Strings(keys)

 var buf strings.Builder
 for i, k := range keys {
 if i > 0 {
 buf.WriteByte('&')
 }
 buf.WriteString(k)
 buf.WriteByte('=')
 buf.WriteString(query.Get(k))
 }
 sum := sha256.Sum256(body)
 buf.WriteString("&body_sha256=")
 buf.WriteString(hex.EncodeToString(sum[:]))
 return buf.String()
}

验签四道关

平台校验四件事：AppId 是否存在、时间戳是否在 5 分钟窗口内、Nonce 是否在 Redis 里没出现过（防重放）、签名是否通过。

验签挂在 Gin 的 OpenAPI 路由组上，是个中间件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


func RSAVerifyMiddleware(appDao dao.AppDAO, rdb *redis.Client) gin.HandlerFunc {
 return func(c *gin.Context) {
 appID := c.GetHeader("X-App-Id")
 timestamp := c.GetHeader("X-Timestamp")
 nonce := c.GetHeader("X-Nonce")
 sign := c.GetHeader("X-Sign")

 if appID == "" || timestamp == "" || nonce == "" || sign == "" {
 c.AbortWithStatusJSON(401, gin.H{"code": "MISSING_AUTH_HEADERS"})
 return
 }
 ts, err := strconv.ParseInt(timestamp, 10, 64)
 if err != nil || math.Abs(float64(time.Now().Unix()-ts)) > 300 {
 c.AbortWithStatusJSON(401, gin.H{"code": "TIMESTAMP_EXPIRED"})
 return
 }
 nonceKey := "openapi:nonce:" + appID + ":" + nonce
 if ok, _ := rdb.SetNX(c, nonceKey, 1, 10*time.Minute).Result(); !ok {
 c.AbortWithStatusJSON(401, gin.H{"code": "REPLAY_DETECTED"})
 return
 }

 app, err := appDao.FindByAppID(c, appID)
 if err != nil || app.Status != "ACTIVE" {
 c.AbortWithStatusJSON(401, gin.H{"code": "APP_NOT_FOUND"})
 return
 }
 body, _ := c.GetRawData()
 c.Request.Body = io.NopCloser(bytes.NewBuffer(body)) // 回放给后续 handler
 signStr := BuildSignString(c.Request.URL.Query(), body)

 pub, err := parseRSAPublicKey(app.PublicKey)
 if err != nil {
 c.AbortWithStatusJSON(401, gin.H{"code": "INVALID_PUBKEY"})
 return
 }
 hashed := sha256.Sum256([]byte(signStr))
 sig, _ := base64.StdEncoding.DecodeString(sign)
 if err := rsa.VerifyPKCS1v15(pub, crypto.SHA256, hashed[:], sig); err != nil {
 c.AbortWithStatusJSON(401, gin.H{"code": "SIGN_INVALID"})
 return
 }
 c.Set("app", app)
 c.Next()
 }
}

GetRawData 之后记得用 io.NopCloser 把 body 放回去，否则后续 ShouldBindJSON 会读到空。这是我第一次联调踩的坑。

四个权衡

第一是 GET 请求的 body 处理。GET 没有 body，我们约定 body_sha256 字段直接填空字符串的 SHA256（即 e3b0c442...），而不是省略这个字段。签名串结构稳定，SDK 不用写两套分支。

第二是 Nonce 的存储成本。Redis 存 10 分钟窗口的 Nonce，看着有压力，实际上按 AppId 隔离之后单商户 QPS 并不高，10 分钟过期自动回收，没必要上滑动窗口或布隆过滤器。

第三是密钥轮换。App 表里留了 public_key 和 public_key_prev 两个字段，轮换时新公钥进主字段、旧公钥降到 prev，中间件两把都试。商户有 24 小时灰度窗口，不会一刀切验签失败。

第四是要不要加密 body。平台已经全链路 HTTPS，签名本身防篡改，最后没做请求体加密，只有银行卡号这类敏感字段由业务层单独做字段级加密。给所有商户平添一层对接成本，不值。

上线之后

上线至今，没出过签名层面的安全事件。回头看，这套机制立得住，靠的是规则够死、边界够清：谁发的、有没有被改、是不是重放，一趟验签全解决。商户接入文档里我配了 Java、Python、Go 三份 SDK 示例，写文档花的功夫，比后来省下的联调时间少多了。

封面图：Simon A. Eugster / Wikimedia Commons · CC BY-SA 3.0