基于HMAC-SHA256实现API请求签名验证，客户端按参数名排序拼接待签名字符串，结合HTTP方法、路径、时间戳、nonce等生成签名；服务端通过中间件校验accessKey、时间窗口、nonce唯一性，并重新计算签名比对，确保请求合法性与防重放攻击。
在使用 Golang 开发 API 接口时，为了保证请求的合法性和安全性，通常会引入请求签名验证机制。这种机制可以防止请求被篡改或重放攻击。下面介绍一种常见的实现方式：基于 HMAC-SHA256 算法的签名验证流程。
1. 签名的基本原理
客户端和服务器共享一个密钥（secretKey），每次请求时，客户端根据请求参数和时间戳生成签名，并将签名随请求发送。服务端收到请求后，使用相同的算法和密钥重新计算签名，并与客户端传来的签名比对。
核心要素包括：
- 请求参数：所有参与签名的参数需按规则排序
- 时间戳（timestamp）：防止重放攻击
- 随机字符串（nonce）：增加唯一性
- API密钥（accessKey 和 secretKey）：用于身份识别和签名计算
- HTTP方法、路径、Body（如需要）：确保请求完整性
2. 客户端生成签名
假设客户端要发送一个 POST 请求到 /api/v1/order，携带参数：
立即学习“go语言免费学习笔记（深入）”；
accessKey=abc123×tamp=1712345678&nonce=randomxyz&amount=100&product=phone
步骤如下：
- 将所有参数按字段名字母升序排序
- 拼接成 query string 格式（不编码 key 和 value，或统一 URL 编码）
- 构造待签名字符串，例如：
POST&/api/v1/order&accessKey=abc123&amount=100&nonce=randomxyz&product=phone×tamp=1712345678 - 使用 secretKey 对该字符串进行 HMAC-SHA256 计算，并转为十六进制小写字符串
- 将生成的 signature 添加到请求头或参数中发送
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"fmt"
"sort"
"strings"
)
func generateSignature(httpMethod, uri, secretKey string, params map[string]string) string {
var keys []string
for k := range params {
keys = append(keys, k)
}
sort.Strings(keys)
var pairs []string
for _, k := range keys {
pairs = append(pairs, fmt.Sprintf("%s=%s", k, params[k]))
}
queryString := strings.Join(pairs, "&")
signStr := fmt.Sprintf("%s&%s&%s", httpMethod, uri, queryString)
h := hmac.New(sha256.New, []byte(secretKey))
h.Write([]byte(signStr))
return hex.EncodeToString(h.Sum(nil))
}
func main() {
params := map[string]string{
"accessKey": "abc123",
"timestamp": "1712345678",
"nonce": "randomxyz",
"amount": "100",
"product": "phone",
}
sig := generateSignature("POST", "/api/v1/order", "my_secret_key_123", params)
fmt.Println("Signature:", sig)
}
3. 服务端验证签名
服务端接收到请求后，执行类似步骤：
- 从请求中提取 accessKey，查询对应 secretKey
- 校验 timestamp 是否在允许的时间窗口内（如 ±5 分钟）
- 检查 nonce 是否已使用过（可缓存一段时间，防重放）
- 用相同规则拼接参数并生成签名
- 使用 hmac.Equal 安全比较签名是否一致
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"net/http"
"sort"
"strings"
"time"
"github.com/gin-gonic/gin"
)
var secretKeyMap = map[string]string{
"abc123": "my_secret_key_123",
}
func SignVerifyMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
accessKey := c.PostForm("accessKey")
timestampStr := c.PostForm("timestamp")
nonce := c.PostForm("nonce")
clientSig := c.GetHeader("X-Signature")
if accessKey == "" || timestampStr == "" || nonce == "" || clientSig == "" {
c.JSON(401, gin.H{"error": "missing required fields"})
c.Abort()
return
}
secretKey, exists := secretKeyMap[accessKey]
if !exists {
c.JSON(401, gin.H{"error": "invalid accessKey"})
c.Abort()
return
}
// 验证时间戳
timestamp, err := time.ParseUnix(timestampStr, 10)
if err != nil || time.Since(timestamp).Abs() > 5*time.Minute {
c.JSON(401, gin.H{"error": "timestamp invalid"})
c.Abort()
return
}
// TODO: 使用 Redis 或内存缓存检查 nonce 是否重复
// 收集所有 form 参数（可根据实际需求扩展支持 query、JSON 等）
params := make(map[string]string)
c.Request.ParseForm()
for k, v := range c.Request.PostForm {
if len(v) > 0 {
params[k] = v[0]
}
}
delete(params, "") // 清理空key
// 生成待签名字符串（同客户端）
var keys []string
for k := range params {
keys = append(keys, k)
}
sort.Strings(keys)
var pairs []string
for _, k := range keys {
pairs = append(pairs, fmt.Sprintf("%s=%s", k, params[k]))
}
queryString := strings.Join(pairs, "&")
signStr := fmt.Sprintf("%s&%s&%s", c.Request.Method, c.Request.URL.Path, queryString)
h := hmac.New(sha256.New, []byte(secretKey))
h.Write([]byte(signStr))
serverSig := hex.EncodeToString(h.Sum(nil))
// 安全比较
if !hmac.Equal([]byte(serverSig), []byte(clientSig)) {
c.JSON(401, gin.H{"error": "signature mismatch"})
c.Abort()
return
}
c.Next()
}
}
4. 安全建议与注意事项
- 使用 HTTPS：防止密钥和签名在传输中泄露
- 限制 timestamp 有效期：通常设置为 ±5 分钟
- 使用唯一 nonce 并去重：可用 Redis 记录一段时间内的 nonce
- 敏感操作加动态 Token：如短信验证码、二次确认等
- 避免日志记录 secretKey 或完整签名字符串
- 参数编码一致性：客户端和服务端必须使用相同的编码规则
