雜湊演算法¶

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

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

此模組中始終存在的雜湊演算法之建構函式有sha1()、sha224()、sha256()、sha384()、sha512()、sha3_224()、sha3_256()、sha3_384()、sha3_512()、shake_128()、shake_256()、blake2b() 和blake2s()。md5() 通常也可用，但如果你使用罕見的「符合 FIPS (FIPS compliant)」的 Python 建置版本，它可能不存在或者不被允許使用。以上會對應到algorithms_guaranteed。

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

用法¶

取得位元組字串b"Nobodyinspectsthespammishrepetition" 的摘要：

>>>importhashlib>>>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 的雜湊演算法、雜湊建構函式或會回傳雜湊物件的可呼叫函式。

範例：

>>>importio,hashlib,hmac>>>withopen(hashlib.__file__,"rb")asf:...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)

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

在 3.11 版被加入.

在 3.13.3 (unreleased) 版的變更:Now raises aBlockingIOError if the file is opened in blockingmode. Previously, spurious null bytes were added to the digest.

密鑰的生成¶

密鑰生成 (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。

>>>fromhashlibimportpbkdf2_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 節。

>>>fromhashlibimportblake2b>>>h=blake2b()>>>h.update(b'Hello world')>>>h.hexdigest()'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

>>>fromhashlibimportblake2b>>>blake2b(b'Hello world').hexdigest()'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

>>>fromhashlibimportblake2b>>>items=[b'Hello',b' ',b'world']>>>h=blake2b()>>>foriteminitems:...h.update(item)...>>>h.hexdigest()'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

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

>>>fromhashlibimportblake2b,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'

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

>>>fromhashlibimportblake2b>>>fromhmacimportcompare_digest>>>>>>SECRET_KEY=b'pseudorandomly generated server secret key'>>>AUTH_SIZE=16>>>>>>defsign(cookie):...h=blake2b(digest_size=AUTH_SIZE,key=SECRET_KEY)...h.update(cookie)...returnh.hexdigest().encode('utf-8')>>>>>>defverify(cookie,sig):...good_sig=sign(cookie)...returncompare_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

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

>>>importos>>>fromhashlibimportblake2b>>>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

>>>fromhashlibimportblake2b>>>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'

>>>fromhashlibimportblake2s>>>frombase64importb64decode,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/  \0001

>>>fromhashlibimportblake2b>>>>>>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'