PHP hash_equals 怎样比较签名避免时序差异

我在给一个回调接口加签名校验时，最先踩到的坑不是 HMAC 算法，而是把签名当普通字符串用 === 比较。PHP 官方提供的 hash_equals() 正是用来比较这类保密字符串的：服务端先用共享密钥重算期望签名，再把期望值放在第一参数，把请求带来的签名放在第二参数。这样能避免普通比较因提前发现不同字符而泄露更多时序信息。

官方手册：https://www.php.net/manual/en/function.hash-equals.php

最小可靠写法是：同一份原文、同一个算法和密钥、同一种输出编码生成期望签名，再执行 hash_equals($expected, $provided)。不要交换参数，也不要把不同长度或不同编码的值直接拿来比较。

我最后保留的签名校验边界

这段代码只解决“请求签名是否等于服务端重算结果”。它不负责解析业务字段、不负责生成密钥，也不代表请求本身一定可信；时间戳、重放控制和权限判断仍然要由接口协议单独处理。

为什么不能继续用 ===

=== 适合普通业务值的严格相等判断，但签名比较面对的是保密值。普通字符串比较通常会在发现首个不同字符后结束，差异位置可能让攻击者获得时序线索。hash_equals() 的用途就是降低这类比较泄露，返回值仍然只有布尔值，调用方应把 false 当成统一的校验失败。

这里有一个容易被忽略的条件：两个参数长度不同，函数会立即返回 false，而已知字符串的长度也可能从时序中暴露。因此长度不一致首先说明请求签名格式错了；它不是让你改用 === 的理由，也不是把输入随意补齐的理由。

HMAC 输出格式必须从头到尾一致

我实际排查这类问题时，第二个高频原因是服务端生成了十六进制字符串，而客户端传来了原始二进制或 Base64 文本。hash_hmac() 的第四个参数为 false 时返回小写十六进制；为 true 时返回原始二进制。两端必须约定一种格式，再把同一格式传给 hash_equals()。

参数顺序、长度和失败分支怎么定

如果你的协议使用 Base64，就让发送端和接收端都明确使用 Base64；如果使用十六进制，就保持大小写和字符集约定一致。不要为了“让长度相同”而截断、补零或自动转换未知编码，因为那会改变签名语义。

适合谁，以及我会怎么落地

Webhook、回调通知、下载地址签名和内部服务间的轻量认证，都适合把“生成期望值”和“安全比较”拆成两个清楚的边界。对我来说，最稳的落地方式是把算法、编码、原文拼接规则和失败响应写进协议文档，再用固定的测试向量覆盖正常值、改一个字符、空签名、长度错误和编码错误。

最后记住三件事：hash_hmac() 负责生成带密钥的摘要，hash_equals() 负责安全比较，签名匹配也不等于完成了时间窗口、重放和权限校验。把这三层分开，排查时就不会把“算法算错”和“认证策略缺失”混成一个问题。

相关问题

hash_equals 能不能比较密码？

它是通用的字符串安全比较函数。密码存储应使用 PHP 的密码哈希 API，不能把明文密码或固定密钥写进代码；本文只讨论已有签名字符串的比较。

为什么 hash_hmac 算出来的值总是比请求签名长？

先检查第四个参数是否一端使用了原始二进制、一端使用了小写十六进制或 Base64，再检查算法、原文拼接和字符编码是否一致。