HMAC 生成器

HMAC 的工作原理

HMAC（基於雜湊的訊息認證碼，RFC 2104）把密碼學雜湊函式與金鑰結合在一起。只有知道金鑰的人才能為某條訊息算出正確的值，所以 HMAC 一致同時說明兩件事：訊息沒有被改動，並且來自持有金鑰的一方。

它的結構是 H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ message))。金鑰如果比雜湊函式的分組更長（MD5、SHA-1 和 SHA-256 為 64 位元組，SHA-384 和 SHA-512 為 128 位元組），會先被雜湊一次，再用零填充到分組長度；然後與 ipad（重複的 0x36）異或，和訊息一起計算內層雜湊，再與 opad（重複的 0x5c）異或，和內層結果一起計算外層雜湊。簡單拼接的 SHA-256(key ‖ message) 沒有外層雜湊，任何人看到一個標籤後，都能在訊息末尾追加資料，並在不知道金鑰的情況下算出新的有效標籤，這就是長度擴充套件攻擊。

HMAC 的輸出長度與底層雜湊相同，HMAC-SHA256 為 32 位元組，即 64 個十六進位字元。RFC 2104 建議金鑰不短於這個長度，可以用隨機 Base64 生成器生成合適的金鑰。

HMAC 簽名的常見用途

• GitHub Webhook。X-Hub-Signature-256 請求頭的值是 sha256= 加上原始請求體的 HMAC-SHA256（十六進位），金鑰為 Webhook 金鑰。可以把整個請求頭的值貼上到「對比」框中，sha256= 字首會被自動忽略。
• Stripe Webhook。Stripe-Signature 請求頭包含時間戳 t 和簽名 v1。簽名是對「時間戳、點號和原始請求體」計算的十六進位 HMAC-SHA256，金鑰是按文字使用的端點金鑰（whsec_...）。
• Shopify Webhook。X-Shopify-Hmac-Sha256 中是原始請求體 HMAC-SHA256 的 Base64 形式，金鑰為應用的客戶端金鑰（client secret）。可以選擇 Base64 輸出，或直接把請求頭的值貼上到「對比」框中。
• AWS 簽名版本 4。簽名金鑰通過鏈式 HMAC-SHA256 派生：先以 AWS4 加秘密訪問金鑰為金鑰對日期計算 HMAC，再依次對區域、服務和 aws4_request 計算，每一步都以上一步的結果為金鑰。把金鑰格式設為十六進位，就能把上一步的輸出直接用作下一步的金鑰。
• JSON Web Token。HS256、HS384 和 HS512 就是對「編碼後的頭部、點號和編碼後的載荷」計算的 HMAC-SHA256、-384 和 -512。權杖的第三段是這個 HMAC 的 URL 安全 Base64 形式，可以原樣貼上到「對比」框中。完整的權杖可以用 JWT 解碼工具驗證。

務必基於收到的原始請求體計算 HMAC，不要做任何改動。把 JSON 解析後再重新序列化，會改變空格或鍵的順序；哪怕只多了一個換行符，HMAC 也會完全不同。

在程式碼中計算 HMAC

# Python
import hmac, hashlib
sig = hmac.new(b'key', b'message', hashlib.sha256).hexdigest()
hmac.compare_digest(sig, received)        # 恆定時間比較

// Node.js
const crypto = require('crypto');
const sig = crypto.createHmac('sha256', 'key').update('message').digest('hex');
// 長度不同時 timingSafeEqual 會丟擲異常，請先檢查長度
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(received));

// PHP：訊息在前，金鑰在後
$sig = hash_hmac('sha256', 'message', 'key');
hash_equals($sig, $received);

# OpenSSL：文字金鑰，以及以十六進位給出的同一金鑰
printf '%s' 'message' | openssl dgst -sha256 -hmac 'key'
printf '%s' 'message' | openssl dgst -sha256 -mac HMAC -macopt hexkey:6b6579

# 測試向量：金鑰 "key"，訊息 "The quick brown fox jumps over the lazy dog"
# HMAC-SHA256 = f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8

在自己的程式碼中校驗簽名時，請使用上面這類恆定時間比較函式。普通的 == 遇到第一個不同的字元就會返回，攻擊者可以利用這種時間差逐位元組試出有效簽名。對於 Stripe 這類帶時間戳的方案，還應拒絕時間戳距今已超過幾分鐘的請求，以防重放攻擊。