hmac --- 基於金鑰雜湊的訊息驗證¶

原始碼：Lib/hmac.py

此模組 (module) 實現了RFC 2014 所描述的 HMAC 演算法。

hmac.new(key,msg=None,digestmod)¶

回傳一個新的 hmac 物件。key 是一個指定密鑰的 bytes（位元組）或 bytearray 物件。如果提供了msg，將會呼叫update(msg) 方法。digestmod 為 HMAC 物件所用的摘要名稱、摘要建構函式 (constructor) 或模組。它可以是適用於hashlib.new() 的任何名稱。儘管該引數的位置在後，但它卻是必須的。

在 3.4 版的變更:參數key 可以為 bytes 或 bytearray 物件。參數msg 可以為hashlib 所支援的任意型別。參數digestmod 可以為雜湊演算法的名稱。

在 3.8 版的變更:digestmod 引數現在是必須的。請將其作為關鍵字引數傳入以避免當你沒有初始msg 時導致的麻煩。

hmac.digest(key,msg,digest)¶

基於給定密鑰key 和digest 回傳msg 的摘要。此函式等價於HMAC(key,msg,digest).digest()，但使用了優化的 C 或 行內實作（inline implementation），對放入記憶體的訊息能處理得更快。參數key、msg 和digest 在new() 中具有相同含義。

作為 CPython 的實現細節，C 的優化實作只有當digest 為字串並且是一個 OpenSSL 所支持的摘要演算法的名稱時才會被使用。

在 3.7 版被加入.

HMAC 物件具有下列方法 (method)：

HMAC.update(msg)¶

用msg 來更新 hmac 物件。重複呼叫相當於單次呼叫並傳入所有引數的拼接結果：m.update(a);m.update(b) 等價於m.update(a+b)。

在 3.4 版的變更:參數msg 可以是hashlib 所支援的任何型別。

HMAC.digest()¶

回傳目前已傳給update() 方法的 bytes 摘要。這個 bytes 物件的長度會與傳給建構函式的摘要digest_size 的長度相同。它可以包含 NUL bytes 以及 non-ASCII bytes。

警告

在一個例行的驗證事務運行期間，將digest() 的輸出與外部提供的摘要進行比較時，建議使用compare_digest() 函式而不是== 運算子以減少被定時攻擊時的漏洞。

HMAC.hexdigest()¶

像是digest() 但摘要的回傳形式為兩倍長度的字串，且此字串只包含十六進位數位。這可以被用於在電子郵件或其他非二進位制環境中安全地交換數據。

警告

在一個例行的驗證事務運行期間，將hexdigest() 的輸出與外部提供的摘要進行比較時，建議使用compare_digest() 函式而不是== 運算子以減少被定時攻擊時的漏洞。

HMAC.copy()¶

回傳 hmac 物件的拷貝 ("clone")。這可以被用來有效率地計算那些共享相同初始子字串的字串的摘要。

一個 hash 物件具有以下屬性：

HMAC.digest_size¶

以 bytes 表示最終 HMAC 摘要的大小。

HMAC.block_size¶

以 bytes 表示雜湊演算法的內部區塊大小。

在 3.4 版被加入.

HMAC.name¶

HMAC 的正準名稱總是為小寫形式，例如hmac-md5。

在 3.4 版被加入.

這個模組還提供了下列輔助函式：

hmac.compare_digest(a,b)¶

回傳a==b。此函式使用一種經專門設計的方式通過避免基於內容的短路行為來防止定時分析，使得它適合處理密碼學。a 和b 必須為相同的型別：可以是str（僅限 ASCII，如HMAC.hexdigest() 的回傳值），或者是bytes-like object。

備註

如果a 和b 具有不同的長度，或者如果發生了錯誤，定時攻擊在理論上可以取得有關a 和b 的型別和長度的訊息 — 但不能取得他們的值。

在 3.3 版被加入.

在 3.10 版的變更:此函式在可能的情況下會在內部使用 OpenSSL 的CRYPTO_memcmp()。