Go HMAC 怎样用 ConstantTimeCompare 比较签名

在 webhook、回调接口或内部服务鉴权中，服务端通常会用共享密钥重新计算一份 HMAC，再和请求携带的签名比较。这个比较动作不能直接用字符串的逐字节判断来代替，否则比较过程可能因为首个不同字节的位置不同而暴露差异。

Go 的标准库已经给出了更合适的入口：优先使用 hmac.Equal 比较两份原始 MAC；如果需要直接处理其他等长的敏感字节，再考虑 subtle.ConstantTimeCompare。两者都不是“把任意字符串变安全”的开关，签名编码、长度判断和错误返回仍然要由调用方处理。

先把签名比较的对象分清楚

HMAC 的输入是消息和共享密钥，输出是固定长度的 MAC。以 SHA-256 为例，输出是 32 字节。客户端把这份 MAC 放进 HTTP 头时，常常会编码成 64 个十六进制字符；服务端收到的是编码后的文本，重新计算得到的却是原始字节。

因此，服务端要么把请求签名解码成字节后比较，要么把计算结果编码成同一种文本后再比较。实际工程中更适合前一种方式：比较对象保持为 []byte，避免把大小写、前缀和编码错误混进安全比较本身。

用 hmac.New 计算 expected MAC

先固定消息的字节来源，再使用同一份密钥计算服务端期望的 MAC。mac.Write 的错误虽然对标准库实现通常不会出现，但仍应按 hash.Hash 接口保留处理路径；签名校验失败时统一返回失败，不要把密钥、期望签名或解码细节写入客户端响应。

package auth

import (
    "crypto/hmac"
    "crypto/sha256"
)

// expectedMAC 根据完整消息和共享密钥计算服务端期望的原始 MAC。
func expectedMAC(message, key []byte) ([]byte, error) {
    // 使用同一个哈希构造函数，确保客户端和服务端算法一致。
    mac := hmac.New(sha256.New, key)
    if _, err := mac.Write(message); err != nil {
        // 保留接口错误，避免把计算失败误当成验签失败。
        return nil, err
    }
    // Sum(nil) 返回新追加的摘要字节，不修改 message。
    return mac.Sum(nil), nil
}

这一步只负责“算出应该是什么”，还没有判断请求是否可信。不要把收到的签名直接当作消息再次计算，也不要在不同请求之间复用同一个可写的 HMAC 对象。

优先使用 hmac.Equal 比较两份 MAC

hmac.Equal 是这个场景的首选 API。它表达了比较对象是 MAC，并且把底层的常量时间比较细节封装起来。先把十六进制字符串解码为字节，再交给它比较：

package auth

import (
    "crypto/hmac"
    "encoding/hex"
    "errors"
)

var errInvalidSignature = errors.New("invalid signature")

// validSignature 将外部十六进制签名还原为字节后，再与期望 MAC 比较。
func validSignature(message, key []byte, providedHex string) error {
    // DecodeString 同时检查奇数长度和非法十六进制字符。
    providedMAC, err := hex.DecodeString(providedHex)
    if err != nil {
        // 对外只返回统一错误，避免泄露解码细节。
        return errInvalidSignature
    }

    expected, err := expectedMAC(message, key)
    if err != nil {
        // 计算错误属于服务端问题，不应伪装成客户端签名格式错误。
        return err
    }

    // hmac.Equal 负责安全比较内容，并在长度不一致时返回 false。
    if !hmac.Equal(providedMAC, expected) {
        return errInvalidSignature
    }
    return nil
}

这里的顺序很重要：外部文本先进行格式解码，解码后的原始 MAC 再交给 hmac.Equal。不要把 providedHex == hex.EncodeToString(expected) 当成等价写法；即使文本比较结果正确，它也没有表达 MAC 比较的语义。

什么时候直接使用 subtle.ConstantTimeCompare

crypto/subtle 提供更底层的 ConstantTimeCompare。它返回整数 1 或 0，而不是布尔值；两份切片长度不同时会立即返回 0，长度相同时才按内容进行不依赖内容的比较。因此它适合已经明确是敏感字节且需要底层组合的场景，但对 HMAC 验签仍建议让 hmac.Equal 表达意图。

package auth

import "crypto/subtle"

// equalTokenBytes 只比较已经完成编码解码的敏感字节。
func equalTokenBytes(left, right []byte) bool {
    // 长度检查是明确的边界判断；内容比较交给 ConstantTimeCompare。
    if len(left) != len(right) {
        return false
    }
    // 返回值为 1 才表示所有字节一致。
    return subtle.ConstantTimeCompare(left, right) == 1
}

这里的显式长度判断不是为了“让比较更安全”而额外添加的魔法，而是为了让调用者清楚知道：不同长度的输入本来就不可能是同一份固定长度令牌。ConstantTimeCompare 的时间不会因为内容在中途不同而继续缩短，但长度本身仍然是可观察的输入属性。

长度、编码和请求校验要分别处理

常见问题不是 API 不会调用，而是把三个层次混在了一起：

• 编码层：请求头里的十六进制或 Base64 文本必须先按约定解码，非法字符和奇数长度直接失败。
• 长度层：SHA-256 HMAC 的原始结果应是固定字节数；如果解码后长度不对，不必进入内容比较。
• 内容层：两份长度合理的原始 MAC 使用 hmac.Equal，不要自己写遇到第一个不同字节就返回的循环。

如果协议允许多个算法或多个编码，先根据明确的协议字段选择算法和解码器，再进入同样的流程。不要为了兼容大小写而把两份签名先转成小写字符串，这会让“协议解析”和“敏感值比较”纠缠在一起。

一份可复用的验签流程

可以把入口收敛为以下五步：取原始请求消息、读取并解码签名、计算期望 MAC、使用 hmac.Equal 比较、统一处理结果。若消息来自 HTTP 请求，签名通常覆盖的是约定的原始请求体或规范化字符串，不能一边验签一边重新拼接 JSON 字段顺序。

package auth

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

var errUnauthorized = errors.New("unauthorized")

// VerifyRequest 校验已经按协议读取出的原始消息和十六进制签名。
func VerifyRequest(message, key []byte, signatureHex string) error {
    // 先解码外部表示，防止把十六进制字符当成 MAC 字节比较。
    provided, err := hex.DecodeString(signatureHex)
    if err != nil {
        return errUnauthorized
    }

    mac := hmac.New(sha256.New, key)
    if _, err := mac.Write(message); err != nil {
        return err
    }
    expected := mac.Sum(nil)

    // hmac.Equal 同时表达 MAC 语义，并避免内容比较的早停差异。
    if !hmac.Equal(provided, expected) {
        return errUnauthorized
    }
    return nil
}

在 HTTP 层，校验失败可以统一返回 401 或 403，日志只记录请求标识、失败阶段和必要的计数，不记录密钥、完整签名或完整请求体。若服务需要区分客户端格式错误和服务端计算错误，也应在内部日志区分，对外仍保持不会泄露敏感细节的响应。

容易踩坑的几种写法

结语：固定流程比记住一个函数更重要

Go HMAC 验签的核心不是单独背下 ConstantTimeCompare，而是把输入表示、长度边界和内容比较分层处理：外部签名先解码，期望值按同一算法计算，最终用 hmac.Equal 比较原始 MAC。只有在明确需要底层组合时，才直接使用 subtle.ConstantTimeCompare。

这样做既能避免把十六进制字符串误当成 MAC，也能让长度不一致、格式错误和内容不匹配分别落在清晰的错误路径中。

相关问题

HMAC-SHA256 的签名应该传十六进制还是 Base64？

两者都可以，关键是协议固定一种编码并在服务端严格解码。二进制 MAC 才是比较对象，编码文本只是传输表示。

长度不一致时还需要调用 ConstantTimeCompare 吗？

不需要为了制造相同长度而填充输入。对于 HMAC 使用 hmac.Equal 即可；直接使用底层 API 时应明确长度不同就是失败。

hmac.Equal 能替代整个 HMAC 验证流程吗？

不能。它只比较两份 MAC，消息选取、密钥管理、签名解码、重放防护和错误响应仍由协议和业务层负责。