與實戰(zhàn))
CPythonhmac模塊完全指南RFC 2104 密鑰哈希消息認證碼的實現(xiàn)與實戰(zhàn)【免費下載鏈接】cpythonThe Python programming language項目地址: https://gitcode.com/GitHub_Trending/cp/cpythonhmac是 Python 標準庫中實現(xiàn) HMACKeyed-Hashing for Message Authentication密鑰哈希消息認證的模塊其算法依據(jù) RFC 2104同時兼容 RFC 4231在 API 消息簽名、請求鑒權、數(shù)據(jù)完整性校驗、Webhook 驗簽等場景中扮演核心角色。通過閱讀本文你將掌握hmac.new、hmac.digest、HMAC對象各方法與屬性以及常量時間比較函數(shù)compare_digest的正確用法并能結合 CPython 源碼理解其 OpenSSL/HACL* 加速路徑與純 Python 回退實現(xiàn)的分層設計。本文完全基于當前 CPython 倉庫中的 Lib/hmac.py、Modules/_hashopenssl.c、Modules/hmacmodule.c 與其配套測試 Lib/test/test_hmac.py 展開。HMAC 是什么算法標準、適用前提與關鍵限制HMAC 在標準哈希函數(shù)如 MD5、SHA-1、SHA-256 等之上引入一個共享密鑰secret key只有同時掌握密鑰與消息的雙方才能計算并核對出相同的認證碼因此它可以同時提供消息完整性與來源認證能力。RFC 2104 定義的 HMAC 構造可概括為HMAC(K, m) H((K ⊕ opad) ∥ H((K ⊕ ipad) ∥ m))其中K是經(jīng)過處理的密鑰若密鑰長度超過哈希分組塊大小則先對其做一次哈希壓縮ipad 0x36、opad 0x5C為兩個不同的填充常量H為底層哈希函數(shù)∥表示字節(jié)拼接。在 Lib/hmac.py 頂部可以直觀看到這兩個常量正是以全表平移的形式實現(xiàn)的trans_5C bytes((x ^ 0x5C) for x in range(256)) trans_36 bytes((x ^ 0x36) for x in range(256))該模塊允許使用任意具有固定摘要長度的哈希函數(shù)但有一個顯著限制原文檔與源碼雙重明確擴展輸出函數(shù)XOF如 SHAKE-128 / SHAKE-256 不能用于 HMAC。這一點在 Lib/hmac.py 的_is_shake_constructor()中顯式檢測shake/SHAKE前綴并拋出ValueError(unsupported hash algorithm ...)相關行為同樣被測試文件 Lib/test/test_hmac.py 中以test_hmac_new_xof_digestmod命名的用例覆蓋。此外本模塊與提供安全哈希函數(shù)的模塊hashlib是天然搭檔——digestmod參數(shù)接受的摘要名稱須是hashlib.new()能識別的算法名詳見 Doc/library/hashlib.rst。核心 API 一覽原文檔定義的模塊級入口函數(shù)與HMAC類方法/屬性可按如下表格速覽詳細用法見后文各節(jié)API類型說明引入/變更版本hmac.new(key, msgNone, digestmod)函數(shù)返回新的HMAC對象digestmod必填3.8 起digestmod必填hmac.digest(key, msg, digest)函數(shù)單發(fā)計算摘要等價于HMAC(key, msg, digest).digest()但走優(yōu)化實現(xiàn)更快3.7 新增HMAC.update(msg)方法增量喂入消息數(shù)據(jù)可多次調用3.4 起支持任意hashlib兼容類型HMAC.digest()方法返回原始字節(jié)摘要長度等于digest_size可能含 NUL 等非 ASCII 字節(jié)—HMAC.hexdigest()方法返回兩倍長度的十六進制字符串—HMAC.copy()方法克隆對象用于高效計算共享相同前綴的多個摘要—HMAC.digest_size屬性結果摘要字節(jié)數(shù)—HMAC.block_size屬性底層哈希算法的內部塊大小字節(jié)3.4 新增HMAC.name屬性規(guī)范名稱恒為小寫如hmac-md53.4 新增hmac.compare_digest(a, b)函數(shù)抗時序分析常量時間的相等比較3.3 新增需要注意從 3.10 開始未文檔化的HMAC.digest_cons、HMAC.inner、HMAC.outer屬性已被移除見原文檔 versionchanged 說明并且HMAC對象在 Lib/hmac.py 中通過__slots__約束為僅有_hmac、_inner、_outer、block_size、digest_size五個槽位?？焖偕鲜窒⒑灻c驗簽創(chuàng)建 HMAC 對象hmac.new()hmac.new(key, msgNone, digestmod)的三個參數(shù)中keybytes 或 bytearray 類型的密鑰3.4 起支持傳其他類型會拋TypeErrormsg可選的初始輸入。若提供等價于隨后自動調用一次update(msg)digestmod必填3.8 起強制可以是三類取值中的任一種適合傳給hashlib.new()的算法名字符串如sha256哈希構造器如hashlib.sha256遵循 PEP 247 的模塊或哈希對象。由于digestmod位置在可選的msg之后當你不傳msg時請務必用關鍵字參數(shù)傳入以避免歧義。這一點在源碼 docstring 與構造器實現(xiàn)中都有強調例如 Lib/hmac.py 在digestmod為空時會拋出TypeError(Missing required argument digestmod.)。一個完整的“簽名 驗簽”示例import hashlib import hmac # 雙方共享的密鑰實際系統(tǒng)中應從密鑰管理服務獲取 secret bshared-secret-key # 發(fā)送方對消息簽名 def sign(message: bytes, key: bytes) - str: return hmac.new(key, message, hashlib.sha256).hexdigest() # 接收方計算期望簽名并做常量時間比對 def verify(message: bytes, expected: str, key: bytes) - bool: computed sign(message, key) return hmac.compare_digest(computed, expected) sig sign(bamount100toalice, secret) print(sig) assert verify(bamount100toalice, sig, secret) # 消息被篡改時驗簽失敗 assert not verify(bamount99999toalice, sig, secret)單發(fā)計算hmac.digest()如果你的消息已經(jīng)完整地放在內存里用hmac.digest(key, msg, digest)比先new()再digest()更快——它在底層使用優(yōu)化的 C/內聯(lián)實現(xiàn)而非逐塊推進狀態(tài)機import hmac # 用法一digest 傳算法名字符串走 C 加速路徑 raw hmac.digest(bkey, bmessage, sha256) # 用法二digest 傳哈希構造器 raw2 hmac.digest(bkey, bmessage, hashlib.sha256) assert raw raw2CPython 實現(xiàn)細節(jié)原文檔明確指出只有當digest是字符串且該算法受 OpenSSL 支持時才會使用優(yōu)化的 C 實現(xiàn)調用 Modules/_hashopenssl.c 暴露的_hashlib.hmac_digest若密鑰超過 OpenSSLHMAC的INT_MAX大小限制拋OverflowError或算法不被 OpenSSL 支持則按 Lib/hmac.py 的邏輯繼續(xù)嘗試_hmacHACL* 實現(xiàn)乃至純 Python 回退。HMAC 對象的方法與屬性詳解update(msg)增量喂入數(shù)據(jù)update(msg)可被重復調用其效果等價于將所有參數(shù)拼接后一次調用即m.update(a); m.update(b)與m.update(a b)完全等價。這在處理流式數(shù)據(jù)如分塊讀取大文件后計算校驗碼時非常有用無需在內存中拼接完整消息。msg可以是任意受hashlib支持的類型3.4 起。digest()與hexdigest()輸出形態(tài)digest()返回原始 bytes長度為構造時所用摘要算法的digest_size可能包含 NUL 等非 ASCII 字節(jié)不適合直接放進文本協(xié)議hexdigest()返回長度兩倍、僅含十六進制字符的字符串適合在電子郵件、HTTP header、URL 等非二進制環(huán)境中安全交換摘要。安全性警示原文檔 warning在驗證例程中把digest()或hexdigest()的輸出與外部提供的摘要比較時務必使用hmac.compare_digest()而非運算符以降低時序攻擊風險詳見下文專節(jié)。copy()克隆 HMAC 對象copy()返回當前對象的一個“克隆體”此后對克隆體的update不會影響原對象。這一能力可高效計算共享同一初始子串的多條消息摘要先統(tǒng)一update公共前綴再復制出多個分支分別喂入不同后綴。h hmac.new(bkey, bheader:, hashlib.sha256) h1 h.copy(); h1.update(bpayload-A) # 只算 header:payload-A h2 h.copy(); h2.update(bpayload-B) # 只算 header:payload-B在 Lib/hmac.py 的實現(xiàn)中copy()直接通過__new__繞過昂貴的__init__對 C 加速路徑調用self._hmac.copy()對純 Python 路徑則分別復制_inner與_outer因此成本很低。對象屬性digest_size、block_size、name屬性含義示例值digest_size結果 HMAC 摘要的字節(jié)數(shù)sha256 為 32sha512 為 64block_size底層哈希算法的內部塊大小字節(jié)sha256 為 64sha384/sha512 為 128name本 HMAC 的規(guī)范名稱恒為小寫hmac-sha256、hmac-md5block_size與name自 3.4 起提供。需要特別指出的是 Lib/hmac.py 中模塊級存在一個占位digest_size None其注釋明確告誡HMAC 返回摘要的大小取決于底層哈希模塊應使用對象實例的digest_size屬性而不是模塊級的這個占位值。name屬性為只讀 property在 C 加速路徑直接透傳底層對象名稱在純 Python 路徑則拼為fhmac-{self._inner.name}見 Lib/hmac.py。compare_digest()抵御時序攻擊的常量時間比較驗簽環(huán)節(jié)最容易被忽視的漏洞是時序側信道普通比較在遇到第一個不同字節(jié)時會短路返回攻擊者可通過測量響應耗時逐字節(jié)猜出合法摘要。hmac.compare_digest(a, b)通過避免基于內容的短路行為來抵御時序分析適合用于密碼學場景。用法約束a、b必須為同類型要么都是str僅限純 ASCII例如hexdigest()的輸出要么都是 bytes-like 對象類型不同如 str 與 bytes 混用、非 ASCII 字符串等都會拋出TypeError。import hmac hmac.compare_digest(abc123, abc123) # Truehexdigest 場景 hmac.compare_digest(b\x00\xff, b\x00\xff) # Truedigest 場景注意原文檔中的note若a與b長度不同或發(fā)生錯誤理論上時序仍可能泄露兩者的類型與長度信息——但絕不會泄露它們的值。這也是為什么實踐中常約定固定長度的摘要格式或先比較長度再比較內容。實現(xiàn)層面3.10 起該函數(shù)在可用時內部使用 OpenSSL 的CRYPTO_memcmp()。搜索 Modules/_hashopenssl.c 可以看到result | CRYPTO_memcmp(left, right, length);的累加式比對正是“無論在哪一位不同都不提前退出”的常量時間寫法在無 OpenSSL 環(huán)境下則回退到_operator._compare_digest見 Lib/hmac.py 的導入分支。測試用例 Lib/test/test_hmac.py 系統(tǒng)性地覆蓋了非法輸入類型、str/bytes/bytearray 混用、以及bytes/str子類——即使子類把__eq__重寫成拋異常compare_digest也絕不會調用它。源碼級實現(xiàn)CPython 的三層加速架構hmac并不是一個“只看 Python 代碼”的純腳本模塊。從 Lib/test/test_hmac.py 的模塊注釋可以清晰看到CPython 為其提供了三種實現(xiàn)按優(yōu)先級依次為OpenSSL HMAC使用 OpenSSL 哈希函數(shù)由_hashlib擴展提供Modules/_hashopenssl.c中的_hashlib.hmac_new、_hashlib.hmac_digestHACLHMAC*內置的 C 實現(xiàn)Modules/hmacmodule.c實現(xiàn)_hmac在無 OpenSSL 的構建如 WASI、部分受限平臺上保證仍有余力且可預測的性能與安全屬性通用純 Python HMACLib/hmac.py內的回退實現(xiàn)能對接 OpenSSL/HACL* 的哈希名與構造器、PEP 247 模塊以及任意用戶自定義哈希對象。對象創(chuàng)建時的分派邏輯非常直白見 Lib/hmac.py若_hashopenssl可用且digestmod為字符串或 OpenSSL 內置構造器類型優(yōu)先走_init_openssl_hmac()算法不受 OpenSSL 支持時拋出UnsupportedDigestmodError并繼續(xù)下探否則若_hmac可用且digestmod為字符串走_init_builtin_hmac()未知算法拋UnknownHashError再下探最后落入_init_old()純 Python 路徑。單發(fā)函數(shù)hmac.digest()的分派邏輯類似Lib/hmac.py但多了一層超大密鑰保護OpenSSL 的HMAC將密鑰限制在INT_MAX內HACL* 限制在UINT32_MAX內一旦越界即優(yōu)雅回退到_compute_digest_fallback()而不是讓 C 層崩潰。純 Python 回退路徑_compute_digest_fallback()Lib/hmac.py是理解 RFC 2104 算法細節(jié)的最佳教材其關鍵步驟為blocksize getattr(inner, block_size, 64) if len(key) blocksize: # 密鑰過長則先哈希壓縮 key digest_cons(key).digest() key key.ljust(blocksize, b\0) # 補齊到塊大小 inner.update(key.translate(trans_36)) # ipad 0x36 outer.update(key.translate(trans_5C)) # opad 0x5C inner.update(msg) outer.update(inner.digest()) # 外層再包一層 return outer.digest()值得注意的工程細節(jié)若底層哈希對象缺少block_size屬性或塊大小小于 16_init_old()會發(fā)出RuntimeWarning并回退到類默認的 64 字節(jié)塊Lib/hmac.py類屬性blocksize 64的注釋說明它代表“默認塊大小”允許子類重寫。實戰(zhàn)典型應用場景場景一Webhook / 開放 API 的請求簽名服務端與調用方預共享密鑰調用方對規(guī)范化后的請求參數(shù)按固定順序拼接后計算 HMAC放入X-Signature頭服務端用compare_digest校驗可同時防篡改與防偽造def make_signature(payload: str, timestamp: str, secret: bytes) - str: # 規(guī)范化待簽字符串務必與服務端完全一致 message f{timestamp}.{payload}.encode() return hmac.new(secret, message, sha256).hexdigest() def check_signature(payload: str, timestamp: str, secret: bytes, sig: str) - bool: if not (isinstance(sig, str) and len(sig) 64): # 先校長度再常量時間比較 return False return hmac.compare_digest(make_signature(payload, timestamp, secret), sig)場景二增量校驗大文件無需將整個文件讀入內存使用update()流式處理兼顧內存與完整性import hmac, hashlib def file_hmac_hex(path: str, secret: bytes, chunk: int 1 20) - str: h hmac.new(secret, digestmodhashlib.sha256) with open(path, rb) as f: while block : f.read(chunk): h.update(block) return h.hexdigest()場景三與標準測試向量對照自檢RFC 4231 的 Test Case 120 字節(jié)0x0b密鑰、消息Hi There對應 sha256 摘要為b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7——該向量可從測試文件 Lib/test/test_hmac.py 中直接讀取MD5/SHA-1 向量取自 RFC 2202SHA-2 取自 RFC 4231SHA-3 取自 NIST。你可以用下面代碼驗證自己的環(huán)境實現(xiàn)import hmac, hashlib got hmac.digest(b\x0b * 20, bHi There, sha256).hex() assert got b0344c61d8db38535ca8afceaf0bf12b \ 881dc200c9833da726e9376c2e32cff7 print(RFC 4231 TC1 OK)邊界情況與常見誤區(qū)1. 密鑰類型與長度key只接受 bytes/bytearray源碼在 Lib/hmac.py 顯式拋TypeError密鑰長度超過底層哈希塊大小如 sha256 的 64 字節(jié)時算法會先對密鑰做一次哈希壓縮再參與計算因此從密碼學角度“過長密鑰”并不會帶來額外安全強度反而應先經(jīng) KDF 處理。2. 算法塊大小對照決定密鑰“過長”的閾值底層算法block_size字節(jié)digest_size字節(jié)MD5 / SHA-1 / SHA-224 / SHA-2566416 / 20 / 28 / 32SHA-384 / SHA-51212848 / 643. 不能用于 XOFSHAKE-128/256 等擴展輸出函數(shù)會觸發(fā)ValueError因為 HMAC 需要固定長度摘要作為中間值與最終輸出對應_is_shake_constructor檢查。4.digestmod必須顯式提供3.8 起缺省會拋TypeError舊的hmac.new(key, msg)兩參調用方式不可再依賴默認 MD5。5. 摘要對比一定用compare_digest無論digest()的二進制輸出還是hexdigest()的十六進制輸出都不要用前者二進制中可能混入 NUL 等字符比較行為易踩坑且存在時序泄露。6. 模塊級hmac.digest_size是None這是源碼中的顯式占位務必從實例讀取真實值。測試體系與進一步閱讀HMAC 的正確性在 CPython 中受到嚴格驗證Lib/test/test_hmac.py 共 1600 余行通過import_fresh_module分別以“屏蔽_hashlib/_hmac”純 Python、“只加載_hmac”HACL*等方式對同一套測試向量跑三份實現(xiàn)并專門設有DigestModTestCaseMixin、HMACCompareDigestTestCase等測試類覆蓋構造缺參、未知算法、超大密鑰bigmemtest、_4G相關用例、digestmod缺失與非法值等異常路徑。若需進一步探究相關主題可繼續(xù)閱讀Lib/hmac.py模塊完整實現(xiàn)與三層分派邏輯Modules/_hashopenssl.cOpenSSL 加速路徑hmac_digest/hmac_new/compare_digestModules/hmacmodule.cHACL* 內置 HMAC 實現(xiàn)Lib/test/test_hmac.pyRFC 2202/4231 與 NIST 測試向量及全部行為測試Doc/library/hashlib.rst底層安全哈希函數(shù)模塊文檔。綜上hmac模塊以極小的 API 面提供了符合 RFC 2104 標準的消息認證能力其正確用法可概括為三句話用new/HMAC做增量計算、用digest做單發(fā)快算、用compare_digest做驗簽比對。在此基礎上理解其 OpenSSL → HACL* → 純 Python 的三級實現(xiàn)能幫助你在部署到無 OpenSSL 的受限平臺時依然對安全性與行為邊界心中有數(shù)?！久赓M下載鏈接】cpythonThe Python programming language項目地址: https://gitcode.com/GitHub_Trending/cp/cpython創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 CPython `hmac` 模塊完全指南：RFC 2104 密鑰哈希消息認證碼的實現(xiàn)與實戰(zhàn)
CPythonhmac模塊完全指南RFC 2104 密鑰哈希消息認證碼的實現(xiàn)與實戰(zhàn)【免費下載鏈接】cpythonThe Python programming language項目地址: https://gitcode.com/GitHub_Trending/cp/cpythonhmac是 Python 標準庫中實現(xiàn) HMACKeyed-Hashing for Message Authentication密鑰哈希消息認證的模塊其算法依據(jù) RFC 2104同時兼容 RFC 4231在 API 消息簽名、請求鑒權、數(shù)據(jù)完整性校驗、Webhook 驗簽等場景中扮演核心角色。通過閱讀本文你將掌握hmac.new、hmac.digest、HMAC對象各方法與屬性以及常量時間比較函數(shù)compare_digest的正確用法并能結合 CPython 源碼理解其 OpenSSL/HACL* 加速路徑與純 Python 回退實現(xiàn)的分層設計。本文完全基于當前 CPython 倉庫中的 Lib/hmac.py、Modules/_hashopenssl.c、Modules/hmacmodule.c 與其配套測試 Lib/test/test_hmac.py 展開。HMAC 是什么算法標準、適用前提與關鍵限制HMAC 在標準哈希函數(shù)如 MD5、SHA-1、SHA-256 等之上引入一個共享密鑰secret key只有同時掌握密鑰與消息的雙方才能計算并核對出相同的認證碼因此它可以同時提供消息完整性與來源認證能力。RFC 2104 定義的 HMAC 構造可概括為HMAC(K, m) H((K ⊕ opad) ∥ H((K ⊕ ipad) ∥ m))其中K是經(jīng)過處理的密鑰若密鑰長度超過哈希分組塊大小則先對其做一次哈希壓縮ipad 0x36、opad 0x5C為兩個不同的填充常量H為底層哈希函數(shù)∥表示字節(jié)拼接。在 Lib/hmac.py 頂部可以直觀看到這兩個常量正是以全表平移的形式實現(xiàn)的trans_5C bytes((x ^ 0x5C) for x in range(256)) trans_36 bytes((x ^ 0x36) for x in range(256))該模塊允許使用任意具有固定摘要長度的哈希函數(shù)但有一個顯著限制原文檔與源碼雙重明確擴展輸出函數(shù)XOF如 SHAKE-128 / SHAKE-256 不能用于 HMAC。這一點在 Lib/hmac.py 的_is_shake_constructor()中顯式檢測shake/SHAKE前綴并拋出ValueError(unsupported hash algorithm ...)相關行為同樣被測試文件 Lib/test/test_hmac.py 中以test_hmac_new_xof_digestmod命名的用例覆蓋。此外本模塊與提供安全哈希函數(shù)的模塊hashlib是天然搭檔——digestmod參數(shù)接受的摘要名稱須是hashlib.new()能識別的算法名詳見 Doc/library/hashlib.rst。核心 API 一覽原文檔定義的模塊級入口函數(shù)與HMAC類方法/屬性可按如下表格速覽詳細用法見后文各節(jié)API類型說明引入/變更版本hmac.new(key, msgNone, digestmod)函數(shù)返回新的HMAC對象digestmod必填3.8 起digestmod必填hmac.digest(key, msg, digest)函數(shù)單發(fā)計算摘要等價于HMAC(key, msg, digest).digest()但走優(yōu)化實現(xiàn)更快3.7 新增HMAC.update(msg)方法增量喂入消息數(shù)據(jù)可多次調用3.4 起支持任意hashlib兼容類型HMAC.digest()方法返回原始字節(jié)摘要長度等于digest_size可能含 NUL 等非 ASCII 字節(jié)—HMAC.hexdigest()方法返回兩倍長度的十六進制字符串—HMAC.copy()方法克隆對象用于高效計算共享相同前綴的多個摘要—HMAC.digest_size屬性結果摘要字節(jié)數(shù)—HMAC.block_size屬性底層哈希算法的內部塊大小字節(jié)3.4 新增HMAC.name屬性規(guī)范名稱恒為小寫如hmac-md53.4 新增hmac.compare_digest(a, b)函數(shù)抗時序分析常量時間的相等比較3.3 新增需要注意從 3.10 開始未文檔化的HMAC.digest_cons、HMAC.inner、HMAC.outer屬性已被移除見原文檔 versionchanged 說明并且HMAC對象在 Lib/hmac.py 中通過__slots__約束為僅有_hmac、_inner、_outer、block_size、digest_size五個槽位?？焖偕鲜窒⒑灻c驗簽創(chuàng)建 HMAC 對象hmac.new()hmac.new(key, msgNone, digestmod)的三個參數(shù)中keybytes 或 bytearray 類型的密鑰3.4 起支持傳其他類型會拋TypeErrormsg可選的初始輸入。若提供等價于隨后自動調用一次update(msg)digestmod必填3.8 起強制可以是三類取值中的任一種適合傳給hashlib.new()的算法名字符串如sha256哈希構造器如hashlib.sha256遵循 PEP 247 的模塊或哈希對象。由于digestmod位置在可選的msg之后當你不傳msg時請務必用關鍵字參數(shù)傳入以避免歧義。這一點在源碼 docstring 與構造器實現(xiàn)中都有強調例如 Lib/hmac.py 在digestmod為空時會拋出TypeError(Missing required argument digestmod.)。一個完整的“簽名 驗簽”示例import hashlib import hmac # 雙方共享的密鑰實際系統(tǒng)中應從密鑰管理服務獲取 secret bshared-secret-key # 發(fā)送方對消息簽名 def sign(message: bytes, key: bytes) - str: return hmac.new(key, message, hashlib.sha256).hexdigest() # 接收方計算期望簽名并做常量時間比對 def verify(message: bytes, expected: str, key: bytes) - bool: computed sign(message, key) return hmac.compare_digest(computed, expected) sig sign(bamount100toalice, secret) print(sig) assert verify(bamount100toalice, sig, secret) # 消息被篡改時驗簽失敗 assert not verify(bamount99999toalice, sig, secret)單發(fā)計算hmac.digest()如果你的消息已經(jīng)完整地放在內存里用hmac.digest(key, msg, digest)比先new()再digest()更快——它在底層使用優(yōu)化的 C/內聯(lián)實現(xiàn)而非逐塊推進狀態(tài)機import hmac # 用法一digest 傳算法名字符串走 C 加速路徑 raw hmac.digest(bkey, bmessage, sha256) # 用法二digest 傳哈希構造器 raw2 hmac.digest(bkey, bmessage, hashlib.sha256) assert raw raw2CPython 實現(xiàn)細節(jié)原文檔明確指出只有當digest是字符串且該算法受 OpenSSL 支持時才會使用優(yōu)化的 C 實現(xiàn)調用 Modules/_hashopenssl.c 暴露的_hashlib.hmac_digest若密鑰超過 OpenSSLHMAC的INT_MAX大小限制拋OverflowError或算法不被 OpenSSL 支持則按 Lib/hmac.py 的邏輯繼續(xù)嘗試_hmacHACL* 實現(xiàn)乃至純 Python 回退。HMAC 對象的方法與屬性詳解update(msg)增量喂入數(shù)據(jù)update(msg)可被重復調用其效果等價于將所有參數(shù)拼接后一次調用即m.update(a); m.update(b)與m.update(a b)完全等價。這在處理流式數(shù)據(jù)如分塊讀取大文件后計算校驗碼時非常有用無需在內存中拼接完整消息。msg可以是任意受hashlib支持的類型3.4 起。digest()與hexdigest()輸出形態(tài)digest()返回原始 bytes長度為構造時所用摘要算法的digest_size可能包含 NUL 等非 ASCII 字節(jié)不適合直接放進文本協(xié)議hexdigest()返回長度兩倍、僅含十六進制字符的字符串適合在電子郵件、HTTP header、URL 等非二進制環(huán)境中安全交換摘要。安全性警示原文檔 warning在驗證例程中把digest()或hexdigest()的輸出與外部提供的摘要比較時務必使用hmac.compare_digest()而非運算符以降低時序攻擊風險詳見下文專節(jié)。copy()克隆 HMAC 對象copy()返回當前對象的一個“克隆體”此后對克隆體的update不會影響原對象。這一能力可高效計算共享同一初始子串的多條消息摘要先統(tǒng)一update公共前綴再復制出多個分支分別喂入不同后綴。h hmac.new(bkey, bheader:, hashlib.sha256) h1 h.copy(); h1.update(bpayload-A) # 只算 header:payload-A h2 h.copy(); h2.update(bpayload-B) # 只算 header:payload-B在 Lib/hmac.py 的實現(xiàn)中copy()直接通過__new__繞過昂貴的__init__對 C 加速路徑調用self._hmac.copy()對純 Python 路徑則分別復制_inner與_outer因此成本很低。對象屬性digest_size、block_size、name屬性含義示例值digest_size結果 HMAC 摘要的字節(jié)數(shù)sha256 為 32sha512 為 64block_size底層哈希算法的內部塊大小字節(jié)sha256 為 64sha384/sha512 為 128name本 HMAC 的規(guī)范名稱恒為小寫hmac-sha256、hmac-md5block_size與name自 3.4 起提供。需要特別指出的是 Lib/hmac.py 中模塊級存在一個占位digest_size None其注釋明確告誡HMAC 返回摘要的大小取決于底層哈希模塊應使用對象實例的digest_size屬性而不是模塊級的這個占位值。name屬性為只讀 property在 C 加速路徑直接透傳底層對象名稱在純 Python 路徑則拼為fhmac-{self._inner.name}見 Lib/hmac.py。compare_digest()抵御時序攻擊的常量時間比較驗簽環(huán)節(jié)最容易被忽視的漏洞是時序側信道普通比較在遇到第一個不同字節(jié)時會短路返回攻擊者可通過測量響應耗時逐字節(jié)猜出合法摘要。hmac.compare_digest(a, b)通過避免基于內容的短路行為來抵御時序分析適合用于密碼學場景。用法約束a、b必須為同類型要么都是str僅限純 ASCII例如hexdigest()的輸出要么都是 bytes-like 對象類型不同如 str 與 bytes 混用、非 ASCII 字符串等都會拋出TypeError。import hmac hmac.compare_digest(abc123, abc123) # Truehexdigest 場景 hmac.compare_digest(b\x00\xff, b\x00\xff) # Truedigest 場景注意原文檔中的note若a與b長度不同或發(fā)生錯誤理論上時序仍可能泄露兩者的類型與長度信息——但絕不會泄露它們的值。這也是為什么實踐中常約定固定長度的摘要格式或先比較長度再比較內容。實現(xiàn)層面3.10 起該函數(shù)在可用時內部使用 OpenSSL 的CRYPTO_memcmp()。搜索 Modules/_hashopenssl.c 可以看到result | CRYPTO_memcmp(left, right, length);的累加式比對正是“無論在哪一位不同都不提前退出”的常量時間寫法在無 OpenSSL 環(huán)境下則回退到_operator._compare_digest見 Lib/hmac.py 的導入分支。測試用例 Lib/test/test_hmac.py 系統(tǒng)性地覆蓋了非法輸入類型、str/bytes/bytearray 混用、以及bytes/str子類——即使子類把__eq__重寫成拋異常compare_digest也絕不會調用它。源碼級實現(xiàn)CPython 的三層加速架構hmac并不是一個“只看 Python 代碼”的純腳本模塊。從 Lib/test/test_hmac.py 的模塊注釋可以清晰看到CPython 為其提供了三種實現(xiàn)按優(yōu)先級依次為OpenSSL HMAC使用 OpenSSL 哈希函數(shù)由_hashlib擴展提供Modules/_hashopenssl.c中的_hashlib.hmac_new、_hashlib.hmac_digestHACLHMAC*內置的 C 實現(xiàn)Modules/hmacmodule.c實現(xiàn)_hmac在無 OpenSSL 的構建如 WASI、部分受限平臺上保證仍有余力且可預測的性能與安全屬性通用純 Python HMACLib/hmac.py內的回退實現(xiàn)能對接 OpenSSL/HACL* 的哈希名與構造器、PEP 247 模塊以及任意用戶自定義哈希對象。對象創(chuàng)建時的分派邏輯非常直白見 Lib/hmac.py若_hashopenssl可用且digestmod為字符串或 OpenSSL 內置構造器類型優(yōu)先走_init_openssl_hmac()算法不受 OpenSSL 支持時拋出UnsupportedDigestmodError并繼續(xù)下探否則若_hmac可用且digestmod為字符串走_init_builtin_hmac()未知算法拋UnknownHashError再下探最后落入_init_old()純 Python 路徑。單發(fā)函數(shù)hmac.digest()的分派邏輯類似Lib/hmac.py但多了一層超大密鑰保護OpenSSL 的HMAC將密鑰限制在INT_MAX內HACL* 限制在UINT32_MAX內一旦越界即優(yōu)雅回退到_compute_digest_fallback()而不是讓 C 層崩潰。純 Python 回退路徑_compute_digest_fallback()Lib/hmac.py是理解 RFC 2104 算法細節(jié)的最佳教材其關鍵步驟為blocksize getattr(inner, block_size, 64) if len(key) blocksize: # 密鑰過長則先哈希壓縮 key digest_cons(key).digest() key key.ljust(blocksize, b\0) # 補齊到塊大小 inner.update(key.translate(trans_36)) # ipad 0x36 outer.update(key.translate(trans_5C)) # opad 0x5C inner.update(msg) outer.update(inner.digest()) # 外層再包一層 return outer.digest()值得注意的工程細節(jié)若底層哈希對象缺少block_size屬性或塊大小小于 16_init_old()會發(fā)出RuntimeWarning并回退到類默認的 64 字節(jié)塊Lib/hmac.py類屬性blocksize 64的注釋說明它代表“默認塊大小”允許子類重寫。實戰(zhàn)典型應用場景場景一Webhook / 開放 API 的請求簽名服務端與調用方預共享密鑰調用方對規(guī)范化后的請求參數(shù)按固定順序拼接后計算 HMAC放入X-Signature頭服務端用compare_digest校驗可同時防篡改與防偽造def make_signature(payload: str, timestamp: str, secret: bytes) - str: # 規(guī)范化待簽字符串務必與服務端完全一致 message f{timestamp}.{payload}.encode() return hmac.new(secret, message, sha256).hexdigest() def check_signature(payload: str, timestamp: str, secret: bytes, sig: str) - bool: if not (isinstance(sig, str) and len(sig) 64): # 先校長度再常量時間比較 return False return hmac.compare_digest(make_signature(payload, timestamp, secret), sig)場景二增量校驗大文件無需將整個文件讀入內存使用update()流式處理兼顧內存與完整性import hmac, hashlib def file_hmac_hex(path: str, secret: bytes, chunk: int 1 20) - str: h hmac.new(secret, digestmodhashlib.sha256) with open(path, rb) as f: while block : f.read(chunk): h.update(block) return h.hexdigest()場景三與標準測試向量對照自檢RFC 4231 的 Test Case 120 字節(jié)0x0b密鑰、消息Hi There對應 sha256 摘要為b0344c61d8db38535ca8afceaf0bf12b881dc200c9833da726e9376c2e32cff7——該向量可從測試文件 Lib/test/test_hmac.py 中直接讀取MD5/SHA-1 向量取自 RFC 2202SHA-2 取自 RFC 4231SHA-3 取自 NIST。你可以用下面代碼驗證自己的環(huán)境實現(xiàn)import hmac, hashlib got hmac.digest(b\x0b * 20, bHi There, sha256).hex() assert got b0344c61d8db38535ca8afceaf0bf12b \ 881dc200c9833da726e9376c2e32cff7 print(RFC 4231 TC1 OK)邊界情況與常見誤區(qū)1. 密鑰類型與長度key只接受 bytes/bytearray源碼在 Lib/hmac.py 顯式拋TypeError密鑰長度超過底層哈希塊大小如 sha256 的 64 字節(jié)時算法會先對密鑰做一次哈希壓縮再參與計算因此從密碼學角度“過長密鑰”并不會帶來額外安全強度反而應先經(jīng) KDF 處理。2. 算法塊大小對照決定密鑰“過長”的閾值底層算法block_size字節(jié)digest_size字節(jié)MD5 / SHA-1 / SHA-224 / SHA-2566416 / 20 / 28 / 32SHA-384 / SHA-51212848 / 643. 不能用于 XOFSHAKE-128/256 等擴展輸出函數(shù)會觸發(fā)ValueError因為 HMAC 需要固定長度摘要作為中間值與最終輸出對應_is_shake_constructor檢查。4.digestmod必須顯式提供3.8 起缺省會拋TypeError舊的hmac.new(key, msg)兩參調用方式不可再依賴默認 MD5。5. 摘要對比一定用compare_digest無論digest()的二進制輸出還是hexdigest()的十六進制輸出都不要用前者二進制中可能混入 NUL 等字符比較行為易踩坑且存在時序泄露。6. 模塊級hmac.digest_size是None這是源碼中的顯式占位務必從實例讀取真實值。測試體系與進一步閱讀HMAC 的正確性在 CPython 中受到嚴格驗證Lib/test/test_hmac.py 共 1600 余行通過import_fresh_module分別以“屏蔽_hashlib/_hmac”純 Python、“只加載_hmac”HACL*等方式對同一套測試向量跑三份實現(xiàn)并專門設有DigestModTestCaseMixin、HMACCompareDigestTestCase等測試類覆蓋構造缺參、未知算法、超大密鑰bigmemtest、_4G相關用例、digestmod缺失與非法值等異常路徑。若需進一步探究相關主題可繼續(xù)閱讀Lib/hmac.py模塊完整實現(xiàn)與三層分派邏輯Modules/_hashopenssl.cOpenSSL 加速路徑hmac_digest/hmac_new/compare_digestModules/hmacmodule.cHACL* 內置 HMAC 實現(xiàn)Lib/test/test_hmac.pyRFC 2202/4231 與 NIST 測試向量及全部行為測試Doc/library/hashlib.rst底層安全哈希函數(shù)模塊文檔。綜上hmac模塊以極小的 API 面提供了符合 RFC 2104 標準的消息認證能力其正確用法可概括為三句話用new/HMAC做增量計算、用digest做單發(fā)快算、用compare_digest做驗簽比對。在此基礎上理解其 OpenSSL → HACL* → 純 Python 的三級實現(xiàn)能幫助你在部署到無 OpenSSL 的受限平臺時依然對安全性與行為邊界心中有數(shù)?！久赓M下載鏈接】cpythonThe Python programming language項目地址: https://gitcode.com/GitHub_Trending/cp/cpython創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考