"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 模組提供安全的雜湊函式。
