Python标准库hashlib安全哈希与消息摘要

哈希算法¶

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

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

例如，如果想获取字节串 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.digest_size
32
>>> m.block_size
64

更简要的写法：

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

hashlib.new(name[, data])¶

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

使用 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() 时将可被识别。 algorithms_guaranteed 将总是它的一个子集。 同样的算法在此集合中可能以不同的名称出现多次（这是 OpenSSL 的原因）。

3.2 新版功能.

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

hash.digest_size¶

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

hash.block_size¶

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

hash 对象具有以下属性：

hash.name¶

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

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

哈希对象具有下列方法:

hash.update(data)¶

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

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

hash.digest()¶

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

hash.hexdigest()¶

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

hash.copy()¶

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

SHAKE 可变长度摘要¶

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

shake.digest(length)¶

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

shake.hexdigest(length)¶

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

密钥派生¶

密钥派生和密钥延展算法被设计用于安全密码哈希。 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 应当为适当来源例如 os.urandom() 的大约 16 个或更多的字节串数据。

iterations 数值应当基于哈希算法和算力来选择。 在 2013 年时，建议至少为 100,000 次 SHA-256 迭代。

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

>>> importhashlib,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)¶

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

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

n 为 CPU/内存开销因子，r 为块大小，p 为并行化因子，maxmem 为内存限制 (OpenSSL 1.1.0 默认为 32 MiB)。 dklen 为派生密钥的长度。

可用性: OpenSSL 1.1+。

3.6 新版功能.

BLAKE2¶

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

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

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

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

此模块的哈希对象遵循标准库 hashlib 对象的 API。

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