雜湊演算法¶

每種種類的 hash 都有一個以其命名的建構函式方法。全部都會回傳具有相同簡單介面的雜湊物件。例如：可使用 sha256() 來建立 SHA-256 雜湊物件。現在你可以使用 update 方法向此物件提供類位元組物件 (bytes-like objects)（通常是 bytes）。在任何時候，你都可以使用 digest() 或 hexdigest() 方法來要求它提供迄今為止傳遞給它的資料串聯的摘要 (digest)。

為了允許多執行緒 (multithreading)，Python GIL 被釋放，同時在其建構函式或 .update 方法中計算一次提供超過 2047 位元組資料的雜湊值。

Constructors for hash algorithms that are always present in this module are md5(), sha1(), sha224(), sha256(), sha384(), sha512(), sha3_224(), sha3_256(), sha3_384(), sha3_512(), shake_128(), shake_256(), blake2b(), and blake2s(). These correspond to algorithms_guaranteed.

Any of these may nonetheless be missing or blocked in unusual environments, such as a rare "FIPS compliant" build of Python or when OpenSSL's "FIPS mode" is configured to exclude some algorithms from its default provider. Calling the constructor of an algorithm that is unavailable raises ValueError.

如果你的 Python 發行版的 hashlib 與提供其他演算法的 OpenSSL 版本鏈結，也可能有其他演算法可用。其他則不保證可用於在所有安裝上，並且只能以名稱來透過 new() 存取。請參閱 algorithms_available。

用法¶

取得位元組字串 b"Nobody inspects the spammish repetition" 的摘要：

>>> import hashlib
>>> m = hashlib.sha256()
>>> m.update(b"Nobody inspects")
>>> m.update(b" the spammish repetition")
>>> m.digest()
b'\x03\x1e\xdd}Ae\x15\x93\xc5\xfe\\\x00o\xa5u+7\xfd\xdf\xf7\xbcN\x84:\xa6\xaf\x0c\x95\x0fK\x94\x06'
>>> m.hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'

更濃縮：

>>> hashlib.sha256(b"Nobody inspects the spammish repetition").hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'

建構函式¶

hashlib.new(name, [data, ]*, usedforsecurity=True)¶

是一個通用建構函式，它將目標演算法的字串 name 作為其第一個參數。它還允許使用者取得上面列出的雜湊值以及 OpenSSL 函式庫可能提供的任何其他演算法。

使用 new() 和演算法名稱：

>>> h = hashlib.new('sha256')
>>> h.update(b"Nobody inspects the spammish repetition")
>>> h.hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'

hashlib.md5([data, ]*, usedforsecurity=True)¶

hashlib.sha1([data, ]*, usedforsecurity=True)¶

hashlib.sha224([data, ]*, usedforsecurity=True)¶

hashlib.sha256([data, ]*, usedforsecurity=True)¶

hashlib.sha384([data, ]*, usedforsecurity=True)¶

hashlib.sha512([data, ]*, usedforsecurity=True)¶

hashlib.sha3_224([data, ]*, usedforsecurity=True)¶

hashlib.sha3_256([data, ]*, usedforsecurity=True)¶

hashlib.sha3_384([data, ]*, usedforsecurity=True)¶

hashlib.sha3_512([data, ]*, usedforsecurity=True)¶

諸如此類的附名建構函式比將演算法名稱傳遞給 new() 更快。

屬性¶

Hashlib 提供以下常數模組屬性：

hashlib.algorithms_guaranteed¶

包含所有平台上該模組保證支援的雜湊演算法名稱的集合。請注意，'md5' 有出現在此列表中，儘管有一些上游供應商提供了奇怪的「符合 FIPS (FIPS compliant)」的 Python 建置，並將其排除在外。

在 3.2 版被加入.

hashlib.algorithms_available¶

包含正在運行的 Python 直譯器中可用的雜湊演算法名稱的集合。這些名稱在傳遞給 new() 時將被識別。algorithms_guaranteed 都會是它的一個子集。相同的演算法可能會以不同的名稱多次出現在該集合中（多虧了 OpenSSL）。

在 3.2 版被加入.

雜湊物件¶

以下的值皆為建構函式回傳之雜湊物件的常數屬性：

hash.digest_size¶

生成雜湊的大小（以位元組為單位）。

hash.block_size¶

雜湊演算法的內部區塊大小（以位元組為單位）。

雜湊物件具有以下屬性：

hash.name¶

該雜湊的規範名稱，都會是小寫，且都會適合作為 new() 的參數以建立此型別的另一個雜湊。

在 3.4 版的變更: name 屬性自 CPython 誕生以來就存在於其中，但直到 Python 3.4 才正式確立，因此在某些平台上可能不存在。

雜湊物件具有以下方法：

hash.update(data)¶

使用類位元組物件來更新雜湊物件。重複呼叫相當於連接所有引數的單一呼叫：m.update(a); m.update(b) 等價於 m.update(a+b)。

hash.digest()¶

回傳目前有傳遞給 update() 方法的資料之摘要。這是一個大小為 digest_size 的位元組物件，它可能包含從 0 到 255 的整個範圍內的位元組。

hash.hexdigest()¶

與 digest() 類似，只不過摘要會是作為雙倍長度的字串物件回傳，僅包含十六進位數字。這可用於在電子郵件或其他非二進位環境中安全地交換值。

hash.copy()¶

回傳雜湊物件的副本（「複製 (clone)」），這可用於高效率地計算出共享同一初始子字串的資料之摘要。

SHAKE 可變長度摘要¶

hashlib.shake_128([data, ]*, usedforsecurity=True)¶

hashlib.shake_256([data, ]*, usedforsecurity=True)¶

shake_128() 和 shake_256() 演算法提供了可變長度摘要，其 length_in_bits//2 最高為 128 或 256 位元安全性。因此，他們的摘要方法會需要長度。最大長度不受 SHAKE 演算法限制。

shake.digest(length)¶

回傳目前有傳遞給 update() 方法的資料之摘要。這是一個大小為 length 的位元組物件，可能包含從 0 到 255 的整個範圍內的位元組。

shake.hexdigest(length)¶

與 digest() 類似，只不過摘要作為雙倍長度的字串物件回傳，僅包含十六進位數字。這可用於交換電子郵件或其他非二進位環境中的值。

範例：

>>> h = hashlib.shake_256(b'Nobody inspects the spammish repetition')
>>> h.hexdigest(20)
'44709d6fcb83d92a76dcb0b668c98e1b1d3dafe7'

檔案雜湊¶

hashlib 模組提供了一個輔助函式，用於對檔案或類檔案物件 (file-like object) 進行有效率的雜湊。

hashlib.file_digest(fileobj, digest, /)¶

回傳已用檔案物件內容更新的摘要物件。

fileobj 必須是以二進位模式讀取的類檔案物件。它接受來自內建 open() 的檔案物件、BytesIO 實例、來自 socket.socket.makefile() 的 SocketIO 物件等。fileobj 必須以阻塞模式開啟，否則可能會引發 BlockingIOError。

該函式可以繞過 Python 的 I/O 並直接使用 fileno() 中的檔案描述器 (file descriptor)。在此函式回傳或引發後，必須假定 fileobj 處於未知狀態 (unknown state)。由呼叫者決定是否關閉 fileobj。

digest 必須是名稱作為 str 的雜湊演算法、雜湊建構函式或會回傳雜湊物件的可呼叫函式。

範例：

>>> import io, hashlib, hmac
>>> with open("library/hashlib.rst", "rb") as f:
...     digest = hashlib.file_digest(f, "sha256")
...
>>> digest.hexdigest()
'...'

>>> buf = io.BytesIO(b"somedata")
>>> mac1 = hmac.HMAC(b"key", digestmod=hashlib.sha512)
>>> digest = hashlib.file_digest(buf, lambda: mac1)

>>> digest is mac1
True
>>> mac2 = hmac.HMAC(b"key", b"somedata", digestmod=hashlib.sha512)
>>> mac1.digest() == mac2.digest()
True

在 3.11 版被加入.

在 3.14 版的變更: 現在如果檔案以非阻塞模式開啟，會引發 BlockingIOError。先前，會有多餘的空位元組被加入到摘要中。

密鑰的生成¶

密鑰生成 (key derivation) 和密鑰延伸 (key stretching) 演算法專為安全密碼雜湊而設計。像是 sha1(password) 這樣過於單純的演算法無法抵抗暴力攻擊。一個好的密碼雜湊函式必須是可調校的 (tunable)、緩慢的，並且有包含 salt（鹽）。

hashlib.pbkdf2_hmac(hash_name, password, salt, iterations, dklen=None)¶

該函式提供基於密碼的 PKCS#5 密鑰生成函式 2。它使用 HMAC 作為偽隨機函式 (pseudorandom function)。

字串 hash_name 是 HMAC 的雜湊摘要演算法所需的名稱，例如 sha1 或 sha256。password 和 salt 被直譯為位元組緩衝區。應用程式和函式庫應為 password 設下合理的長度限制（例如 1024）。salt 應該是來自適當來源（例如 os.urandom()）且大約 16 或更多位元組。

應根據雜湊演算法和計算能力選擇 iterations 次數。截至 2022 年，建議進行數十萬次 SHA-256 疊代。有關為什麼以及如何選擇最適合你的應用程式的基本原理，請閱讀 NIST-SP-800-132 的 Appendix A.2.2。stackexchange pbkdf2 疊代問題上的答案有詳細解釋。

dklen 是生成的密鑰長度。如果 dklen 為 None，則會使用雜湊演算法 hash_name 的摘要大小，例如 SHA-512 為 64。

>>> from hashlib import pbkdf2_hmac
>>> our_app_iters = 500_000  # Application specific, read above.
>>> dk = pbkdf2_hmac('sha256', b'password', b'bad salt' * 2, our_app_iters)
>>> dk.hex()
'15530bba69924174860db778f2c6f8104d3aaf9d26241840c8c4a641c8d000a9'

僅當有使用 OpenSSL 編譯 Python 時該函式才可用。

在 3.4 版被加入.

在 3.12 版的變更: 該函式現在僅在有使用 OpenSSL 建置 Python 時可用。緩慢的純 Python 實作已被刪除。

hashlib.scrypt(password, *, salt, n, r, p, maxmem=0, dklen=64)¶

該函式提供（如 RFC 7914 中所定義的）scrypt 基於密碼的密鑰衍生函式。

password 和 salt 必須是類位元組物件。應用程式和函式庫應為 password 設下合理的長度限制（例如 1024）。salt 應該是來自適當來源（例如 os.urandom()）且大約 16 或更多位元組。

n 是 CPU/記憶體開銷係數、r 是區塊大小、p 為平行化係數、maxmem 為記憶體限制（OpenSSL 1.1.0 預設為 32 MiB）。dklen 是生成密鑰的長度。

在 3.6 版被加入.

BLAKE2¶

BLAKE2 是在 RFC 7693 中定義的加密雜湊函式，有兩種類型：

• BLAKE2b，針對 64 位元平台進行了最佳化，可生成 1 到 64 位元組之間任意大小的摘要，

• BLAKE2s，針對 8 至 32 位元平台進行了最佳化，可生成 1 至 32 位元組之間任意大小的摘要。

BLAKE2 支援密鑰模式 (keyed mode) （更快、更簡單的 HMAC 替代品）、加鹽雜湊 (salted hashing)、個人化和樹狀雜湊。

該模組中的雜湊物件遵循標準函式庫的 hashlib 物件 API。

建立雜湊物件¶

新的雜湊物件是透過呼叫建構函式建立的：

hashlib.blake2b(data=b'', *, digest_size=64, key=b'', salt=b'', person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, node_depth=0, inner_size=0, last_node=False, usedforsecurity=True)¶

hashlib.blake2s(data=b'', *, digest_size=32, key=b'', salt=b'', person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, node_depth=0, inner_size=0, last_node=False, usedforsecurity=True)¶

這些函式回傳相應的雜湊物件以計算 BLAKE2b 或 BLAKE2s。他們可以選擇採用這些通用參數：

• data：要雜湊的初始資料塊 (data chunk)，它必須是類位元組物件。它只能作為位置引數傳遞。

• digest_size：輸出摘要的大小（以位元組為單位）。

• key：用於密鑰雜湊的密鑰（BLAKE2b 最多 64 位元組、BLAKE2s 最多 32 位元組）。

• salt：用於隨機雜湊的鹽（BLAKE2b 最多 16 個位元組、BLAKE2s 最多 8 個位元組）。

• person：個人化字串（BLAKE2b 最多 16 個位元組、BLAKE2s 最多 8 個位元組）。

下表顯示了一般參數的限制（以位元組為單位）：

雜湊	digest_size	len(key)	len(salt)	len(person)
BLAKE2b	64	64	16	16
BLAKE2s	32	32	8	8

備註

BLAKE2 規範定義了鹽和個人化參數的恆定長度，但為了方便起見，此實作接受任意大小的位元組字串，最多可達指定長度。如果參數的長度小於指定的長度，則用零補滿，所以像是 b'salt 和 b'salt\x00 是相同的值。（但 key 的情況並非如此。）

這些大小可作為模組常數使用，如下所述。

建構函式還接受以下樹狀雜湊參數：

• fanout：扇出（0 到 255，如果無限制則為 0、順序模式為 1）。

• depth：樹的最大深度（1 到 255，如果無限制則為 255、順序模式為 1）。

• leaf_size：葉的最大位元組長度（0 到 2**32-1，如果無限制或處於順序模式則為 0）。

• node_offset：節點偏移量（BLAKE2b 為 0 到 2**64-1，BLAKE2s 為 0 到 2**48-1，0 表示第一個、最左邊、葉子或在順序模式下）。

• node_depth：節點深度（0 到 255，葉為 0，或在順序模式下）。

• inner_size：內部摘要大小（BLAKE2b 為 0 到 64，BLAKE2s 為 0 到 32，順序模式為 0）。

• last_node：布林值，代表處理的節點是否為最後一個（False 代表順序模式）。

關於樹狀雜湊的綜合回顧，請參閱 BLAKE2 規範中的第 2.10 節。

>>> from hashlib import blake2b
>>> h = blake2b()
>>> h.update(b'Hello world')
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

>>> from hashlib import blake2b
>>> blake2b(b'Hello world').hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

>>> from hashlib import blake2b
>>> items = [b'Hello', b' ', b'world']
>>> h = blake2b()
>>> for item in items:
...     h.update(item)
...
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

>>> from hashlib import blake2b
>>> h = blake2b(digest_size=20)
>>> h.update(b'Replacing SHA1 with the more secure function')
>>> h.hexdigest()
'd24f26cf8de66472d58d4e1b1774b4c9158b1f4c'
>>> h.digest_size
20
>>> len(h.digest())
20

>>> from hashlib import blake2b, blake2s
>>> blake2b(digest_size=10).hexdigest()
'6fa1d8fcfd719046d762'
>>> blake2b(digest_size=11).hexdigest()
'eb6ec15daf9546254f0809'
>>> blake2s(digest_size=10).hexdigest()
'1bf21a98c78a1c376ae9'
>>> blake2s(digest_size=11).hexdigest()
'567004bf96e4a25773ebf4'

>>> from hashlib import blake2b
>>> h = blake2b(key=b'pseudorandom key', digest_size=16)
>>> h.update(b'message data')
>>> h.hexdigest()
'3d363ff7401e02026f4a4687d4863ced'

>>> from hashlib import blake2b
>>> from hmac import compare_digest
>>>
>>> SECRET_KEY = b'pseudorandomly generated server secret key'
>>> AUTH_SIZE = 16
>>>
>>> def sign(cookie):
...     h = blake2b(digest_size=AUTH_SIZE, key=SECRET_KEY)
...     h.update(cookie)
...     return h.hexdigest().encode('utf-8')
>>>
>>> def verify(cookie, sig):
...     good_sig = sign(cookie)
...     return compare_digest(good_sig, sig)
>>>
>>> cookie = b'user-alice'
>>> sig = sign(cookie)
>>> print("{0},{1}".format(cookie.decode('utf-8'), sig))
user-alice,b'43b3c982cf697e0c5ab22172d1ca7421'
>>> verify(cookie, sig)
True
>>> verify(b'user-bob', sig)
False
>>> verify(cookie, b'0102030405060708090a0b0c0d0e0f00')
False

>>> import hmac, hashlib
>>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)
>>> m.update(b'message')
>>> m.hexdigest()
'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'

>>> import os
>>> from hashlib import blake2b
>>> msg = b'some message'
>>> # Calculate the first hash with a random salt.
>>> salt1 = os.urandom(blake2b.SALT_SIZE)
>>> h1 = blake2b(salt=salt1)
>>> h1.update(msg)
>>> # Calculate the second hash with a different random salt.
>>> salt2 = os.urandom(blake2b.SALT_SIZE)
>>> h2 = blake2b(salt=salt2)
>>> h2.update(msg)
>>> # The digests are different.
>>> h1.digest() != h2.digest()
True

>>> from hashlib import blake2b
>>> FILES_HASH_PERSON = b'MyApp Files Hash'
>>> BLOCK_HASH_PERSON = b'MyApp Block Hash'
>>> h = blake2b(digest_size=32, person=FILES_HASH_PERSON)
>>> h.update(b'the same content')
>>> h.hexdigest()
'20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'
>>> h = blake2b(digest_size=32, person=BLOCK_HASH_PERSON)
>>> h.update(b'the same content')
>>> h.hexdigest()
'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'

>>> from hashlib import blake2s
>>> from base64 import b64decode, b64encode
>>> orig_key = b64decode(b'Rm5EPJai72qcK3RGBpW3vPNfZy5OZothY+kHY6h21KM=')
>>> enc_key = blake2s(key=orig_key, person=b'kEncrypt').digest()
>>> mac_key = blake2s(key=orig_key, person=b'kMAC').digest()
>>> print(b64encode(enc_key).decode('utf-8'))
rbPb15S/Z9t+agffno5wuhB77VbRi6F9Iv2qIxU7WHw=
>>> print(b64encode(mac_key).decode('utf-8'))
G9GtHFE1YluXY1zWPlYk1e/nWfu0WSEb0KRcjhDeP/o=

  10
 /  \
00  01

>>> from hashlib import blake2b
>>>
>>> FANOUT = 2
>>> DEPTH = 2
>>> LEAF_SIZE = 4096
>>> INNER_SIZE = 64
>>>
>>> buf = bytearray(6000)
>>>
>>> # Left leaf
... h00 = blake2b(buf[0:LEAF_SIZE], fanout=FANOUT, depth=DEPTH,
...               leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
...               node_offset=0, node_depth=0, last_node=False)
>>> # Right leaf
... h01 = blake2b(buf[LEAF_SIZE:], fanout=FANOUT, depth=DEPTH,
...               leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
...               node_offset=1, node_depth=0, last_node=True)
>>> # Root node
... h10 = blake2b(digest_size=32, fanout=FANOUT, depth=DEPTH,
...               leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
...               node_offset=0, node_depth=1, last_node=True)
>>> h10.update(h00.digest())
>>> h10.update(h01.digest())
>>> h10.hexdigest()
'3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa'