PHP hash_hmac 怎样生成带密钥摘要

PHP 里要生成“带密钥摘要”，直接使用 hash_hmac()。它把算法名、待签名消息和共享密钥组合起来，默认返回小写十六进制字符串；如果协议要求原始字节，再把第四个参数设为 true。验签时不要把结果当普通字符串随意比较，而应该用 hash_equals()。

官方文档：https://www.php.net/manual/en/function.hash-hmac.php

最常用的写法是 hash_hmac('sha256', $data, $key)。发送端和接收端必须对同一份规范化数据使用同一个密钥和算法；接收用户传来的摘要时，用 hash_equals($expected, $provided) 判断。

先分清 hash 和 HMAC 解决的问题

普通哈希只把消息映射为摘要，适合做内容指纹或完整性标识，但只要消息公开，任何人都能重新计算。HMAC 在摘要计算中加入共享密钥，接收方只有拿到同一密钥才能生成相同结果，因此更适合接口签名、回调验签和内部服务之间的请求认证。

这里的关键不是把密钥拼接到字符串两端，而是让 hash_hmac() 按 HMAC 规则处理密钥。双方还要先约定数据的字节序列：参数排序、空值表示、空格和 JSON 编码只要有一个不同，摘要就会不同。

用三个输入生成文本摘要

函数签名可以记成 hash_hmac(algo, data, key, binary)：algo 是算法名，data 是要认证的消息，key 是共享密钥，binary 决定输出格式。默认值为 false，结果是小写十六进制字符串，最适合放入 HTTP 头或 JSON 字段。

示例中的空格只是为了提醒数据规范化的重要性，真实协议应在签名文档中明确格式，并在发送和接收两端使用完全相同的规则。摘要不是加密结果，拿到摘要不能反推出密钥。

binary 参数决定摘要怎样传输

当 binary=false 时，返回值是小写十六进制文本；当 binary=true 时，返回原始二进制字节。二进制形式更适合后续编码或存储，不适合直接打印到页面，也不应未经编码就塞进 JSON 或 URL。

十六进制和 Base64 只是两种不同的传输表示，不代表两次计算得到了不同的 HMAC。协议一旦选定表示方式，验签端就要先按同样的方式得到待比较字符串。

收到签名后用 hash_equals 比较

接收请求时，服务端根据原始数据和本地密钥生成 $expected，再把请求中带来的 $provided 作为第二个参数传给 hash_equals()。这个函数用于避免普通比较在执行时间上的差异泄露已知摘要内容。

hash_equals() 要求两个参数是字符串，并且长度不同会直接返回 false。所以不要先把用户输入当作算法名、数组或对象使用，也不要把“长度不同”当成可以继续处理业务的情况。

算法选择和 PHP 版本边界

hash_hmac() 的算法必须是支持 HMAC 的密码学哈希算法，例如 sha256。可以用 hash_hmac_algos() 查看当前环境支持的算法，但“支持”不等于“适合所有场景”，不要为了兼容旧系统继续选择已不适合新协议的算法。

PHP 8 中，未知算法或非密码学哈希算法会抛出 ValueError；旧版本的错误表现并不完全相同。生产协议不应在每个请求里动态协商算法，而应该把算法作为版本化配置，并在升级 PHP 后检查异常处理路径。

把 HMAC 用在接口签名时的三个约定

• 固定数据：先约定字段排序、编码、空值、时间戳和换行规则，签名和验签不能各自拼接。
• 固定表示：十六进制或 Base64 选一种并写入协议，不能一端输出原始二进制、另一端拿十六进制比较。
• 固定比较：本地计算的摘要放在 hash_equals() 第一位，用户提交值放第二位；密钥只从服务端安全配置读取。

常见问题

hash_hmac() 能不能替代密码加密？

不能。HMAC 用来证明消息和密钥之间的关联，结果不可逆；需要让内容可恢复时，应使用专门的加密方案。

为什么两端密钥一样，摘要仍然不同？

优先检查算法、参数顺序、字符编码、空格、换行、URL 编码和 JSON 字段顺序。HMAC 计算的是字节序列，不是“看起来相同”的业务对象。

能不能用 == 或 === 验签？

接口签名应使用 hash_equals()。普通比较没有表达出“已知摘要与用户输入”的安全语义，也可能暴露与比较时间相关的信息。