摘要

目前有多種不同的模組實現了 MD5 或 SHA 等加密雜湊演算法。本文件規定了此類演算法的標準 API，以便於在不同實現之間進行切換。

規範

所有雜湊模組都應提供相同的介面。可以新增額外的方法或變數，但本文件中描述的那些應始終存在。

雜湊函式模組定義一個函式

建立一個新的雜湊物件並返回它。第一種形式用於無金鑰雜湊，例如 MD5 或 SHA。對於 HMAC 等有金鑰雜湊，key 是一個必需引數，包含一個用於金鑰的字串。在這兩種情況下，如果提供了可選的 string 引數，它將立即雜湊到物件的初始狀態中，就像呼叫了 obj.update(string) 一樣。

建立雜湊物件後，可以使用其 update() 方法將任意字串饋入物件，並且可以隨時透過呼叫物件的 digest() 方法獲取雜湊值。

可以向此函式新增任意額外的關鍵字引數，但如果未提供，則應使用合理的預設值。例如，對於支援可變輪數和多種不同輸出大小的雜湊函式，可以新增 rounds 和 digest_size 關鍵字，它們應預設為被認為是安全的值。

雜湊函式模組定義一個變數

一個整數值；由該模組建立的雜湊物件產生的摘要大小，以位元組為單位。您也可以透過建立一個示例物件並訪問其 digest_size 屬性來獲取此值，但從模組中獲取此值可能很方便。輸出大小可變的雜湊將此變數設定為 None。

雜湊物件需要一個屬性

此屬性與模組級別的 digest_size 變數相同，衡量雜湊物件產生的摘要大小，以位元組為單位。如果雜湊具有可變輸出大小，則必須在建立雜湊物件時選擇此輸出大小，並且此屬性必須包含所選大小。因此，None 不是此屬性的合法值。

雜湊物件需要以下方法

返回此雜湊物件的獨立副本。此副本的更新不會影響原始物件。

以包含 8 位資料的字串形式返回此雜湊物件的雜湊值。此函式不會以任何方式更改物件；呼叫此函式後，您可以繼續更新物件。

以包含十六進位制數字的字串形式返回此雜湊物件的雜湊值。數字 a 到 f 應使用小寫字母。與 .digest() 方法一樣，此方法不得更改物件。

將 string 雜湊到雜湊物件的當前狀態中。update() 可以在雜湊物件的生命週期內被呼叫任意次。

雜湊模組可以定義額外的模組級函式或物件方法，並且仍然符合此規範。

下面是一個示例，使用名為 MD5 的模組

>>> from Crypto.Hash import MD5
>>> m = MD5.new()
>>> m.digest_size
16
>>> m.update('abc')
>>> m.digest()
'\x90\x01P\x98<\xd2O\xb0\xd6\x96?}(\xe1\x7fr'
>>> m.hexdigest()
'900150983cd24fb0d6963f7d28e17f72'
>>> MD5.new('abc').digest()
'\x90\x01P\x98<\xd2O\xb0\xd6\x96?}(\xe1\x7fr'

基本原理

摘要大小以位元組為單位，而不是位，儘管雜湊演算法大小通常以位為單位引用；例如，MD5 是一個 128 位演算法，而不是 16 位元組演算法。這是因為在我檢視的示例程式碼中，經常需要以位元組為單位的長度（在檔案中向前或向後查詢；計算輸出字串的長度），而很少使用以位為單位的長度。因此，需要以位為單位的大小的少數人將不得不承擔將 digest_size 乘以 8 的負擔。

有人建議將 update() 方法更好地命名為 append()。但是，該方法確實導致雜湊物件的當前狀態被更新，並且 Python 附帶的 md5 和 sha 模組已經使用了 update()，因此最簡單的做法是保持名稱 update() 不變。

有金鑰雜湊建構函式引數的順序是一個棘手的問題。不清楚 key 應該排在第一位還是第二位。它是一個必需引數，通常的約定是將必需引數放在前面，但這也意味著 string 引數從第一個位置移動到第二個位置。可能會混淆並將單個引數傳遞給有金鑰雜湊，認為您正在將初始字串傳遞給無金鑰雜湊，但為了避免這種潛在錯誤，似乎不值得使有金鑰雜湊的介面更模糊。

更改

2001-09-17：將 clear() 重新命名為 reset()；向物件添加了 digest_size 屬性；添加了 .hexdigest() 方法。

2001-09-20：完全刪除了 reset() 方法。

2001-09-28：對於可變大小雜湊，將 digest_size 設定為 None。

致謝

感謝 Aahz、Andrew Archibald、Rich Salz、Itamar Shtull-Trauring 以及 python-crypto 列表的讀者對本 PEP 的評論。

版權

本文件已置於公共領域。