HMAC消息认证码工具 - 在线生成与校验HMAC-SHA256签名

5614 字
28 分钟
HMAC消息认证码工具 - 在线生成与校验HMAC-SHA256签名

🔧 签名这种事,平时不出错,一出错就卡一整天#

对接第三方 API 的时候,你大概率遇到过这种场面:文档写着「把参数按字典序拼接,用 HMAC-SHA256 计算签名」,你把 secret 填进去,算出一串 32 字节的结果,转成 hex 拼到请求头里发出去,服务端回你一个 401,reason 只有四个字:invalid signature。

然后开始排查。参数顺序对不对?字段名大小写对不对?是不是漏了一个空值参数?是不是 body 少了个换行?两个小时过去,最后发现文档里那个密钥写的是十六进制字符串,而你把它当成普通文本原样敲了进去——你用的密钥是 64 个字节,人家用的是 32 个字节。

还有一种更难受的版本:支付回调上线三个月一直好好的,某天开始大量验签失败,日志里只有 sign mismatch。翻到最后发现,上游把金额字段从 100 改成了 100.00。就多了三个字符,签名全废。

这两类问题的共同点很明确:HMAC 算法本身几乎不会算错,错的永远是「你以为参与计算的字节」和「实际参与计算的字节」不一致。 星点 HMAC 消息认证码工具 的用处就是把这些输入摊开——消息、密钥、算法、输出编码各摆一处,让你能把「签名对不对」和「业务代码哪里写错了」这两件事拆开看。


📖 HMAC 到底是什么:给哈希套上一层共享密钥#

HMAC 全称 Hash-based Message Authentication Code,中文一般叫基于哈希的消息认证码。

普通哈希(比如 SHA-256)只回答一个问题:这段数据有没有变过。而且任何人拿到数据都能算,算出来的值都一样。所以普通哈希能证明「完整」,但证明不了「来源」——攻击者改了数据,自己重算一遍哈希就行了。

HMAC 在哈希外面套了一层密钥:算这个值的人必须持有同一把密钥。于是它同时回答两个问题:

  • 数据在传输过程中有没有被改过(完整性);
  • 这条消息是不是持有密钥的那一方发出的(来源认证)。

几个必须记住的性质:

  • 输出定长:HMAC-SHA256 输出 32 字节,HMAC-SHA384 输出 48 字节,HMAC-SHA512 输出 64 字节。长度只跟哈希算法有关,跟消息长短无关。
  • 确定性:同样的消息、同样的密钥、同样的算法,永远得到同样的结果。没有随机数、没有 nonce 参与输出(这一点和 AES-GCM 那类认证加密不同,后者每次加密都要换 IV)。
  • 不可逆:不能从签名反推消息,也不能反推密钥。
  • 不提供保密性:消息本身通常是明文传输的,HMAC 只是贴在旁边的「防伪标签」。想知道 HMAC 能不能藏住内容,答案是不能。
  • 对称密钥:双方各持一份相同的密钥。所以它确认的是「对方也持有这把钥匙」,而不是「对方是某个特定身份」——后者要靠数字签名那套公私钥体系。

🆚 四种东西别再混:普通哈希 / HMAC / 加密 / 数字签名#

这四个概念经常被混着说,实际解决的问题完全不同。下面这张表是排查问题时最该先对齐的一张:

维度普通哈希(SHA-256)HMAC对称加密(AES 等)数字签名(RSA/ECDSA)
是否用密钥不用用共享密钥(对称)用密钥(对称)用私钥签、公钥验
是否可逆不可逆不可逆可逆(解密还原)不可逆
主要解决什么完整性比对、去重、指纹完整性 + 来源认证保密性完整性 + 来源 + 不可否认
谁能生成任何人只有持密钥的人持密钥的人只有持私钥的人
被主动篡改能否发现能发现不一致,但攻击者可重算不能伪造(不知密钥算不出)通常要配合 AEAD/校验不能伪造
典型场景文件校验、缓存键、内容指纹API 签名、Webhook 验签、JWT HS256传输加密、字段加密证书、代码签名、OAuth 断言
输出定长摘要(32 字节等)定长摘要(同哈希算法)密文(长度与明文相关)定长或变长签名值

一句话区分:哈希是「指纹」,HMAC 是「带钥匙的指纹」,加密是「上锁」,数字签名是「盖章」并且这张章只有一个人能盖。 加密本身通常不保证完整性(除非用 AEAD 模式),别指望「加密了就篡改不了」;反过来,HMAC 也不保证隐私。


⚙️ 内部怎么算的(概念级,不用手算)#

理解 HMAC 的结构,能解释掉很多实际遇到的问题。公式大致长这样:

K' = 密钥规整到哈希块长(过长先哈希,过短右侧补零)
HMAC(K, m) = H( (K' XOR opad) || H( (K' XOR ipad) || m ) )

其中 ipad 是 0x36 重复填充,opad 是 0x5c 重复填充,|| 表示字节串拼接。SHA-256 的块长是 64 字节。

为什么设计成两轮哈希,而不是简单地 H(key || message)?因为 MD5、SHA-1、SHA-256 这类 Merkle–Damgård 结构的哈希存在长度扩展问题:知道了 H(key || message) 的值,即使不知道 key,也能在消息后面继续追加数据,算出 H(key || message || extra) 的合法值。对签名系统来说这是致命的。HMAC 把外层哈希也用密钥处理了一遍,堵住了这条路。

这对你只有两个实际影响:

  1. hash(密钥 + 消息) 算出来的值不等于 HMAC,两者也不能互相验证。很多语言里 hmac 和 hash 是两个不同的函数,别顺手选错。
  2. 密钥必须当成字节处理,不能当成「字符串」处理。这也是为什么这个工具要让你显式选择密钥的解释方式。

🧭 工具怎么用:五个选项一次说清#

工具地址:https://www.xingdian.net/app/codec/hmac/

1. 选算法:HMAC-SHA-256 / 384 / 512#

工具只提供这三个算法,没有 MD5、没有 SHA-1。这是刻意的——HMAC 本身能缓解哈希碰撞的影响,但没必要把一个 2004 年就该退场的算法继续摆出来。

  • HMAC-SHA-256:绝大多数 API 签名、Webhook、JWT HS256 用的都是它。
  • HMAC-SHA-384 / SHA-512:出现在部分支付、银行、企业内部规范里。

选哪个不要凭「更强的应该也行」判断。算法不一致,结果必然不同,跟强弱无关。对方文档写 SHA-256,你就选 SHA-256。

2. 密钥 + 解释方式:UTF-8 文本 vs Hex 字节#

这是最容易出事的一栏,单独展开说。

工具提供两种密钥解释:

  • UTF-8 文本:把输入框里的字符按 UTF-8 编码成字节。输入 secret,实际密钥就是 73 65 63 72 65 74 六个字节。
  • Hex 字节:把输入框里的十六进制字符两两解析成字节。输入 736563726574,得到的也是同样这六个字节;但如果输入 secret,Hex 模式会因为 s 不是合法十六进制字符直接报错。

看起来只是两种输入习惯,实际差别巨大:

输入内容选 UTF-8 文本选 Hex 字节
secret6 字节报错(非法 Hex)
73656372657412 字节(每个字符各占 1 字节)6 字节
abcdef6 字节3 字节(ab cd ef)

看到问题了吗?abcdef 这个字符串两种解释都成立,都是「合法输入」,但一个是 6 字节、一个是 3 字节,算出来的签名完全不同,而且不会报错。这就是最典型的一类「密钥对了但服务端说错」。

判断方法看长度:32 字节的密钥写成 hex 是 64 个字符,16 字节写成 hex 是 32 个字符。如果文档里的密钥是一长串 0-9a-f 且长度是 32/40/64,八成是要按 hex 解析。反过来,如果文档给的是 mySecretKey 这种可读单词,就是文本。拿不准的时候,去问对方要一份「密钥的字节长度」——这个问题通常一问就清楚了。

3. 消息:待签串原文#

把服务端实际参与计算的那串内容原样贴进来。注意是原样:包括空格、换行、参数顺序、URL 编码、大小写。下一节会专门讲这个坑。

4. 生成 / 校验#

  • 生成:输入消息 + 密钥,输出签名。
  • 校验:额外输入一段「预期签名」,工具用同样的输入重新计算并比较,告诉你是否匹配。

校验这个动作看着平淡,其实是排障时最有用的功能,后面会单独讲步骤。

5. 输出编码:Hex / Base64 / Base64URL#

同一份签名值,三种写法:

编码外观长度(HMAC-SHA256)适用
Hex只有 0-9a-f64 个字符HTTP header、日志、大多数「签名」字段
Base64含 + /,末尾可能有 =44 个字符放在 JSON 字段里
Base64URL把 + / 换成 - _,去填充43 个字符放在 URL 参数里、JWT 片段

跟着服务端要求走。编码不一致,字符串比较必然失败,而且错误信息通常还是那句 invalid signature,一点提示都没有。

关于「本地计算」#

密钥只在这个页面里用于计算,不上传、不存储。工具内部用的是浏览器 Web Crypto 的原生 HMAC 实现,不是自己拼 hash(key + message) 凑出来的。这一点很重要,因为不少「在线 HMAC」网页是后者,算出来的值跟标准库对不上。


⚠️ 六个坑,按踩到的概率排序#

坑 1:密钥的两种解释语义不同#

上面已经展开过。补充一个实战细节:有些服务端会把密钥做一次 Base64 解码再使用(因为配置里存的是 base64)。这时你要做的不是「选 Base64 模式」(工具没有这个选项),而是先把那段 base64 解码成字节,再以 Hex 或文本的形式喂进去。遇到「三个地方都能填,但都对不上」的情况,先去核对密钥的字节长度,比盲试快得多。

坑 2:待签串必须与服务端逐字节一致#

签名对内容零容忍,差一个字节结果就完全不同。常见的差异点:

  • 参数顺序:文档说字典序,你按插入序拼。
  • 空值参数:a=&b=1 里的 a 到底参不参与签名。
  • 空格与换行:JSON body 格式化过没有、末尾有没有 \n、表单是不是 a=1&b=2 还是 a=1&b=2&。
  • URL 编码:空格是 %20 还是 +;中文是否已编码;百分号后大小写(%2F vs %2f);是不是被编码了两次。
  • 数字格式:100 / 100.00 / 1e2;时间戳是秒还是毫秒。
  • 大小写:HTTP 方法 GET 还是 get;路径 /api/v1/Order 还是 /api/v1/order。
  • 尾部斜杠:/api/v1/order 和 /api/v1/order/ 是两个不同的串。
  • 字符集:body 到底是 UTF-8 还是 GBK。

排查方式:不要靠肉眼比对拼好的字符串,人眼对不出空格和编码差异。正确做法是找一个「已知正确」的样本——官方文档的示例、SDK 算出的值、或者历史成功日志里的签名——把它连同消息和密钥一起放进工具,先验证「同一组输入能复现出同一个签名」。复现成功之后,你才有资格去怀疑业务代码。这一步能省掉大半天。

坑 3:时间戳和 nonce 也在签名里#

很多 API 会把 timestamp、nonce、requestId 放进待签串,目的是防重放。这意味着:

  • 十分钟前拼好的串,现在拿去验新请求一定失败。
  • 只改时间戳不重算签名,等于自己造了一个坏签名。
  • 签名对但时间超窗(常见是 ±5 分钟),服务端照样拒绝,报错信息还是签名错误。

调试时最常踩的一个:拿文档示例里的固定 timestamp 算,结果和示例签名一模一样,就以为大功告成;但真实请求用的是当前时间,于是继续失败。示例能对上,说明算法、密钥、拼接规则都对了,剩下的问题只在「真实请求里到底拼了什么」。这时候该去抓包看实际发出的内容,而不是继续改算法。

坑 4:hash(key + message) 不是 HMAC#

这类实现我见过太多次:

sha256(secret + body)
sha256(secret + body + secret)
md5(key + msg).toUpperCase()

第二种看起来「两头加盐」更稳妥,但它仍然不是 HMAC:没有标准定义、没有 ipad/opad 结构、也挡不住长度扩展。不同人「两头加」的方式还不一样,互操作必然出问题。

判断方法很简单:如果文档写的是 HMAC-SHA256,你算出来的值应该和它给的示例一致。如果 HMAC 对不上、而 hash(secret+body) 反而对上了,那说明要么文档写错,要么你在对接的是一套自制签名方案。这种情况要和对方确认,不要自己偷偷改算法去迁就——今天能跑通,明天换个语言或换个库就会崩。

坑 5:密钥不能写进前端代码#

浏览器里的 JS 是公开的。把 HMAC 密钥写进前端,等于把钥匙印在传单上满街发——打开 DevTools 就能读到,然后任何人都能伪造请求、伪造回调。

正确的分工是:签名在服务端做。这个在线工具适合调试、复现线上问题、验证文档示例、给测试同学对齐口径,不适合作为生产签名链路的一环。它「不上传数据」不等于「可以放生产密钥」。

同理,「用 HMAC 签前端请求」这件事本身要谨慎:只要密钥在客户端,它就保护不了任何东西。

坑 6:输出编码、大小写、前缀#

前面表格说过编码,这里补几个细节:

  • Hex 大小写:有些服务端要求大写。
  • Base64 的 = 填充:有的要求保留,有的要求去掉。
  • Bearer 、sign=、HMAC-SHA256 之类的前缀,有的要带有的不要。
  • 签名外层有没有引号、有没有被 URL 编码过一次。

比对字符串之前,先把这些「非算法因素」逐项对齐,比怀疑密钥有效得多。


🛡️ 为什么服务端验签要用常量时间比较#

这个概念值得单独讲,因为它解释了很多「算法没错但就是不安全」的代码。

普通的字符串比较(a == b、str.equals())通常在第一个不同的字节处就返回了。如果服务端用这种方式比较签名,攻击者可以通过测量响应时间,一个字节一个字节地把正确签名猜出来——先猜第一位,响应变慢了说明猜对了,再猜第二位。32 字节的签名,逐字节暴力猜的代价会从天文数字降到「几千次请求」这个量级。这类攻击叫时序攻击(timing attack)。

所以正确的做法是常量时间比较:不管在第几位发现不匹配,函数耗时都一样,不泄露任何位置信息。这不是性能优化,是安全要求。

对你的启发只有三条:

  1. 自己写验签代码时,别用普通字符串比较,用语言或库提供的安全比较(Node 的 crypto.timingSafeEqual、Java 的 MessageDigest.isEqual、Python 的 hmac.compare_digest、Go 的 hmac.Equal)。
  2. 比较前先统一成字节,长度不一致时很多安全比较函数会直接抛错,反而暴露长度信息。
  3. 这个在线工具的「校验」是给你调试用的,结果只在本页显示;生产环境的验签必须走上面那些实现。

✅ 校验步骤与结果怎么读#

操作步骤#

  1. 准备好三样东西:消息原文、密钥(并确认它是文本还是 hex)、预期签名(并确认编码)。
  2. 选算法(跟服务端文档一致)。
  3. 选密钥解释方式,填入密钥。
  4. 粘贴消息。
  5. 切到「校验」,粘贴预期签名。
  6. 看结果。

四种结果,四种处理#

① 匹配 算法、密钥、待签串三者都对。这条输入值得存下来当基准样本,以后改代码、换库、升级依赖,都拿它做回归。

② 不匹配 按「改动成本从低到高」的顺序排查,不要一上来就怀疑算法:

  1. 编码对不对(hex / base64 / base64url);
  2. 大小写、填充、前缀对不对;
  3. 待签串首尾有没有多余空白或换行;
  4. 密钥语义对不对(文本 vs hex);
  5. 参数顺序、URL 编码方式;
  6. 算法版本(256 / 384 / 512)。

③ 校验时直接报错(签名格式非法) 多半是预期签名的长度或字符集不对。HMAC-SHA256 的 hex 必须是 64 个字符,base64 应该能正常解码;混进了空格、换行、引号、sign= 前缀都会报错。

④ 工具里匹配,服务端仍拒绝 签名只是校验链条上的一环。继续查:时间窗口、nonce 是否已被用过、appId/密钥版本是否对、IP 白名单、网关有没有改写 body(比如压缩、转码、加字段)。这类问题在工具里永远查不出来,要去服务端日志和网关配置里找。


🌐 几类常见签名场景,各自的坑不一样#

云服务 OpenAPI 签名串通常是 CanonicalRequest:HTTP 方法、路径、规范化查询串、参与签名的 header、body 的哈希值。里面往往嵌套一层「先对 body 做 SHA-256 再参与 HMAC」,所以你会同时用到两个工具。这类方案参数多、规范化规则细,建议先用官方提供的签名调试页面把第一个请求跑通。

支付回调 / Webhook 服务端把若干关键字段按固定顺序拼接后 HMAC,你在接收端重算比对。最高频的错误是金额格式(100 vs 100.00)和「空值字段到底参与不参与」。

内部服务间调用 header 里带 timestamp + nonce + sign。验签失败时先看时间(服务器时钟漂移很常见),再看 nonce 缓存是不是被误清。

JWT 的 HS256 签名对象是 base64url(header) + "." + base64url(payload),密钥就是那个共享 secret。签名怎么算都对、但库报验签失败,常见原因有两个:header/payload 被重新序列化过(字段顺序、空格变了,导致 base64url 段变了),或者密钥被库当成 base64 又解码了一次。

短信 / 邮件 / 对象存储 多为「参数排序 → 拼接 → 加 key → HMAC → 转大写 hex」,各家细节不同,但都逃不出上面这些坑。


🔗 处理签名时,这些工具能接上#

签名排障经常不是孤立的一步,会牵出别的转换:


❓ 常见问题(FAQ)#

HMAC 是加密吗?能藏住消息内容吗? 不是。HMAC 是消息认证码,只验证完整性和来源,不提供保密性。消息明文发出去,旁边附一段签名,中间人看得见内容,但改不了内容而不被发现。
HMAC-SHA256 和普通的 SHA-256 有什么区别? SHA-256 不需要密钥,任何人算出来都一样,只能用来比对内容是否一致;HMAC-SHA256 需要共享密钥,不知道密钥就算不出正确值。同一个消息,两者的结果完全不同,不能互相替代。
为什么工具提示我的密钥不是合法 Hex? 你选了「Hex 字节」解释方式,但输入里有 0-9、a-f 之外的字符(比如 `s`、`k`、`-`),或者字符个数是奇数。要么改成「UTF-8 文本」,要么把密钥换成真正的十六进制串。
HMAC-SHA256 的签名应该有多长? 原始输出固定 32 字节。写成 hex 是 64 个字符,标准 Base64 是 44 个字符(末尾带一个 `=`),Base64URL 去掉填充是 43 个字符。长度不符基本可以断定编码选错或内容被截断。
文档示例能对上,真实请求还是 401,问题在哪? 说明算法、密钥、拼接规则都对了,问题在「真实请求到底拼了什么」。去抓包看实际发出的待签串,重点看时间戳、nonce、空值参数、body 有没有被网关改写、金额之类字段的格式。
这个工具会把我的密钥发到服务器吗? 不会。密钥只在当前页面内参与计算,不上传、不存储,关掉页面就没了。但请记住:调试用的密钥和线上生产密钥最好分开,别把生产密钥贴进任何网页。
为什么不能直接在前端算 HMAC? 因为前端代码和密钥对所有人可见,任何人打开开发者工具就能拿到密钥并伪造请求。签名必须在服务端完成,前端只负责把服务端给的签名带在请求里。

💬 总结#

HMAC 这个概念本身不难:哈希 + 共享密钥,验证完整性和来源,不负责保密。难的是工程细节——密钥是文本还是字节、待签串里到底有哪些字符、编码用 hex 还是 base64、时间戳有没有参与。这些细节不会在报错信息里告诉你,只会还你一句 invalid signature。

遇到签名问题时的顺序建议:先用 HMAC 工具 复现一个「已知正确」的样本,确认算法和密钥没问题;再拿真实请求的待签串去比对,一处一处排;最后才去怀疑代码逻辑。这个顺序能把大部分「卡一整天」的问题压缩到半小时以内。

立即体验:访问 HMAC 消息认证码工具

文章分享

如果这篇文章对你有帮助,欢迎分享给更多人!

相关文章 智能推荐
1
星点编码工具完整指南 - 11个在线编码解码/哈希/签名工具导航
编码工具 星点编码工具系列总览:11 个工具完整导航,覆盖 Base64/Base64URL、Base32、Hex、Unicode、HTML 实体、多语言字符串转义、MD5/SHA/SHA-3/SM3 哈希、HMAC、UUID、文件哈希校验与 Punycode 域名转换。含编码与加密、哈希、签名的区别对比、按场景选工具表和常见误区,全部浏览器本地处理不上传。
2
Hex十六进制编码解码工具 - 文本与十六进制在线互转
编码工具 Hex 十六进制编码解码工具使用指南:讲清一个字节为什么对应两位十六进制、UTF-8 文本怎么变成字节(含中文 3 字节实例),以及协议调试、抓包看字节、写测试数据、识别文件头时的实际用法;说明大小写、分隔符、0x 前缀三个选项的差异,非 UTF-8 时按字节展示与 BOM/NUL 提示的含义,附对比表与常见错误。
3
文件哈希校验工具 - 本地计算文件MD5/SHA256校验值(文件不上传)
编码工具 在线文件哈希校验工具:拖入文件即可分块计算 MD5、SHA-1、SHA-256、SHA-384、SHA-512 校验值,支持多算法同时计算、真实进度与随时取消,文件全程在浏览器本地读取、不上传服务器。含与 certutil、Get-FileHash、sha256sum、shasum 的结果对照、不一致排查与安全提醒,适合核对系统镜像、安装包、设计稿和发布包。
4
字符串转义工具 - JSON/Java/Python/Go/C 多语言在线转义与反转义
编码工具 在线字符串转义与反转义工具使用指南:讲清反斜杠、双引号、换行、制表符、回车与 NUL 为什么要转,对照 JSON、JavaScript、Java、Python、Go、C/C++ 在 Unicode 表示、\x 与八进制、raw string、行连接上的差异,说明 JSON 反转义走标准 parser、只接受字符串字面量,并给出五步操作、跨语言示例与常见错误。
5
Base64编码解码工具 - 在线Base64/Base64URL/Data URL互转(本地处理)
编码工具 在线 Base64 编码解码工具:标准 Base64(+ /)与 URL 安全 Base64URL(- _)双字母表互转,填充可选、可忽略排版空白、自动识别 Data URL 并拆出 MIME,解码结果非 UTF-8 时按 Hex 展示原始字节。含长度膨胀、填充规则、中文乱码与「+ 变空格」排查,浏览器本地处理,不上传数据。
随机文章 随机推荐
公告
🎉 已升级 2.0 版本,欢迎使用。
分类
标签
站点统计
文章
247
分类
31
标签
973
总字数
633,901
运行时长
0 天
最后活动
0 天前

目录