hmac --- 基于密鑰的消息驗證

源代碼: Lib/hmac.py

---

此模塊實現了 HMAC 算法，算法的描述參見 RFC 2104。

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

返回一個新的 hmac 對象。 key 是一個指定密鑰的 bytes 或 bytearray 對象。 如果提供了 msg，將會調用 update(msg) 方法。 digestmod 為 HMAC 對象要使用的摘要名稱、摘要構造器或模塊。 它支持任何適用于 hashlib.new() 的名稱并默認設為 hashlib.md5 構造器。

在 3.4 版更改: 形參 key 可以為 bytes 或 bytearray 對象。 形參 msg 可以為 hashlib 所支持的任意類型。 形參 digestmod 可以為某種哈希算法的名稱。

Deprecated since version 3.4, will be removed in version 3.8: MD5 作為 digestmod 的隱式默認摘要已被棄用。

hmac.digest(key, msg, digest)

基于給定密鑰 key 和 digest 返回 msg 的摘要。 此函數等價于 HMAC(key, msg, digest).digest()，但使用了優化的 C 或內聯實現，對放入內存的消息能處理得更快。 形參 key, msg 和 digest 具有與 new() 中相同的含義。

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

3.7 新版功能.

HMAC 對象具有下列方法:

HMAC.update(msg)

用 msg 來更新 hmac 對象。 重復調用相當于單次調用并傳入所有參數的拼接結果: m.update(a); m.update(b) 等價于 m.update(a + b)。

在 3.4 版更改: 形參 msg 可以為 hashlib 所支持的任何類型。

HMAC.digest()

返回當前已傳給 update() 方法的字節串數據的摘要。 這個字節串數據的長度將與傳給構造器的摘要的長度 digest_size 相同。 它可以包含非 ASCII 的字節，包括 NUL 字節。

警告

在驗證例程運行期間將 digest() 的輸出與外部提供的摘要進行比較時，建議使用 compare_digest() 函數而不是 == 運算符以減少定時攻擊防御力的不足。

HMAC.hexdigest()

類似于 digest() 但摘要會以兩倍長度字符串的形式返回，其中僅包含十六進制數碼。 這可以被用于在電子郵件或其他非二進制環境中安全地交換數據值。

警告

在驗證例程運行期間將 hexdigest() 的輸出與外部提供的摘要進行比較時，建議使用 compare_digest() 函數而不是 == 運算符以減少定時攻擊防御力的不足。

HMAC.copy()

返回 hmac 對象的副本（“克隆）。 這可被用來高效地計算共享相同初始子串的數據的摘要。

hash 對象具有以下屬性：

HMAC.digest_size

以字節表示的結果 HMAC 摘要的大小。

HMAC.block_size

以字節表示的哈希算法的內部塊大小。

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 新版功能.

參見

模塊 hashlib

提供安全哈希函數的 Python 模塊。