Go hmac.Equal 怎么比较消息认证码

正确用法是：接收方先用同一哈希函数、同一共享密钥和完全相同的消息字节重算期望 MAC，再把对方传来的十六进制或 Base64 标签解码成字节，最后调用 hmac.Equal(received, expected)。不要用普通字符串相等、bytes.Equal 或手写循环替代，因为普通比较可能随首个不同字节提前结束，产生可观察的时间差。

官方文档：https://pkg.go.dev/crypto/hmac

为什么普通相等比较不够

HMAC 用共享密钥对消息计算认证标签。接收方拿到消息和标签后，用同一密钥重算一次：两个标签一致，说明消息在传输中没有被改动，并且发送方持有正确密钥。这里验证的是消息认证，不是把消息加密。

普通字节或字符串比较通常在发现第一个不同位置时结束。如果攻击者能够大量请求并精细测量响应时间，匹配前缀越长可能花费越久，进而泄露标签的局部信息。Go 官方文档因此明确提醒接收方使用 hmac.Equal，避免这种时序侧信道。

hmac.Equal 的比较语义

hmac.Equal(mac1, mac2) 比较两个 MAC 字节切片并返回布尔值。标准库实现把工作交给 subtle.ConstantTimeCompare；相同长度的切片会按恒定时间方式比较。长度不同会直接返回 false，源码注释说明这通常意味着使用了完全不同的哈希函数。

hmac.Equal 只负责安全比较，不会替你解码十六进制字符串、移除请求头前缀、重新计算 HMAC，也不会判断选用的算法是否正确。调用前必须先把两边整理成同一语义的原始标签字节。

完整验证一条十六进制 MAC

下面封装一个 HMAC-SHA256 验证函数。传入消息原始字节、共享密钥和对方发送的十六进制标签；函数先解码，再重算，最后安全比较。

package auth

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
)

func VerifyHex(message, key []byte, receivedHex string) (bool, error) {
	// 先把传输用的十六进制文本还原成 MAC 原始字节。
	received, err := hex.DecodeString(receivedHex)
	if err != nil {
		return false, fmt.Errorf("decode HMAC: %w", err)
	}

	// 用完全相同的消息字节、共享密钥和 SHA-256 重算期望标签。
	mac := hmac.New(sha256.New, key)
	_, _ = mac.Write(message) // hash.Hash 写入内存字节不会返回业务错误。
	expected := mac.Sum(nil)

	// 使用恒定时间比较，避免普通相等判断产生时序侧信道。
	return hmac.Equal(received, expected), nil
}

如果上游使用 Base64，把 hex.DecodeString 换成与对方约定一致的 base64.StdEncoding.DecodeString 或 URL-safe 变体。不要看到标签长得像文本，就直接把字符串转成 []byte；那得到的是编码字符的字节，不是摘要本身。

在 HTTP Webhook 中使用

Webhook 最常见的坑是先把 JSON 解码成结构体，再重新序列化后验签。空格、字段顺序和转义形式可能改变，重算出来的 HMAC 就不同。应先读取请求体原始字节完成验证，验证成功后再解析 JSON。

package webhook

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"io"
	"net/http"
	"strings"
)

func VerifyRequest(r *http.Request, secret []byte) ([]byte, error) {
	// 限制请求体大小，避免验签接口被超大载荷占用过多内存。
	body, err := io.ReadAll(io.LimitReader(r.Body, 1

生产代码还应把共享密钥放在受控的密钥管理系统或环境注入通道中，不要写入仓库、日志或错误响应。验签失败时返回统一错误，不要把“前几个字节匹配”之类内部信息暴露给调用方。

排查一直返回 false 的情况

先不要怀疑 hmac.Equal，而是逐项核对它两边的输入。最常见的原因是收到的标签仍是编码文本，或参与计算的消息已经变化。

采用建议

把 HMAC 验证封装成一个窄函数：输入只包含原始消息、密钥和传输标签，内部统一负责前缀处理、解码、重算和 hmac.Equal。这样上层业务不会在不同接口里重复写不一致的比较逻辑。

如果协议允许截断 MAC，应在协议层明确固定长度，并在比较前严格检查；不能由调用方随意截断期望值。对于新接口，还应把算法、编码格式、请求头名称和签名覆盖范围写进双方协议，而不是靠示例猜测。

常见问题

hmac.Equal 的两个参数顺序重要吗？

对相等判断结果没有影响，但推荐保持 received, expected 或团队统一的顺序，减少审查时的认知负担。

可以直接比较十六进制字符串吗？

不建议。先用 hex.DecodeString 得到 MAC 原始字节，再调用 hmac.Equal。这样编码边界清楚，也不会误把字符大小写或前缀混进标签。

hmac.Equal 会验证共享密钥吗？

不会。它只比较两个字节切片。共享密钥是否正确，体现在你重算出的期望 MAC 是否与收到的 MAC 一致。

为什么相同 JSON 对象仍然验证失败？

HMAC 针对字节，不针对“语义相同的 JSON 对象”。字段顺序、空格、换行和转义形式变化都会改变摘要，应使用收到的原始请求体字节。