PHP hash_equals 怎么避免令牌比较泄露：长度判断、类型边界与签名校验

Webhook 验签接口最容易被忽略的地方，往往不是 HMAC 算法，而是最后那一步“两个字符串是否相等”。如果把收到的签名和本地计算结果交给普通的逐字符比较，比较过程可能随着前缀匹配长度变化而产生可观测差异。PHP 的 hash_equals() 就是为这类机密字符串比较准备的，但它不是把任意输入丢进去就万事大吉：参数顺序、字符串类型和原始请求体都要先处理好。

从一次 webhook 误判开始：签名明明一样却验签失败

一个订单回调接口上线后，偶发的 401 让排查变得很拧巴。开发机上把数组重新编码成 JSON，再计算 HMAC，结果看起来和第三方控制台展示的一样；线上却有少量请求失败。进一步对照发现，服务端取到的请求体已经被框架解析过一次，空格和字段顺序都可能变化，最后又用普通 == 比较两个签名。

这里其实有两条独立问题：签名输入是否一致，比较动作是否适合机密值。先把输入边界固定住，再把比较替换为 hash_equals()，否则只修其中一处，验签仍然不稳。

先看清 hash_equals 的参数顺序和适用对象

PHP 官方手册标注的标准调用形式是：

hash_equals(string $known_string, string $user_string): bool

第一个参数应是服务端已经知道、且不受用户输入影响的字符串；第二个参数才是请求里带来的候选值。函数会以适合机密字符串比较的方式完成判断，长度不同则直接返回 false。这个约定不只是为了好读：把外部输入放在基准位置，会让代码审查者难以确认哪一侧是真正可信的结果。

它适合用来比对 HMAC、两步验证恢复码、一次性令牌这类不能通过时间差反推内容的敏感字符串，别直接拿来替换普通业务字段的等值判断，它本身不会帮你自动做签名算法计算、编码格式转换，也不会顺带校验令牌的过期时间。

把验签边界写成一条可检查的流程

下面这段业务示例把各环节职责拆得很清楚：先读取完全未做处理的原始请求体，再从请求头取出外部传过来的签名，最后把本地算出来的结果和传入签名做比对。示例默认用十六进制格式的 HMAC，如果对接的外部系统约定用 Base64，你要先把两边的编码格式统一之后，再送入比较逻辑。

$rawBody = file_get_contents('php://input');
$provided = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$secret = $_ENV['WEBHOOK_SECRET'] ?? '';

if (!is_string($rawBody) || !is_string($provided) || !is_string($secret)) {
    http_response_code(400);
    exit('invalid signature input');
}

$known = hash_hmac('sha256', $rawBody, $secret);

if (!hash_equals($known, $provided)) {
    http_response_code(401);
    exit('invalid signature');
}

// 验签通过后，再解析 JSON 并处理业务事件。

示例里的 php://input 只作为 PHP 运行时读取原始请求体的代码，不是文章元数据或文件名；发布前的站点 WAF 预检也会区分代码块和提交字段。真实项目还应增加请求时间戳、事件 ID 和重放记录，不能把“比较安全”误当成“请求可信”。

长度、类型和编码：三个容易被漏掉的边界

第一，外部头部可能缺失，$_SERVER 取值也可能不是你预想的字符串。第二，签名格式可能有前缀，例如 sha256=...，需要先按协议拆掉前缀并拒绝空值。第三，十六进制和 Base64 是两种不同表示，同一组摘要不能直接跨格式比较。

防护不止一个函数：补上过期与重放检查

攻击者即使无法伪造新签名，也可能重复发送一份曾经合法的回调。常见的防护做法是让签名覆盖时间戳和原始请求体，例如 timestamp + '.' + rawBody，服务端先判断时间窗，再记录事件 ID。时间窗取多长要看供应商重试策略，不能凭感觉写成永不过期。

$timestamp = $_SERVER['HTTP_X_SIGNATURE_TIMESTAMP'] ?? '';
$eventId = $_SERVER['HTTP_X_EVENT_ID'] ?? '';

if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
    http_response_code(401);
    exit('expired signature');
}

$signedPayload = $timestamp . '.' . $rawBody;
$known = hash_hmac('sha256', $signedPayload, $secret);

if (!hash_equals($known, $provided) || eventWasHandled($eventId)) {
    http_response_code(401);
    exit('replayed or invalid signature');
}

这段代码里的 eventWasHandled() 代表一个有过期时间的持久化记录，不应使用进程内数组代替。验签通过后再落库，或者在数据库里用唯一约束抢占事件 ID，都比“处理完再随手记日志”可靠。

测试时不要只测一条正确签名

最小测试集至少要覆盖这些场景：正确签名、少一个字符的签名、多一个字符的签名、只改最后一位的签名、缺少签名头、空请求体、非 UTF-8 原始字节和过期时间戳。测试目标不是测出普通==比较的响应耗时差异，而是确认所有失败场景返回的响应状态完全统一、审计字段记录完整，并且所有业务写入逻辑绝对不会在验签通过之前执行。

1. 固定一份原始请求体，分别生成十六进制和 Base64 签名，确认两类格式不会被混用。
2. 把签名逐步改动，断言所有非法输入都返回同一种 401 状态语义。
3. 检查日志只记录事件 ID、失败原因类别和请求时间，绝对不记录密钥或完整签名原文。
4. 重复提交已经处理过的事件，确认唯一约束或幂等表能挡住第二次业务写入操作。

相关问题

hash_equals() 能直接比较密码吗？

密码应使用 password_hash() 和 password_verify()。hash_equals() 更适合已经得到的固定机密字符串比较，不能替代密码哈希算法。

两边长度不同为什么直接失败？

长度本身就是字符串格式的一部分。长度不同通常意味着编码方式、前缀或输入内容不一致，应先排查对接协议和原始请求体，不要为了让比较通过而主动截断字符串。

验签通过后还需要权限判断吗？

需要。签名只能说明请求来自持有密钥的一方、且内容传输过程中没有被篡改，业务对象是否允许当前事件修改，仍要经过状态校验和权限校验。

小结

hash_equals() 的价值在于把机密字符串比较从普通相等判断里单独拎出来，但安全边界要靠整条流程共同完成：原始请求体保持一致，本地结果放在可信参数位，输入类型和编码先归一化，再补上时间窗、事件幂等和不泄露敏感值的审计。这样改动才不是“换一个函数名”，而是把 webhook 验签真正收口。

核对资料

• PHP 官方手册：hash_equals
• PHP 官方手册：hash_hmac
• PHP 官方手册：password_verify