hashlib --- 安全哈希與消息摘要?

哈希算法?

每種類型的 hash 都有一個構(gòu)造器方法。 它們都返回一個具有相同的簡單接口的 hash 對象。 例如，使用 use sha256() 創(chuàng)建一個 SHA-256 hash 對象。 你可以使用 update() 方法向這個對象輸入 字節(jié)類對象 (通常是 bytes)。 在任何時候你都可以使用 digest() 或 hexdigest() 方法獲得到目前為止輸入這個對象的拼接數(shù)據(jù)的 digest。

此模塊中總是可用的哈希算法構(gòu)造器有 sha1(), sha224(), sha256(), sha384(), sha512(), blake2b() 和 blake2s()。 md5() 通常也是可用的，但如果你在使用少見的 "FIPS 兼容" 的 Python 編譯版本則可能會找不到它。 此外還可能有一些附加的算法，具體取決于你的平臺上的 Python 所使用的 OpenSSL 庫。 在大部分平臺上可用的還有 sha3_224(), sha3_256(), sha3_384(), sha3_512(), shake_128(), shake_256() 等等?！?/p>

For example, to obtain the digest of the byte string 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 作為第一個形參的通用構(gòu)造器。 它還允許訪問上面列出的哈希算法以及你的 OpenSSL 庫可能提供的任何其他算法。 同名的構(gòu)造器要比 new() 更快所以應當優(yōu)先使用。

使用 new() 并附帶由 OpenSSL 所提供了算法:

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

Hashlib 提供下列常量屬性：

hashlib.algorithms_guaranteed?

一個集合，其中包含此模塊在所有平臺上都保證支持的哈希算法的名稱。 請注意 'md5' 也在此清單中，雖然某些上游廠商提供了一個怪異的排除了此算法的 "FIPS 兼容" Python 編譯版本。

3.2 新版功能.

hashlib.algorithms_available?

一個集合，其中包含在所運行的 Python 解釋器上可用的哈希算法的名稱。 將這些名稱傳給 new() 時將可被識別。 algorithms_guaranteed 將總是它的一個子集。 同樣的算法在此集合中可能以不同的名稱出現(xiàn)多次（這是 OpenSSL 的原因）。

3.2 新版功能.

下列值會以構(gòu)造器所返回的哈希對象的常量屬性的形式被提供:

hash.digest_size?

以字節(jié)表示的結(jié)果哈希對象的大小。

hash.block_size?

以字節(jié)表示的哈希算法的內(nèi)部塊大小。

hash 對象具有以下屬性：

hash.name?

此哈希對象的規(guī)范名稱，總是為小寫形式并且總是可以作為 new() 的形參用來創(chuàng)建另一個此類型的哈希對象。

在 3.4 版更改: 該屬性名稱自被引入起即存在于 CPython 中，但在 Python 3.4 之前并未正式指明，因此可能不存在于某些平臺上。

哈希對象具有下列方法:

hash.update(data)?

用 bytes-like object 來更新哈希對象。 重復調(diào)用相當于單次調(diào)用并傳入所有參數(shù)的拼接結(jié)果: m.update(a); m.update(b) 等價于 m.update(a+b)。

在 3.1 版更改: 當使用 OpenSSL 提供的哈希算法在大于 2047 字節(jié)的數(shù)據(jù)上執(zhí)行哈希更新時 Python GIL 會被釋放以允許其他線程運行。

hash.digest()?

返回當前已傳給 update() 方法的數(shù)據(jù)摘要。 這是一個大小為 digest_size 的字節(jié)串對象，字節(jié)串中可包含 0 至 255 的完整取值范圍。

hash.hexdigest()?

類似于 digest() 但摘要會以兩倍長度字符串對象的形式返回，其中僅包含十六進制數(shù)碼。 這可以被用于在電子郵件或其他非二進制環(huán)境中安全地交換數(shù)據(jù)值。

hash.copy()?

返回哈希對象的副本（“克隆”）。 這可被用來高效地計算共享相同初始子串的數(shù)據(jù)的摘要。

SHAKE 可變長度摘要?

shake_128() 和 shake_256() 算法提供安全的 length_in_bits//2 至 128 或 256 位可變長度摘要。 為此，它們的摘要需指定一個長度。 SHAKE 算法不限制最大長度。

shake.digest(length)?

返回當前已傳給 update() 方法的數(shù)據(jù)摘要。 這是一個大小為 length 的字節(jié)串對象，字節(jié)串中可包含 0 to 255 的完整取值范圍。

shake.hexdigest(length)?

類似于 digest() 但摘要會以兩倍長度字符串對象的形式返回，其中僅包含十六進制數(shù)碼。 這可以被用于在電子郵件或其他非二進制環(huán)境中安全地交換數(shù)據(jù)值。

File hashing?

The hashlib module provides a helper function for efficient hashing of a file or file-like object.

hashlib.file_digest(fileobj, digest, /)?

Return a digest object that has been updated with contents of file object.

fileobj must be a file-like object opened for reading in binary mode. It accepts file objects from builtin open(), BytesIO instances, SocketIO objects from socket.socket.makefile(), and similar. The function may bypass Python's I/O and use the file descriptor from fileno() directly. fileobj must be assumed to be in an unknown state after this function returns or raises. It is up to the caller to close fileobj.

digest must either be a hash algorithm name as a str, a hash constructor, or a callable that returns a hash object.

Example:

>>>

>>> import io, hashlib, hmac
>>> with open(hashlib.__file__, "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 新版功能.

密鑰派生?

密鑰派生和密鑰延展算法被設計用于安全密碼哈希。 sha1(password) 這樣的簡單算法無法防御暴力攻擊。 好的密碼哈希函數(shù)必須可以微調(diào)、放慢步調(diào)，并且包含 加鹽。

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

此函數(shù)提供 PKCS#5 基于密碼的密鑰派生函數(shù) 2。 它使用 HMAC 作為偽隨機函數(shù)。

字符串 hash_name 是要求用于 HMAC 的哈希摘要算法的名稱，例如 'sha1' 或 'sha256'。 password 和 salt 會以字節(jié)串緩沖區(qū)的形式被解析。 應用和庫應當將 password 限制在合理長度 (例如 1024)。 salt 應當為適當來源例如 os.urandom() 的大約 16 個或更多的字節(jié)串數(shù)據(jù)。

The number of iterations should be chosen based on the hash algorithm and computing power. As of 2022, hundreds of thousands of iterations of SHA-256 are suggested. For rationale as to why and how to choose what is best for your application, read Appendix A.2.2 of NIST-SP-800-132. The answers on the stackexchange pbkdf2 iterations question explain in detail.

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'

3.4 新版功能.

備注

隨同 OpenSSL 提供了一個快速的 pbkdf2_hmac 實現(xiàn)。 Python 實現(xiàn)是使用 hmac 的內(nèi)聯(lián)版本。 它的速度大約要慢上三倍并且不會釋放 GIL。

3.10 版后已移除: 較慢的 pbkdf2_hmac Python 實現(xiàn)已被棄用。 未來該函數(shù)將僅在 Python 附帶 OpenSSL 編譯時可用。

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

此函數(shù)提供基于密碼加密的密鑰派生函數(shù)，其定義參見 RFC 7914。

password 和 salt 必須為 字節(jié)類對象。 應用和庫應當將 password 限制在合理長度 (例如 1024)。 salt 應當為適當來源例如 os.urandom() 的大約 16 個或更多的字節(jié)串數(shù)據(jù)。

n 為 CPU/內(nèi)存開銷因子，r 為塊大小，p 為并行化因子，maxmem 為內(nèi)存限制 (OpenSSL 1.1.0 默認為 32 MiB)。 dklen 為派生密鑰的長度。

3.6 新版功能.

BLAKE2?

BLAKE2 是在 RFC 7693 中定義的加密哈希函數(shù)，它有兩種形式:

• BLAKE2b，針對 64 位平臺進行優(yōu)化，并會生成長度介于 1 和 64 字節(jié)之間任意大小的摘要。

• BLAKE2s，針對 8 至 32 位平臺進行優(yōu)化，并會生成長度介于 1 和 32 字節(jié)之間任意大小的摘要。

BLAKE2 支持 keyed mode (HMAC 的更快速更簡單的替代), salted hashing, personalization 和 tree hashing.

此模塊的哈希對象遵循標準庫 hashlib 對象的 API。

創(chuàng)建哈希對象?

新哈希對象可通過調(diào)用構(gòu)造器函數(shù)來創(chuàng)建:

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)?

這些函數(shù)返回用于計算 BLAKE2b 或 BLAKE2s 的相應的哈希對象。 它們接受下列可選通用形參:

• data: 要哈希的初始數(shù)據(jù)塊，它必須為 bytes-like object。 它只能作為位置參數(shù)傳入。

• digest_size: 以字節(jié)數(shù)表示的輸出摘要大小。

• key: 用于密鑰哈希的密鑰（對于 BLAKE2b 最長 64 字節(jié)，對于 BLAKE2s 最長 32 字節(jié)）。

• salt: 用于隨機哈希的鹽值（對于 BLAKE2b 最長 16 字節(jié)，對于 BLAKE2s 最長 8 字節(jié)）。

• person: 個性化字符串（對于 BLAKE2b 最長 16 字節(jié)，對于 BLAKE2s 最長 8 字節(jié)）。

下表顯示了常規(guī)參數(shù)的限制（以字節(jié)為單位）：

Hash	目標長度	長度（鍵）	長度（鹽）	長度（個人）
BLAKE2b	64	64	16	16
BLAKE2s	32	32	8	8

備注

BLAKE2 規(guī)格描述為鹽值和個性化形參定義了固定的長度，但是為了方便起見，此實現(xiàn)接受指定在長度以內(nèi)的任意大小的字節(jié)串。 如果形參長度小于指定值，它將以零值進行填充，因此舉例來說，b'salt' 和 b'salt\x00' 為相同的值 (key 的情況則并非如此。)

如下面的模塊 constants 所描述，這些是可用的大小取值。

構(gòu)造器函數(shù)還接受下列樹形哈希形參:

• fanout: 扇出值 (0 至 255，如無限制即為 0，連續(xù)模式下為 1)。

• depth: 樹的最大深度 (1 至 255，如無限制則為 255，連續(xù)模式下為 1)。

• leaf_size: maximal byte length of leaf (0 to 2**32-1, 0 if unlimited or in sequential mode).

• node_offset: node offset (0 to 2**64-1 for BLAKE2b, 0 to 2**48-1 for BLAKE2s, 0 for the first, leftmost, leaf, or in sequential mode).

• node_depth: 節(jié)點深度 (0 至 255，對于葉子或在連續(xù)模式下則為 0)。

• inner_size: 內(nèi)部摘要大小 (對于 BLAKE2b 為 0 至 64，對于 BLAKE2s 為 0 至 32，連續(xù)模式下則為 0)。

• last_node: 一個布爾值，指明所處理的節(jié)點是否為最后一個 (連續(xù)模式下則為 False)。

請參閱 BLAKE2 規(guī)格描述 第 2.10 節(jié)獲取有關樹形哈希的完整說明。

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