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 把外层哈希也用密钥处理了一遍,堵住了这条路。
这对你只有两个实际影响:
hash(密钥 + 消息)算出来的值不等于 HMAC,两者也不能互相验证。很多语言里hmac和hash是两个不同的函数,别顺手选错。- 密钥必须当成字节处理,不能当成「字符串」处理。这也是为什么这个工具要让你显式选择密钥的解释方式。
🧭 工具怎么用:五个选项一次说清
工具地址: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 字节 |
|---|---|---|
secret | 6 字节 | 报错(非法 Hex) |
736563726574 | 12 字节(每个字符各占 1 字节) | 6 字节 |
abcdef | 6 字节 | 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-f | 64 个字符 | 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还是+;中文是否已编码;百分号后大小写(%2Fvs%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)。
所以正确的做法是常量时间比较:不管在第几位发现不匹配,函数耗时都一样,不泄露任何位置信息。这不是性能优化,是安全要求。
对你的启发只有三条:
- 自己写验签代码时,别用普通字符串比较,用语言或库提供的安全比较(Node 的
crypto.timingSafeEqual、Java 的MessageDigest.isEqual、Python 的hmac.compare_digest、Go 的hmac.Equal)。 - 比较前先统一成字节,长度不一致时很多安全比较函数会直接抛错,反而暴露长度信息。
- 这个在线工具的「校验」是给你调试用的,结果只在本页显示;生产环境的验签必须走上面那些实现。
✅ 校验步骤与结果怎么读
操作步骤
- 准备好三样东西:消息原文、密钥(并确认它是文本还是 hex)、预期签名(并确认编码)。
- 选算法(跟服务端文档一致)。
- 选密钥解释方式,填入密钥。
- 粘贴消息。
- 切到「校验」,粘贴预期签名。
- 看结果。
四种结果,四种处理
① 匹配 算法、密钥、待签串三者都对。这条输入值得存下来当基准样本,以后改代码、换库、升级依赖,都拿它做回归。
② 不匹配 按「改动成本从低到高」的顺序排查,不要一上来就怀疑算法:
- 编码对不对(hex / base64 / base64url);
- 大小写、填充、前缀对不对;
- 待签串首尾有没有多余空白或换行;
- 密钥语义对不对(文本 vs hex);
- 参数顺序、URL 编码方式;
- 算法版本(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」,各家细节不同,但都逃不出上面这些坑。
🔗 处理签名时,这些工具能接上
签名排障经常不是孤立的一步,会牵出别的转换:
- 有些方案要求 body 的 SHA-256 参与签名 → 用 哈希计算工具 先算出 body 摘要;
- 签名结果要在 hex 和 base64 之间互转 → Base64 / Base64URL 工具 或 Hex 工具;
- 时间戳是秒还是毫秒、时间窗口对不对 → 时间戳转换工具;
- 想搞清哈希算法怎么选、MD5 还能不能用 → 看 MD5/SHA-256/SHA-3/SM3 区别;
- 想了解编码系列还有哪些工具 → 星点编码工具完整指南。
❓ 常见问题(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 消息认证码工具
文章分享
如果这篇文章对你有帮助,欢迎分享给更多人!