15.1. hashlib — 安全哈希与消息摘要

这个模块针对不同的安全哈希和消息摘要算法实现了一个通用的接口。包括 FIPS 的 SHA1, SHA224, SHA256, SHA384, and SHA512 (定义于 FIPS 180-2) 算法，以及 RSA 的 MD5 算法( 定义于 Internet )。术语“安全哈希”和“消息摘要”是可互换的，较旧的算法被称为消息摘要，现代术语是安全哈希。

注解

如果你想找到 adler32 或 crc32 哈希函数，它们在 zlib 模块中。

警告

有些算法已知存在哈希碰撞弱点，请参考最后的“另请参阅”段。

每种类型的 hash 都有一个构造器方法。它们都返回一个具有相同的简单接口的 hash 对象。例如，使用 use 创建一个 SHA-256 hash 对象。你可以使用 update() 方法向这个对象输入 (通常是 bytes)。在任何时候你都可以使用 digest() 或 hexdigest() 方法获得到目前为止输入这个对象的拼接数据的 digest。

注解

为了更好的多线程性能，在对象创建或者更新时，若数据大于2047字节则 Python 的会被释放。

注解

向 update() 输入字符串对象是不被支持的，因为哈希基于字节而非字符。

此模块中总是可用的哈希算法构造器有 sha1(), sha224(), sha256(), sha384(), sha512(), blake2b() 和。 md5() 通常也是可用的，但如果你在使用少见的 “FIPS 兼容” 的 Python 编译版本则可能会找不到它。此外还可能有一些附加的算法，具体取决于你的平台上的 Python 所使用的 OpenSSL 库。在大部分平台上可用的还有 sha3_224(), sha3_256(), sha3_384(), sha3_512(), shake_128(), shake_256() 等等。

3.6 新版功能: SHA3 (Keccak) 和 SHAKE 构造器 sha3_224(), sha3_256(), sha3_384(), sha3_512(), shake_128(), shake_256().

3.6 新版功能: 添加了 blake2b() 和。

例如，如果想获取字节串 b'Nobody inspects the spammish repetition' 的摘要:

更简要的写法：

>>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest()
'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'

hashlib.new(name[, data])

一个接受所希望的算法对应的字符串 name 作为第一个形参的通用构造器。它还允许访问上面列出的哈希算法以及你的 OpenSSL 库可能提供的任何其他算法。同名的构造器要比 new() 更快所以应当优先使用。

使用并附带由 OpenSSL 所提供了算法:

>>> h = hashlib.new('ripemd160')
>>> h.update(b"Nobody inspects the spammish repetition")
>>> h.hexdigest()
'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'

Hashlib 提供下列常量属性：

hashlib.algorithms_guaranteed

一个集合，其中包含此模块在所有平台上都保证支持的哈希算法的名称。请注意 ‘md5’ 也在此清单中，虽然某些上游厂商提供了一个怪异的排除了此算法的 “FIPS 兼容” Python 编译版本。

3.2 新版功能.

hashlib.algorithms_available

一个集合，其中包含在所运行的 Python 解释器上可用的哈希算法的名称。将这些名称传给 new() 时将可被识别。将总是它的一个子集。同样的算法在此集合中可能以不同的名称出现多次（这是 OpenSSL 的原因）。

3.2 新版功能.

下列值会以构造器所返回的哈希对象的常量属性的形式被提供:

hash.digest_size

以字节表示的结果哈希对象的大小。

hash.block_size

以字节表示的哈希算法的内部块大小。

hash 对象具有以下属性：

hash.name

此哈希对象的规范名称，总是为小写形式并且总是可以作为 new() 的形参用来创建另一个此类型的哈希对象。

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

哈希对象具有下列方法:

hash.update(data)

用来更新哈希对象。重复调用相当于单次调用并传入所有参数的拼接结果: m.update(a); m.update(b) 等价于 m.update(a+b)。

在 3.1 版更改: 当使用 OpenSSL 提供的哈希算法在大于 2047 字节的数据上执行哈希更新时 Python GIL 会被释放以允许其他线程运行。

hash.digest()

返回当前已传给 update() 方法的数据摘要。这是一个大小为的字节串对象，字节串中可包含 0 至 255 的完整取值范围。

hash.hexdigest()

类似于 digest() 但摘要会以两倍长度字符串对象的形式返回，其中仅包含十六进制数码。这可以被用于在电子邮件或其他非二进制环境中安全地交换数据值。

hash.copy()

返回哈希对象的副本（“克隆”）。这可被用来高效地计算共享相同初始子串的数据的摘要。

shake_128() 和 shake_256() 算法提供安全的 length_in_bits//2 至 128 或 256 位可变长度摘要。为此，它们的摘要需指定一个长度。 SHAKE 算法不限制最大长度。

shake.digest(length)

返回当前已传给 update() 方法的数据摘要。这是一个大小为 length 的字节串对象，字节串中可包含 0 to 255 的完整取值范围。

shake.hexdigest(length)

类似于但摘要会以两倍长度字符串对象的形式返回，其中仅包含十六进制数码。这可以被用于在电子邮件或其他非二进制环境中安全地交换数据值。

密钥派生和密钥延展算法被设计用于安全密码哈希。 sha1(password) 这样的简单算法无法防御暴力攻击。好的密码哈希函数必须可以微调、放慢步调，并且包含加盐。

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

此函数提供 PKCS#5 基于密码的密钥派生函数 2。它使用 HMAC 作为伪随机函数。

字符串 hash_name 是要求用于 HMAC 的哈希摘要算法的名称，例如 ‘sha1’ 或 ‘sha256’。 password 和 salt 会以字节串缓冲区的形式被解析。应用和库应当将 password 限制在合理长度 (例如 1024)。 salt 应当为适当来源例如的大约 16 个或更多的字节串数据。

dklen 为派生密钥的长度。如果 dklen 为 None 则会使用哈希算法 hash_name 的摘要大小，例如 SHA-512 为 64。

>>> import hashlib, binascii
>>> dk = hashlib.pbkdf2_hmac('sha256', b'password', b'salt', 100000)
>>> binascii.hexlify(dk)
b'0394a2ede332c9a13eb82e9b24631604c31df978b4e2f0fbd2c549944f9d79a5'

3.4 新版功能.

注解

随同 OpenSSL 提供了一个快速的 pbkdf2_hmac 实现。 Python 实现是使用 hmac 的内联版本。它的速度大约要慢上三倍并且不会释放 GIL。

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

此函数提供基于密码加密的密钥派生函数，其定义参见。

password 和 salt 必须为字节类对象。应用和库应当将 password 限制在合理长度 (例如 1024)。 salt 应当为适当来源例如的大约 16 个或更多的字节串数据。

n is the CPU/Memory cost factor, r the block size, p parallelization factor and maxmem limits memory (OpenSSL 1.1.0 defaults to 32 MB). dklen is the length of the derived key.

Availability: OpenSSL 1.1+

3.6 新版功能.

BLAKE2 是在中定义的加密哈希函数，它有两种形式:

BLAKE2b，针对 64 位平台进行优化，并会生成长度介于 1 和 64 字节之间任意大小的摘要。
BLAKE2s，针对 8 至 32 位平台进行优化，并会生成长度介于 1 和 32 字节之间任意大小的摘要。

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

此模块的哈希对象遵循标准库对象的 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*)

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

这些函数返回用于计算 BLAKE2b 或 BLAKE2s 的相应的哈希对象。它们接受下列可选通用形参:

data: 要哈希的初始数据块，它必须为 bytes-like object。它只能作为位置参数传入。
digest_size: 以字节数表示的输出摘要大小。
key: 用于密钥哈希的密钥（对于 BLAKE2b 最多 64 字节，对于 BLAKE2s 最多 32 字节）。
salt: 用于随机哈希的盐值（对于 BLAKE2b 最长 16 字节，对于 BLAKE2s 最长 8 字节）。
person: 个性化字符串（对于 BLAKE2b 最长 16 字节，对于 BLAKE2s 最长 8 字节）。

下表显示了常规参数的限制（以字节为单位）：

注解

BLAKE2 规格描述为盐值和个性化形参定义了固定的长度，但是为了方便起见，此实现接受指定在长度以内的任意大小的字节串。如果形参长度小于指定值，它将以零值进行填充，因此举例来说，和 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 至 264-1，对于 BLAKE2s 为 0 至 248-1，对于最左边第一个叶子或在连续模式下则为 0)。
node_depth: 节点深度 (0 至 255，对于叶子或在连续模式下则为 0)。
inner_size: 内部摘要大小 (对于 BLAKE2b 为 0 至 64，对于 BLAKE2s 为 0 至 32，连续模式下则为 0)。
last_node: 一个布尔值，指明所处理的节点是否为最后一个 (连续模式下则为 False)。

请参阅 BLAKE2 规格描述第 2.10 节了解有关树形哈希的完整介绍。

blake2s.SALT_SIZE

盐值长度（构造器所接受的最大长度）。

blake2b.PERSON_SIZE

blake2s.PERSON_SIZE

盐值长度（构造器所接受的最大长度）。

blake2b.MAX_KEY_SIZE

blake2s.MAX_KEY_SIZE

最大密钥长度。

blake2b.MAX_DIGEST_SIZE

blake2s.MAX_DIGEST_SIZE

哈希函数可输出的最大摘要长度。

15.1.4.3.1. 简单哈希

要计算某个数据的哈希值，你应该首先通过调用适当的构造器函数 (blake2b() 或 ) 来构造一个哈希对象，然后通过在该对象上调用 update() 来更新目标数据，最后通过调用 digest() (或针对十六进制编码字符串的 hexdigest()) 来获取该对象的摘要。

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

作为快捷方式，你可以直接以位置参数的形式向构造器传入第一个数据块来直接更新:

你可以多次调用 hash.update() 至你所想要的任意次数以迭代地更新哈希值:

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

15.1.4.3.2. 使用不同的摘要大小

BLAKE2 具有可配置的摘要大小，对于 BLAKE2b 最多 64 字节，对于 BLAKE2s 最多 32 字节。例如，要使用 BLAKE2b 来替代 SHA-1 而不改变输出大小，我们可以让 BLAKE2b 产生 20 个字节的摘要:

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

不同摘要大小的哈希对象具有完全不同的输出（较短哈希值并非较长哈希值的前缀）；即使输出长度相同，BLAKE2b 和 BLAKE2s 也会产生不同的输出:

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

15.1.4.3.3. 密钥哈希

Keyed hashing can be used for authentication as a faster and simpler replacement for (HMAC). BLAKE2 can be securely used in prefix-MAC mode thanks to the indifferentiability property inherited from BLAKE.

这个例子演示了如何使用密钥 b'pseudorandom key' 来为 b'message data' 获取一个（十六进制编码的）128 位验证代码:

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

作为实际的例子，一个 Web 应用可为发送给用户的 cookies 进行对称签名，并在之后对其进行验证以确保它们没有被篡改:

即使存在原生的密钥哈希模式，BLAKE2 也同样可在 hmac 模块的 HMAC 构造过程中使用:

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

15.1.4.3.4. 随机哈希

用户可通过设置 salt 形参来为哈希函数引入随机化。随机哈希适用于防止对数字签名中使用的哈希函数进行碰撞攻击。

在 BLAKE2 中，盐值会在初始化期间作为对哈希函数的一次性输入而不是对每个压缩函数的输入来处理。

警告

使用 BLAKE2 或任何其他通用加密哈希函数例如 SHA-256 进行 加盐哈希 (或纯哈希) 并不适用于哈希密码。请参阅 BLAKE2 FAQ 了解更多信息。

>>> import os
>>> from hashlib import blake2b
>>> # 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()

15.1.4.3.5. 个性化

出于不同的目的强制让哈希函数为相同的输入生成不同的摘要有时也是有用的。正如 Skein 哈希函数的作者所言:

BLAKE2 可通过向 person 参数传入字节串来进行个性化:

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

15.1.4.3.6. 树形模式

以下是对包含两个叶子节点的最小树进行哈希的例子:

这个例子使用 64 字节内部摘要，返回 32 字节最终摘要:

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

是由 Jean-Philippe Aumasson, Samuel Neves, Zooko Wilcox-O’Hearn 和 Christian Winnerlein 基于 Jean-Philippe Aumasson, Luca Henzen, Willi Meier 和 Raphael C.-W. Phan 所创造的 SHA-3 入围方案进行设计的。

它使用的核心算法来自由 Daniel J. Bernstein 所设计的 ChaCha 加密。

stdlib 实现是基于模块的。它由 Dmitry Chestnykh 在 Samuel Neves 所编写的 C 实现的基础上编写。此文档拷贝自 pyblake2 并由 Dmitry Chestnykh 撰写。

C 代码由 Christian Heimes 针对 Python 进行了部分的重写。

以下公共领域贡献同时适用于 C 哈希函数实现、扩展代码和本文档:

根据创意分享公共领域贡献 1.0 通用规范，下列人士为此项目的开发提供了帮助或对公共领域的修改作出了贡献:

参见

模块

使用哈希运算来生成消息验证代码的模块。

模块 base64

针对非二进制环境对二进制哈希值进行编辑的另一种方式。

BLAKE2 官方网站

http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf

有关安全哈希算法的 FIPS 180-2 出版物。

包含关于哪些算法存在已知问题以及对其使用所造成的影响的信息的 Wikipedia 文章。

https://www.ietf.org/rfc/rfc2898.txt