如何在 Python、Node.js 與 Go 產生與驗證 HMAC 簽章
學習如何在 Python、Node.js 與 Go 產生與驗證 HMAC 簽章。透過實用範例、程式片段與免費線上工具強化 API 安全。
API 與 webhook 高度仰賴 HMAC（Hash-based Message Authentication Code），確保你接收到的每個請求都真實且未被竄改。
若沒有簽章驗證，應用程式可能遭受偽造、資料篡改或重播攻擊。
在本指南中，你會學到：
- 什麼是 HMAC 簽章，以及它如何運作
- 如何在 Python、Node.js、Go 中產生與驗證 HMAC 簽章
- 開發者常見錯誤與修正方式
- 如何使用免費線上工具測試 HMAC：Authgear 的 HMAC Signature Generator & Verifier
什麼是 HMAC 簽章？
HMAC（Hash-based Message Authentication Code）是一種訊息驗證碼，將密碼學雜湊函式（如 SHA256）與密鑰結合而成。
它能確保兩件關鍵事項：
- 完整性： 訊息在傳輸中未被修改。
- 真實性： 訊息來自知道密鑰的可信來源。
其概念公式很簡單：
HMAC = hash(secret_key + message)
發送端與接收端使用同一把密鑰。若雙方計算結果一致，訊息即為有效。
為何 API 要使用 HMAC？
當 API 接收請求（例如 POST /payment）時，你必須確認請求來自可信 client。
透過 HMAC 簽章，只有持有正確密鑰的發送方能產生有效簽章。
典型流程：
- Client 對 request body 計算 HMAC。
- 在標頭附上
X-Signature: <hmac_value>發送請求。 - Server 重新計算 HMAC 並比較兩者。
- 相符則信任並處理請求。
Stripe、Shopify、GitHub、AWS、Slack 等大型平台都用 HMAC 來驗證 webhook 與安全請求簽章。
HMAC 逐步運作方式
- 組合密鑰與訊息。
- 以密碼學演算法（例如 SHA256）做雜湊。
- 比對雙方簽章以確認真實性。
- 選擇合適演算法：
- HMAC-SHA256（多數情境建議）
- HMAC-SHA1（舊系統相容）
- HMAC-SHA512（高安全需求）
在 Python 中產生與驗證 HMAC
Python 的 hmac 與 hashlib 函式庫讓 HMAC 生成很直覺。
驗證時務必使用 compare_digest()，可避免 timing attack。你可以用 Authgear 免費 HMAC Signature Generator & Verifier 嘗試自己的訊息與簽章。
在 Node.js 中產生與驗證 HMAC
Node 內建 crypto 函式庫提供相同能力。
timingSafeEqual 可避免時間側信道造成比較洩漏。
在 Go 中產生與驗證 HMAC
Go 的 crypto/hmac 套件提供簡潔介面，可用於 HMAC 產生與驗證。
實務範例：簽章 API 請求
以下示範 HMAC 簽章如何用於 API 請求驗證。
Client（Sender）：
Server（Receiver）：
這可確保只有授權發送方能提交有效請求。
常見錯誤與修正方式
| 問題 | 可能原因 | 解法 |
|---|---|---|
| HMAC 簽章無效 | 編碼不一致（UTF-8 vs ASCII） | 確認 client 與 server 都一致使用 UTF-8 編碼。 |
| 簽章不一致 | 雙方使用不同演算法 | 確認兩端使用相同演算法，例如 HMAC-SHA256。 |
| Timing attack 風險 | 以 == 比較字串 |
務必使用安全比較函式，如 compare_digest() 或 timingSafeEqual()。 |
| 輸出不符合預期 | 摘要格式不一致（hex vs base64） | 統一格式並一致使用 .hexdigest() 或 .base64encode()。 |
如何選擇合適雜湊演算法
| 演算法 | 安全等級 | 效能 | 建議用途 |
|---|---|---|---|
| SHA-1 | 弱 / 舊版 | 非常快 | 僅用於舊系統相容性需求。 |
| SHA-256 | 強 | 平衡 | API 簽章與 webhook 驗證的預設首選。 |
| SHA-512 | 非常強 | 稍慢 | 適合高安全或大型 payload 場景。 |
線上測試你的 HMAC
你可使用 Authgear 免費線上工具立即產生與驗證 HMAC： HMAC Signature Generator & Verifier
工具支援：
- 演算法：SHA-1、SHA-256、SHA-512
- Generate 與 Verify 模式
- 一鍵複製輸出
- 即時 hex 輸出
它很適合快速測試請求簽章，或除錯 API key 導致的簽章不一致問題。
常見問題
HMAC 使用哪種演算法？
HMAC 可使用 SHA256、SHA1、SHA512。對 API 來說，SHA256 最常用，兼顧安全與廣泛支援。
HMAC 可以用來做 API 驗證嗎？
可以。Stripe、AWS、GitHub 等平台都用 HMAC 簽 API 請求與 webhook。
HMAC 與一般 hashing 差在哪？
Hashing 只能保證資料完整性；HMAC 因加入共享密鑰，可同時保證完整性與真實性。
HMAC 和 JWT 一樣嗎？
不一樣。JWT 可能使用 HMAC 演算法（如 HS256），但 JWT 還包含無狀態驗證所需 payload。
有哪些工具可線上測試 HMAC？
Authgear 提供免費 HMAC Signature Generator & Verifier，也有 JWK Generator、JWT Decoder 與完整 Authgear Developer Toolkit。