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

哈希算法?

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

此模塊中總是可用的哈希算法構(gòu)造器有 sha1(), sha224(), sha256(), sha384(), sha512(), blake2b() 和 blake2s()。 md5() 通常也是可用的，但如果你在使用少見的 "FIPS 兼容" 的 Python 編譯版本則可能會(huì)找不到它。 此外還可能有一些附加的算法，具體取決于你的平臺(tái)上的 Python 所使用的 OpenSSL 庫。 在大部分平臺(tái)上可用的還有 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'

更簡(jiǎn)要的寫法：

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

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

一個(gè)接受所希望的算法對(duì)應(yīng)的字符串 name 作為第一個(gè)形參的通用構(gòu)造器。 它還允許訪問上面列出的哈希算法以及你的 OpenSSL 庫可能提供的任何其他算法。 同名的構(gòu)造器要比 new() 更快所以應(yīng)當(dāng)優(yōu)先使用。

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

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

Hashlib 提供下列常量屬性：

hashlib.algorithms_guaranteed?

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

3.2 新版功能.

hashlib.algorithms_available?

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

3.2 新版功能.

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

hash.digest_size?

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

hash.block_size?

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

hash 對(duì)象具有以下屬性：

hash.name?

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

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

哈希對(duì)象具有下列方法:

hash.update(data)?

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

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

hash.digest()?

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

hash.hexdigest()?

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

hash.copy()?

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

SHAKE 可變長(zhǎng)度摘要?

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

shake.digest(length)?

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

shake.hexdigest(length)?

類似于 digest() 但摘要會(huì)以兩倍長(zhǎng)度字符串對(duì)象的形式返回，其中僅包含十六進(jìn)制數(shù)碼。 這可以被用于在電子郵件或其他非二進(jìn)制環(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 新版功能.

密鑰派生?

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

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

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

字符串 hash_name 是要求用于 HMAC 的哈希摘要算法的名稱，例如 'sha1' 或 'sha256'。 password 和 salt 會(huì)以字節(jié)串緩沖區(qū)的形式被解析。 應(yīng)用和庫應(yīng)當(dāng)將 password 限制在合理長(zhǎng)度 (例如 1024)。 salt 應(yīng)當(dāng)為適當(dāng)來源例如 os.urandom() 的大約 16 個(gè)或更多的字節(jié)串?dāng)?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 為派生密鑰的長(zhǎng)度。 如果 dklen 為 None 則會(huì)使用哈希算法 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 提供了一個(gè)快速的 pbkdf2_hmac 實(shí)現(xiàn)。 Python 實(shí)現(xiàn)是使用 hmac 的內(nèi)聯(lián)版本。 它的速度大約要慢上三倍并且不會(huì)釋放 GIL。

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

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

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

password 和 salt 必須為 字節(jié)類對(duì)象。 應(yīng)用和庫應(yīng)當(dāng)將 password 限制在合理長(zhǎng)度 (例如 1024)。 salt 應(yīng)當(dāng)為適當(dāng)來源例如 os.urandom() 的大約 16 個(gè)或更多的字節(jié)串?dāng)?shù)據(jù)。

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

3.6 新版功能.

BLAKE2?

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

• BLAKE2b，針對(duì) 64 位平臺(tái)進(jìn)行優(yōu)化，并會(huì)生成長(zhǎng)度介于 1 和 64 字節(jié)之間任意大小的摘要。

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

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

此模塊的哈希對(duì)象遵循標(biāo)準(zhǔn)庫 hashlib 對(duì)象的 API。

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

新哈希對(duì)象可通過調(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ù)返回用于計(jì)算 BLAKE2b 或 BLAKE2s 的相應(yīng)的哈希對(duì)象。 它們接受下列可選通用形參:

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

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

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

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

• person: 個(gè)性化字符串（對(duì)于 BLAKE2b 最長(zhǎng) 16 字節(jié)，對(duì)于 BLAKE2s 最長(zhǎng) 8 字節(jié)）。

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

Hash	目標(biāo)長(zhǎng)度	長(zhǎng)度（鍵）	長(zhǎng)度（鹽）	長(zhǎng)度（個(gè)人）
BLAKE2b	64	64	16	16
BLAKE2s	32	32	8	8

備注

BLAKE2 規(guī)格描述為鹽值和個(gè)性化形參定義了固定的長(zhǎng)度，但是為了方便起見，此實(shí)現(xiàn)接受指定在長(zhǎng)度以內(nèi)的任意大小的字節(jié)串。 如果形參長(zhǎng)度小于指定值，它將以零值進(jìn)行填充，因此舉例來說，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é)點(diǎn)深度 (0 至 255，對(duì)于葉子或在連續(xù)模式下則為 0)。

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

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

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

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