Go crypto/subtle.ConstantTimeCompare 为什么长度不同会直接失败：密钥校验与输入边界

线上签名校验突然把一批本来有效的请求判成无效，日志里只剩下一句“密钥不匹配”。排查这类问题时，crypto/subtle.ConstantTimeCompare 经常被误解成“只要内容相同就返回 true”。实际上，它先比较两个字节切片的长度；长度不同会立即返回 false，不会继续把补零、编码转换之类的工作替你完成。

先看清 ConstantTimeCompare 的触发信号

这段函数适合比较已经得到的固定长度敏感字节，例如 HMAC 摘要、随机令牌或经过协议约定的密钥材料。它的返回值只有一个：两个切片长度相同且每个字节都相等时为 true，否则为 false。

package main

import (
    "crypto/subtle"
    "fmt"
)

func main() {
    fmt.Println(subtle.ConstantTimeCompare([]byte("token"), []byte("token")))
    fmt.Println(subtle.ConstantTimeCompare([]byte("token"), []byte("token!")))
}

第二次调用不是“比较到最后才发现内容不同”，而是输入长度已经不同。这里先别急着改比较函数，应该先确认调用方传进来的是原始字节、十六进制文本，还是 Base64 文本。

快速判断：问题出在长度还是编码

最有用的第一条日志不是把密钥打印出来，而是记录非敏感的长度、编码类型和解码错误。可以把校验前的输入整理成下面这张小表：

例如一侧是 32 字节摘要，另一侧是它的 64 个十六进制字符。如果直接把两者转成 []byte 比较，长度必然不一样；这不是摘要错了，而是比较层级错了。

处理步骤：先解码，再做固定长度校验

下面的函数只接受十六进制摘要。它先把两侧文本解码为字节，然后明确检查解码错误和长度，最后才进入常量时间比较：

package verify

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

var ErrInvalidDigest = errors.New("invalid digest")

func EqualHexDigest(wantText, gotText string) (bool, error) {
    want, err := hex.DecodeString(wantText)
    if err != nil {
        return false, ErrInvalidDigest
    }
    got, err := hex.DecodeString(gotText)
    if err != nil || len(want) != len(got) {
        return false, ErrInvalidDigest
    }
    return subtle.ConstantTimeCompare(want, got) == 1, nil
}

这个边界检查不是多余的：它让调用方能区分“格式不合法”和“格式合法但值不相等”，同时避免把不同协议字段悄悄当成同一类数据比较。

用测试把长度边界钉死

测试不要只写一个正确样例。至少覆盖空串、奇数长度、非法字符、合法但长度不同，以及内容不同但长度相同的情况。

func TestEqualHexDigest(t *testing.T) {
    cases := []struct {
        name string
        want string
        got  string
        ok   bool
    }{
        {"same", "aabbccdd", "aabbccdd", true},
        {"same length different value", "aabbccdd", "aabbcc00", false},
        {"different length", "aabbccdd", "aabbcc", false},
        {"odd hex", "aabbccd", "aabbccd", false},
        {"bad hex", "aabbcczz", "aabbcczz", false},
    }
    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            got, err := EqualHexDigest(tc.want, tc.got)
            if (err == nil) != tc.ok || (err == nil && !got) {
                if tc.ok { t.Fatalf("expected valid equal digest") }
            }
        })
    }
}

实际项目中建议把测试拆成“格式错误”和“值不相等”两组，让失败信息更清楚。若摘要来自 HTTP Header，还应额外测试大小写、空格清理规则，以及是否误用了 URL-safe Base64。

回滚与复盘：不要用补零掩盖协议不一致

如果线上刚切换了摘要编码，最稳妥的回滚顺序是恢复旧编码的读取逻辑，同时保留新逻辑的非敏感指标：解码失败数、长度不一致数和最终不相等数。不要把短输入补零到目标长度，也不要为了兼容直接截断长输入；这会把协议错误变成另一种合法输入，反而让审计更难。

确认新旧客户端都能产生同一种字节长度后，再分批切换写入端。复盘时记录摘要算法、文本编码、解码函数、长度期望值和灰度结果，下一次看到“密钥不匹配”时就能先定位比较层级。

常见问题与边界答案

ConstantTimeCompare 能比较字符串吗？

函数接收的是 []byte。字符串需要先明确编码成字节，但敏感值更应先确认双方是否处在同一编码层级。

长度不同还能做到常量时间比较吗？

该函数对长度不同的输入直接返回 false。若协议允许变长值，应先做协议层校验，不要自行补齐后再比较。

为什么十六进制字符串看起来一样，比较结果却是 false？

常见原因是把 64 个十六进制字符与 32 字节原文直接比较。两边都解码到字节层后，结果才具有可比性。

最后的检查清单

• 确认比较双方的输入层级相同：原始字节、十六进制或 Base64 不要混用。
• 记录长度与解码错误，不记录密钥、令牌或完整摘要。
• 长度不同、编码非法和内容不同分别写测试。
• 协议变更优先修复编码契约，不用补零或截断伪造兼容。