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

原始碼：Lib/hmac.py

此模組實作了 RFC 2014 所描述的 HMAC 演算法。此介面允許使用具有固定摘要 (digest) 長度的任意雜湊函式。要特別注意的是擴充輸出函式（如 SHAKE-128 或 SHAKE-256）不能與 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 版被加入.

class hmac.HMAC

  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 版被加入.

在 3.10 版的變更: 未寫入文件的屬性 `HMAC.digest_cons`，`HMAC.inner` 和 `HMAC.outer` 已被移除。

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

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()`。

也參考

`hashlib` 模組

  Python 模組提供安全的雜湊函式。