Go hmac.Equal 为什么比字符串比较更适合校验签名

Go 校验 HMAC 签名时，推荐把请求里的 Base64 或十六进制文本先解码成字节，再用 hmac.Equal 比较服务端重新计算的 MAC。它比直接写 string(received) == string(expected) 更适合安全敏感的签名判断，因为 crypto/hmac 专门提供了不泄露内容比较时序的函数。

为什么字符串比较不适合做签名判断

普通字符串比较通常可以在发现第一个不同字节后结束。对一般业务字段这没有问题，但 MAC 属于攻击者可以反复提交、服务端会反复判断的认证材料；比较耗时如果与前缀匹配长度有关，就可能给远程观察者留下侧信道线索。这里不需要自己猜测或手写“逐字节但不提前返回”的循环，标准库已经提供了更明确的 API。

还要先分清编码层和认证层。请求头里常见的是 Base64 文本，日志里也可能写成十六进制字符串。它们都不是 MAC 本身，直接比较文本会把编码格式差异和认证值混在一起；正确顺序是验证编码、解码为字节，再比较。

用 hmac.New 计算 expectedMAC，再交给 hmac.Equal

下面的示例假设客户端把签名放在 Base64 编码的请求头中。服务端必须使用同一份原始消息和共享密钥重新计算 MAC，不能把已经格式化过的 JSON、自动补过换行的文本或另一种字符编码当成同一个输入。

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"errors"
)

// validSignature 校验 Base64 编码的 HMAC-SHA256 签名。
func validSignature(message, encodedSignature string, key []byte) (bool, error) {
	// 先解码传输文本；编码错误不能当成“签名不匹配”后继续处理。
	receivedMAC, err := base64.StdEncoding.DecodeString(encodedSignature)
	if err != nil {
		return false, errors.New("签名不是合法的 Base64")
	}

	// 使用与签名方一致的哈希算法和密钥，重新得到服务端期望值。
	mac := hmac.New(sha256.New, key)
	_, _ = mac.Write([]byte(message)) // hash.Hash 的 Write 不会返回常规写入错误。
	expectedMAC := mac.Sum(nil)

	// 只比较 MAC 字节；hmac.Equal 会处理比较时序和长度边界。
	return hmac.Equal(receivedMAC, expectedMAC), nil
}

这个函数的返回值区分了两类情况：Base64 语法错误是输入格式问题，返回错误；格式合法但 MAC 不一致则是 false, nil。接口层可以把两者都映射成统一的未通过响应，避免向外暴露过多认证细节，但日志里仍可保留内部分类。

hmac.Equal 负责比较，不负责完整鉴权

Go 官方实现会在 MAC 长度不一致时直接返回不相等，因为不同长度通常意味着使用了不同的摘要格式；长度一致后再进行内容的常量时间比较。因此，调用方不必为了“更安全”先写一段普通的长度和字符串判断，也不要把用户可控的签名截断到固定长度再比较。

不过，hmac.Equal 不能修复上游输入问题。若服务端签名的消息拼接顺序不同、JSON 空格不同、时间戳没有纳入签名，或者密钥读取错误，比较结果仍然会失败；若缺少时间窗口、请求唯一值或服务端状态，它也不会自动提供重放防护。

接入接口时的四项复查

1. 确认签名覆盖的原始内容是稳定的，尤其检查 JSON 序列化、换行和字符编码。
2. 确认客户端与服务端使用同一摘要算法、同一密钥和同一编码格式。
3. 确认解码失败、签名不匹配、时间戳过期都不会继续执行业务写操作。
4. 若接口需要防重放，把时间戳、随机数或请求 ID 纳入签名并在服务端检查有效期。

常见问题

为什么不直接使用 subtle.ConstantTimeCompare？

它是更底层的字节切片比较函数；针对 MAC 校验，hmac.Equal 表达的意图更清楚，也避免调用方重复处理 MAC 长度语义。

签名是十六进制字符串时还要解码吗？

要。使用 encoding/hex.DecodeString 得到字节后再调用 hmac.Equal，不要把十六进制字符本身当作摘要内容。

hmac.Equal 能防止重放攻击吗？

不能。它只回答两个 MAC 是否相等；时间窗口、请求唯一值、密钥轮换和失败策略需要由完整协议另外设计。

把比较对象从“编码后的字符串”还原成“MAC 字节”，再让 hmac.Equal 完成最后判断，通常就是 Go HMAC 签名校验中最关键的一步。