HMAC 產生器 API 替代方案是一種工具，可在不發出 HTTP 請求的情況下，產生與遠端 HMAC 端點相同的金鑰雜湊驗證標籤。HMAC 產生器工具在當前分頁中執行 Web Crypto，並以小寫十六進制與標準帶填補字元的 Base64 形式，完整回傳 HMAC-SHA-256、HMAC-SHA-384 與 HMAC-SHA-512 標籤，逐位元組與 API 在給定相同金鑰與訊息時所回傳的結果完全一致。開發人員選擇此替代方案，以便從第三方服務移除 API 金鑰、在測試期間消除速率限制、離線作業，或在不必信任遠端來回往返的情況下，驗證廠商的 HMAC 回應。由於 Web Crypto 不會傳輸輸入內容，因此秘密絕不會離開瀏覽器分頁。其權衡之處在於，您必須自行提供精確的金鑰位元組與訊息位元組;產生器無法讀取您應用程式的環境變數，也無法從遠端秘密儲存處擷取。
為什麼開發人員選擇 HMAC 產生器 API 替代方案
大多數公開的 HMAC 端點會接受訊息與金鑰，然後回傳十六進制或 Base64 摘要。乍看之下相當便利，但每次呼叫都會增加摩擦，並在整個開發工作流程中累積:
- 速率限制會限制您在負載測試或回填遷移期間可計算的標籤數量。
- 網路延遲會將 50 微秒的 HMAC 轉變為 200 毫秒的來回往返，在需要對數千個 webhook 酬載進行簽署的緊密迴圈中影響重大。
- 一旦您的本機腳本依賴他人的正常運作時間、TLS 憑證與定價層級，廠商鎖定效應隨即出現。
- 當外部服務在每次請求中都能看到您的金鑰時(即使透過 TLS)，秘密處理規則會變得模糊。
- 隔離網路環境、嚴格限制的 CI 執行器與離線筆電，根本無法連線至遠端端點。
瀏覽器端的 HMAC 產生器迴避了上述全部五項問題。它透過 W3C Web Cryptography API 執行，因此位元組從不經過網路傳輸，並回傳與伺服器端點原本會產生的相同完整標籤。其結果是相同的驗證原語，在本機產生，沒有速率計數器，也沒有遠端信任假設。
本機 HMAC 替代方案實際必須產生什麼
只有在替代方案能產生逐位元組相同的輸出時，取代 API 才是安全的。以下四項需求區分了真正的替代方案與玩具:
| 需求 | API 端點 | 瀏覽器 HMAC 產生器 |
|---|---|---|
| 標籤演算法 | 伺服器端選擇 | 在本機選擇 SHA-256、SHA-384 或 SHA-512 |
| 金鑰編碼 | 通常僅限 UTF-8 | UTF-8 或精確的十六進制位元組，逐欄位選擇 |
| 訊息編碼 | 通常僅限 UTF-8 | UTF-8 或精確的十六進制位元組，逐欄位選擇 |
| 輸出編碼 | 通常為十六進制或 Base64 | 完整小寫十六進制加上帶填補字元的 Base64 |
| 符合性證明 | 實作聲明 | 已驗證八個 RFC 4231 測試向量 |
| 網路需求 | 是 | 頁面載入後即不需要 |
符合性這一列是多數團隊最容易忽略的部分。RFC 4231 提供了針對短金鑰、重複位元組金鑰、短於摘要大小的金鑰，以及跨越雜湊區塊邊界之訊息的確定性向量。HMAC 產生器會檢查全部八種情況，因此通過的標籤會與權威性的伺服器端實作應產生的結果相符。向量來源記錄於 RFC 4231，而演算法定義則記錄於 NIST FIPS 198-1。
在瀏覽器中本機產生 HMAC 標籤
- 開啟 HMAC 產生器，並確認您正在實作的協定預期的是不帶演算法前綴或封包的完整 HMAC 標籤。
- 選擇 SHA-256 可產生 32 位元組標籤，選擇 SHA-384 可產生 48 位元組標籤，或選擇 SHA-512 可產生 64 位元組標籤。若協定按名稱引用特定雜湊，則此選擇為強制性。
- 當您的金鑰為可列印文字或符號時，將金鑰編碼設為 UTF-8;當金鑰為二進位、以十六進制常數發布，或儲存於硬體安全模組匯出檔時，則設為十六進制。
- 以同樣方式設定訊息編碼。UTF-8 涵蓋帶腔調字母、CJK 字元與表情符號;十六進制則涵蓋來自封包擷取、二進位協定欄位或正式請求字串的原始位元組。
- 貼上精確的金鑰位元組與訊息位元組，且不額外加入空格、換行、0x 前綴或冒號。十六進制模式會拒絕奇數長度的輸入，因此意外的格式字元無法在無聲中變更位元組。
- 產生標籤，並複製接收端所預期的十六進制字串或帶填補字元的 Base64 字串。
- 若協定強制規定截斷、Base64url 或演算法識別碼前綴，請在工具外部明確套用這些轉換。切勿憑目視修剪標籤。
每個解碼欄位上限為 1,000,000 位元組，因此超過該大小的輸入不會被此頁面接受。只要位元組正確，您即可將腳本中的任何 HMAC API 呼叫替換為對本機產生之標籤的呼叫，前提是您以相同編碼保留相同的金鑰，並以相同順序使用相同的雜湊。
雜湊選擇與標籤長度
| 雜湊 | 區塊大小(位元組) | 標籤大小(位元組) | 十六進制字元數 | 典型用途 |
|---|---|---|---|---|
| SHA-256 | 64 | 32 | 64 | 大多數 webhook、JWT HS256、通用請求簽署 |
| SHA-384 | 128 | 48 | 96 | 高保證變體、TLS 1.2 PRF 輸出 |
| SHA-512 | 128 | 64 | 128 | 長期有效簽章、高吞吐量簽署 |
始終顯示完整標籤。要求較短輸出的協定應明確指定截斷規則。常見模式為「最左側 N 個位元組」，但精確的 N 與編碼必須來自主管規格，而非憑外觀猜測。
金鑰與訊息的編碼
逐位元組一致性是整個遊戲的核心。兩種編碼看似相似，卻會產生不同的 HMAC 標籤:
- UTF-8 將文字視為 Unicode 碼點，每個字元輸出一到四個位元組。字串 "café" 會成為 c、a、f 各一個位元組，以及 é 的兩個位元組。表情符號 🙂 會成為四個位元組。
- 十六進制將輸入視為以每個位元組兩個十六進制數字表示的原始位元組。"cafe" 是位元組 0xCA 0xFE;UTF-8 字母 c、a、f、e 則會是位元組 0x63 0x61 0x66 0x65，必須輸入為 "63616665"。
編碼不符是本機計算的 HMAC 無法與 API 回應相符的最常見單一原因。若您的參考系統以 ASCII 字串 "secretkey" 傳送金鑰，但您貼上位元組 0x73 0x65 0x63 0x72 0x65 0x74 0x6B 0x65 0x79，則標籤將會一致。若您在 API 將同一字串解讀為 ASCII 的同時貼上十六進制數字 "7365637265746B6579"，則標籤仍會一致，因為兩者產生相同的位元組。其陷阱在於透過接收端從未看過的編碼進行轉換，例如對百分號進行 URL 編碼，或剝除協定所依賴的結尾換行字元。十六進制模式會拒絕奇數半位元組、前綴與零散標點，因此意外的格式字元無法悄然移動位元組。
如需深入瞭解如何使用已知秘密產生精確標籤，HMAC-SHA256 標籤指南 以僅使用標準瀏覽器工具的方式逐步演練一個實作範例。
十六進制、Base64 與 Base64url 不可互換
HMAC 產生器以兩種形式回傳相同標籤:小寫十六進制，以及使用 + 與 / 字元並帶 = 填補的標準 Base64。然而，部分協定要求其他形式:
- JWT 簽章使用 Base64url，其將 + 替換為 -、將 / 替換為 _，並去除 = 填補。位元組相同，但字串不同。
- 部分 webhook 提供者僅需要摘要本身，並以 "sha256=" 等演算法識別碼作為前綴。
- 部分雲端簽署機制會在傳輸前將訊息與標籤串接為二進位封包。
當上述任一規則適用時，請在產生器外部執行該轉換。該工具的契約是輸出正式完整的標籤;周邊的協定負責線路格式。對於已在其他處使用 Base64 至文字編碼的比較流程，類似 Base64 編碼 / 解碼 工具的輔助程式可在不混淆兩組位元組的情況下，驗證接收端的解讀方式。
金鑰處理與 HMAC 未提供的功能
HMAC 標籤會向持有相同秘密的一方驗證精確的訊息位元組。它不會加密訊息、無法證明訊息的機密性，也無法防範金鑰遭洩露。以下若干運作規則可維持驗證保證的誠實性:
- 使用為該雜湊量身打造的密碼學安全隨機來源來產生金鑰。人類設定的密碼不會自動成為強效的 HMAC 金鑰;若必須將密碼轉為金鑰，請將其通過應用程式所強制要求的密碼型金鑰衍生函式。
- 透過受保護的管道分發秘密、依用途區分金鑰，並在任何疑似遭到洩露後予以輪替。
- 在伺服器上以固定時間比較函式比對標籤。許多語言中逐位元組的字串相等比較會因時間差異而洩漏資訊。
- 避免在不受信任的裝置上，將生產環境的秘密貼入瀏覽器。瀏覽器會在分頁存續期間將金鑰保留於記憶體中，且不會上傳，但裝置、螢幕與剪貼簿仍屬於信任邊界的一部分。
標籤成功相符，僅能證明雙方共用該金鑰並處理了相同的位元組。它無法證明訊息屬於私密、無法證明寄送者除持有金鑰外可被識別，也無法證明除金鑰持有人外的任何一方撰寫了該訊息。請將 HMAC 視為更廣泛協定中的一層，該協定可能同時要求加密、重送保護與已驗證的傳輸。
從遠端 HMAC API 切換至 HMAC 產生器，可移除網路相依性，卻不會改變密碼學契約。接收端不在乎寄送端使用的是託管 API、伺服器端程式庫，還是瀏覽器分頁;它只在乎位元組是否相符。
若您正在權衡選項，XOR 加密 API 替代方案:瀏覽器端重複金鑰 對此有詳細說明。