HMAC 生成器与签名校验工具

什么是 HMAC？

const crypto = require('crypto');

// HMAC-SHA256 with a UTF-8 text key, hex output
const hmac = crypto
  .createHmac('sha256', 'my-secret-key')
  .update('Hello, World!')
  .digest('hex');

console.log(hmac);
// → 'cf3141611e22ea26a9cac6fe41d941274dd6653622c83cba13972d177bd69699'

// Verify a signature in constant time
function verify(message, key, expectedHex) {
  const actual = crypto.createHmac('sha256', key).update(message).digest();
  const expected = Buffer.from(expectedHex, 'hex');
  return actual.length === expected.length &&
    crypto.timingSafeEqual(actual, expected);
}

核心特性

HMAC 示例

Hello, World!

cf3141611e22ea26a9cac6fe41d941274dd6653622c83cba13972d177bd69699

{"id":42,"event":"user.created"}

Cd2f7zTKaJFeG6k+t1FcvDPn51OAZ2f4GrxkCUgMhGs=

what do ya want for nothing?

5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843

The quick brown fox

36f44b125a8a90639dc46733039571792e081e0fd8685ff746784b02ed14aa35629d562c7117cde4a701570551faa5a5e1b7ef1eb5c3bcd4cc1fdb8923fcf14e

如何生成与校验 HMAC

1. 1

   选择算法

   选 HMAC-SHA256（默认值，也几乎适用于所有 webhook、API 和 JWT），或切到 SHA-1、SHA-384、SHA-512 以匹配某个要求它的系统。这四种都通过 Web Crypto API 在你的浏览器中原生运行。

2. 2

   输入密钥并设置其编码

   键入或粘贴你的密钥，然后把「密钥编码」设为与服务器解释方式一致：普通字符串用 Text（UTF-8），十六进制数据用 Hex，base64 密钥用 Base64。设错这一项是 HMAC 不匹配的头号原因，拿不准时三种都试一遍。

3. 3

   输入消息

   粘贴你想签名的确切字节 —— 对 webhook 而言就是逐字节的原始请求体，不做任何重新序列化或空白改动。HMAC 会随你的编辑实时重算，不会向任何服务器发送数据。

4. 4

   选择输出格式并复制

   选择 Hex（GitHub 风格）、Base64（Stripe/AWS 风格）或 Base64URL（JWT 风格）以匹配你的集成所需，然后点击「复制」获取签名。

5. 5

   校验已有签名

   切到「校验」标签页，粘贴来自请求头或令牌的「预期 HMAC」，工具会以常量时间确认你计算的签名是否匹配 —— 这样你就能在对载荷采取行动前先认证它。

常见 HMAC 错误

// Server stored a base64 secret but you sign the literal string
createHmac('sha256', 'c2VjcmV0LWtleQ==').update(msg)

// Decode the base64 secret to raw bytes first
createHmac('sha256', Buffer.from('c2VjcmV0LWtleQ==', 'base64')).update(msg)

// Provider sends base64, you compare hex
expected = 'Cd2f7z...=' // base64
actual   = digest('hex') // hex — never matches

// Produce the same encoding the provider uses
actual = digest('base64')

// Re-serialization changes the bytes
body = JSON.stringify(JSON.parse(rawBody))
verify(hmac(body))

// Sign the raw bytes exactly as received
verify(hmac(rawBody))

if (received === computed) { /* trust */ }

if (crypto.timingSafeEqual(receivedBuf, computedBuf)) { /* trust */ }

HMAC 用于什么

校验 webhook 签名

GitHub、Stripe、Slack、Twilio 等服务商会用只与你共享的密钥对请求体做 HMAC 来签每个 webhook。重算标签并与请求头（例如 X-Hub-Signature-256）比较，在采取行动前确认事件是真实的。用「校验」标签页即可完成，无需写一次性代码。

为 API 请求签名

经过认证的 API 常要求客户端用共享密钥对请求（方法、路径、时间戳、请求体）做 HMAC 签名，而不是直接发送密钥本身。AWS Signature Version 4 是典型例子。本工具让你逐步复现并调试这些签名。

保证消息完整性

当你在服务之间传递令牌、cookie 或消息时，附上一个 HMAC 能让接收方检测出任何篡改。由于标签依赖于密钥，攻击者在修改数据后无法重算它 —— 这与普通校验和不同。

理解 JWT HS256 签名

用 HS256 签名的 JWT 就是 base64url(header) + '.' + base64url(payload)，用 HMAC-SHA256 签名并把结果以 Base64URL 输出。把算法设为 SHA-256、输出设为 Base64URL，就能看到该签名究竟是如何产生的，再到 JWT 编码器中交叉核对。

调试对不上的签名

当你的 HMAC 与服务器对不上时，本工具是定位原因的最快途径：把密钥分别当作 Text、Hex、Base64 试，把输出在 Hex 和 Base64 之间切换，并确认你签的是确切的原始字节 —— 全程无需重新部署任何代码。

HMAC 工作原理

RFC 2104 结构

HMAC 定义为 H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ m))，其中 ipad 是重复的字节 0x36，opad 是重复的 0x5c，两者都补到哈希的块大小。长于块大小的密钥会先被哈希；短于块大小的密钥则用零填充。正是这种两遍嵌套赋予 HMAC 其安全性证明，即便底层哈希不抗碰撞，该证明依然成立。

为何带密钥的哈希胜过普通哈希

普通哈希只能证明数据未被意外损坏，因为任何人都能为任意消息（包括被篡改的）重算它。HMAC 混入了一个密钥，因此只有密钥持有者才能产生有效标签。这把「仅完整性」转变为「完整性加真实性」，而这正是 webhook 和签名请求真正需要的性质。

抵抗长度扩展

裸 SHA-1、SHA-256 和 SHA-512 是 Merkle–Damgård 哈希，易受长度扩展攻击：给定 H(secret ‖ msg)，攻击者无需知道密钥即可计算 H(secret ‖ msg ‖ extra)。朴素的「密钥前缀 MAC」方案因此被攻破。HMAC 的外层哈希中和了该攻击，这是用 HMAC 而非把密钥和消息哈希到一起的主要原因。

在 SHA-256 与 SHA-512 之间选择

HMAC-SHA256 产生 256 位（64 个 hex 字符）标签，是互操作的默认值 —— 快速、普及、处处支持。HMAC-SHA512 产生 512 位（128 个 hex 字符）标签，在 64 位 CPU 上往往更快，因为 SHA-512 用 64 位字。除非规范或对端系统要求 SHA-512，否则选 SHA-256；两者用于认证都安全。

Web Crypto 实现

本工具调用 crypto.subtle.importKey 加载你的密钥（从 Text、Hex 或 Base64 解码），并用 crypto.subtle.sign('HMAC', ...) 计算标签，再把原始字节编码为 Hex、Base64 或 Base64URL。这与浏览器用于 TLS 的是同一套原生、经审计的实现，运行在 JavaScript 引擎之外以求速度。

HMAC 最佳实践

密钥长度至少等于哈希输出

HMAC-SHA256 至少用 32 个随机字节（256 位）的密钥；SHA-512 用 64 个。短密钥或低熵密钥是最薄弱的环节。请从密码学安全的随机源生成密钥 —— 绝不要用口令或可预测的字符串。

始终以常量时间比较标签

用常量时间比较来校验签名（Node 用 crypto.timingSafeEqual，Python 用 hmac.compare_digest），而不是 == 或字符串相等。朴素比较会在第一个不同字节处提前返回，泄露的时序可能让攻击者逐字节恢复出有效标签。本工具的「校验」标签页已采用常量时间比较。

切勿记录或暴露密钥

把签名密钥挡在日志、错误信息、URL 和客户端代码之外。将其存放在密钥管理器或环境变量中，定期轮换，并让每个集成各用一把密钥，这样一次泄露不至于殃及全部。

优先选 HMAC-SHA256 或更强算法

默认用 HMAC-SHA256；当对端要求时升到 SHA-384 或 SHA-512。新系统避免用 HMAC-SHA1，绝不要用 HMAC-MD5。尽管 HMAC 比裸签名更能容忍弱哈希，从现代哈希起步能给你最大的安全余量。

对确切字节（含时间戳）签名

对原始、未修改的载荷签名 —— 重新序列化 JSON 或修剪空白会改变字节并破坏校验。对请求签名时，把时间戳或 nonce 纳入被签数据，并拒绝过期签名以防重放攻击。

HMAC 常见问题