Python code coverage for Lib/hashlib.py

#	count	content
1	n/a	#. Copyright (C) 2005-2010 Gregory P. Smith (greg@krypto.org)
2	n/a	# Licensed to PSF under a Contributor Agreement.
3	n/a	#
4	n/a
5	n/a	__doc__ = """hashlib module - A common interface to many hash functions.
6	n/a
7	n/a	new(name, data=b'', **kwargs) - returns a new hash object implementing the
8	n/a	given hash function; initializing the hash
9	n/a	using the given binary data.
10	n/a
11	n/a	Named constructor functions are also available, these are faster
12	n/a	than using new(name):
13	n/a
14	n/a	md5(), sha1(), sha224(), sha256(), sha384(), sha512(), blake2b(), blake2s(),
15	n/a	sha3_224, sha3_256, sha3_384, sha3_512, shake_128, and shake_256.
16	n/a
17	n/a	More algorithms may be available on your platform but the above are guaranteed
18	n/a	to exist. See the algorithms_guaranteed and algorithms_available attributes
19	n/a	to find out what algorithm names can be passed to new().
20	n/a
21	n/a	NOTE: If you want the adler32 or crc32 hash functions they are available in
22	n/a	the zlib module.
23	n/a
24	n/a	Choose your hash function wisely. Some have known collision weaknesses.
25	n/a	sha384 and sha512 will be slow on 32 bit platforms.
26	n/a
27	n/a	Hash objects have these methods:
28	n/a	- update(arg): Update the hash object with the bytes in arg. Repeated calls
29	n/a	are equivalent to a single call with the concatenation of all
30	n/a	the arguments.
31	n/a	- digest(): Return the digest of the bytes passed to the update() method
32	n/a	so far.
33	n/a	- hexdigest(): Like digest() except the digest is returned as a unicode
34	n/a	object of double length, containing only hexadecimal digits.
35	n/a	- copy(): Return a copy (clone) of the hash object. This can be used to
36	n/a	efficiently compute the digests of strings that share a common
37	n/a	initial substring.
38	n/a
39	n/a	For example, to obtain the digest of the string 'Nobody inspects the
40	n/a	spammish repetition':
41	n/a
42	n/a	>>> import hashlib
43	n/a	>>> m = hashlib.md5()
44	n/a	>>> m.update(b"Nobody inspects")
45	n/a	>>> m.update(b" the spammish repetition")
46	n/a	>>> m.digest()
47	n/a	b'\\xbbd\\x9c\\x83\\xdd\\x1e\\xa5\\xc9\\xd9\\xde\\xc9\\xa1\\x8d\\xf0\\xff\\xe9'
48	n/a
49	n/a	More condensed:
50	n/a
51	n/a	>>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest()
52	n/a	'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
53	n/a
54	n/a	"""
55	n/a
56	n/a	# This tuple and __get_builtin_constructor() must be modified if a new
57	n/a	# always available algorithm is added.
58	n/a	__always_supported = ('md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512',
59	n/a	'blake2b', 'blake2s',
60	n/a	'sha3_224', 'sha3_256', 'sha3_384', 'sha3_512',
61	n/a	'shake_128', 'shake_256')
62	n/a
63	n/a
64	n/a	algorithms_guaranteed = set(__always_supported)
65	n/a	algorithms_available = set(__always_supported)
66	n/a
67	n/a	__all__ = __always_supported + ('new', 'algorithms_guaranteed',
68	n/a	'algorithms_available', 'pbkdf2_hmac')
69	n/a
70	n/a
71	n/a	__builtin_constructor_cache = {}
72	n/a
73	n/a	def __get_builtin_constructor(name):
74	n/a	cache = __builtin_constructor_cache
75	n/a	constructor = cache.get(name)
76	n/a	if constructor is not None:
77	n/a	return constructor
78	n/a	try:
79	n/a	if name in ('SHA1', 'sha1'):
80	n/a	import _sha1
81	n/a	cache['SHA1'] = cache['sha1'] = _sha1.sha1
82	n/a	elif name in ('MD5', 'md5'):
83	n/a	import _md5
84	n/a	cache['MD5'] = cache['md5'] = _md5.md5
85	n/a	elif name in ('SHA256', 'sha256', 'SHA224', 'sha224'):
86	n/a	import _sha256
87	n/a	cache['SHA224'] = cache['sha224'] = _sha256.sha224
88	n/a	cache['SHA256'] = cache['sha256'] = _sha256.sha256
89	n/a	elif name in ('SHA512', 'sha512', 'SHA384', 'sha384'):
90	n/a	import _sha512
91	n/a	cache['SHA384'] = cache['sha384'] = _sha512.sha384
92	n/a	cache['SHA512'] = cache['sha512'] = _sha512.sha512
93	n/a	elif name in ('blake2b', 'blake2s'):
94	n/a	import _blake2
95	n/a	cache['blake2b'] = _blake2.blake2b
96	n/a	cache['blake2s'] = _blake2.blake2s
97	n/a	elif name in {'sha3_224', 'sha3_256', 'sha3_384', 'sha3_512',
98	n/a	'shake_128', 'shake_256'}:
99	n/a	import _sha3
100	n/a	cache['sha3_224'] = _sha3.sha3_224
101	n/a	cache['sha3_256'] = _sha3.sha3_256
102	n/a	cache['sha3_384'] = _sha3.sha3_384
103	n/a	cache['sha3_512'] = _sha3.sha3_512
104	n/a	cache['shake_128'] = _sha3.shake_128
105	n/a	cache['shake_256'] = _sha3.shake_256
106	n/a	except ImportError:
107	n/a	pass # no extension module, this hash is unsupported.
108	n/a
109	n/a	constructor = cache.get(name)
110	n/a	if constructor is not None:
111	n/a	return constructor
112	n/a
113	n/a	raise ValueError('unsupported hash type ' + name)
114	n/a
115	n/a
116	n/a	def __get_openssl_constructor(name):
117	n/a	if name in {'blake2b', 'blake2s'}:
118	n/a	# Prefer our blake2 implementation.
119	n/a	return __get_builtin_constructor(name)
120	n/a	try:
121	n/a	f = getattr(_hashlib, 'openssl_' + name)
122	n/a	# Allow the C module to raise ValueError. The function will be
123	n/a	# defined but the hash not actually available thanks to OpenSSL.
124	n/a	f()
125	n/a	# Use the C function directly (very fast)
126	n/a	return f
127	n/a	except (AttributeError, ValueError):
128	n/a	return __get_builtin_constructor(name)
129	n/a
130	n/a
131	n/a	def __py_new(name, data=b'', **kwargs):
132	n/a	"""new(name, data=b'', **kwargs) - Return a new hashing object using the
133	n/a	named algorithm; optionally initialized with data (which must be bytes).
134	n/a	"""
135	n/a	return __get_builtin_constructor(name)(data, **kwargs)
136	n/a
137	n/a
138	n/a	def __hash_new(name, data=b'', **kwargs):
139	n/a	"""new(name, data=b'') - Return a new hashing object using the named algorithm;
140	n/a	optionally initialized with data (which must be bytes).
141	n/a	"""
142	n/a	if name in {'blake2b', 'blake2s'}:
143	n/a	# Prefer our blake2 implementation.
144	n/a	# OpenSSL 1.1.0 comes with a limited implementation of blake2b/s.
145	n/a	# It does neither support keyed blake2 nor advanced features like
146	n/a	# salt, personal, tree hashing or SSE.
147	n/a	return __get_builtin_constructor(name)(data, **kwargs)
148	n/a	try:
149	n/a	return _hashlib.new(name, data)
150	n/a	except ValueError:
151	n/a	# If the _hashlib module (OpenSSL) doesn't support the named
152	n/a	# hash, try using our builtin implementations.
153	n/a	# This allows for SHA224/256 and SHA384/512 support even though
154	n/a	# the OpenSSL library prior to 0.9.8 doesn't provide them.
155	n/a	return __get_builtin_constructor(name)(data)
156	n/a
157	n/a
158	n/a	try:
159	n/a	import _hashlib
160	n/a	new = __hash_new
161	n/a	__get_hash = __get_openssl_constructor
162	n/a	algorithms_available = algorithms_available.union(
163	n/a	_hashlib.openssl_md_meth_names)
164	n/a	except ImportError:
165	n/a	new = __py_new
166	n/a	__get_hash = __get_builtin_constructor
167	n/a
168	n/a	try:
169	n/a	# OpenSSL's PKCS5_PBKDF2_HMAC requires OpenSSL 1.0+ with HMAC and SHA
170	n/a	from _hashlib import pbkdf2_hmac
171	n/a	except ImportError:
172	n/a	_trans_5C = bytes((x ^ 0x5C) for x in range(256))
173	n/a	_trans_36 = bytes((x ^ 0x36) for x in range(256))
174	n/a
175	n/a	def pbkdf2_hmac(hash_name, password, salt, iterations, dklen=None):
176	n/a	"""Password based key derivation function 2 (PKCS #5 v2.0)
177	n/a
178	n/a	This Python implementations based on the hmac module about as fast
179	n/a	as OpenSSL's PKCS5_PBKDF2_HMAC for short passwords and much faster
180	n/a	for long passwords.
181	n/a	"""
182	n/a	if not isinstance(hash_name, str):
183	n/a	raise TypeError(hash_name)
184	n/a
185	n/a	if not isinstance(password, (bytes, bytearray)):
186	n/a	password = bytes(memoryview(password))
187	n/a	if not isinstance(salt, (bytes, bytearray)):
188	n/a	salt = bytes(memoryview(salt))
189	n/a
190	n/a	# Fast inline HMAC implementation
191	n/a	inner = new(hash_name)
192	n/a	outer = new(hash_name)
193	n/a	blocksize = getattr(inner, 'block_size', 64)
194	n/a	if len(password) > blocksize:
195	n/a	password = new(hash_name, password).digest()
196	n/a	password = password + b'\x00' * (blocksize - len(password))
197	n/a	inner.update(password.translate(_trans_36))
198	n/a	outer.update(password.translate(_trans_5C))
199	n/a
200	n/a	def prf(msg, inner=inner, outer=outer):
201	n/a	# PBKDF2_HMAC uses the password as key. We can re-use the same
202	n/a	# digest objects and just update copies to skip initialization.
203	n/a	icpy = inner.copy()
204	n/a	ocpy = outer.copy()
205	n/a	icpy.update(msg)
206	n/a	ocpy.update(icpy.digest())
207	n/a	return ocpy.digest()
208	n/a
209	n/a	if iterations < 1:
210	n/a	raise ValueError(iterations)
211	n/a	if dklen is None:
212	n/a	dklen = outer.digest_size
213	n/a	if dklen < 1:
214	n/a	raise ValueError(dklen)
215	n/a
216	n/a	dkey = b''
217	n/a	loop = 1
218	n/a	from_bytes = int.from_bytes
219	n/a	while len(dkey) < dklen:
220	n/a	prev = prf(salt + loop.to_bytes(4, 'big'))
221	n/a	# endianess doesn't matter here as long to / from use the same
222	n/a	rkey = int.from_bytes(prev, 'big')
223	n/a	for i in range(iterations - 1):
224	n/a	prev = prf(prev)
225	n/a	# rkey = rkey ^ prev
226	n/a	rkey ^= from_bytes(prev, 'big')
227	n/a	loop += 1
228	n/a	dkey += rkey.to_bytes(inner.digest_size, 'big')
229	n/a
230	n/a	return dkey[:dklen]
231	n/a
232	n/a	try:
233	n/a	# OpenSSL's scrypt requires OpenSSL 1.1+
234	n/a	from _hashlib import scrypt
235	n/a	except ImportError:
236	n/a	pass
237	n/a
238	n/a
239	n/a	for __func_name in __always_supported:
240	n/a	# try them all, some may not work due to the OpenSSL
241	n/a	# version not supporting that algorithm.
242	n/a	try:
243	n/a	globals()[__func_name] = __get_hash(__func_name)
244	n/a	except ValueError:
245	n/a	import logging
246	n/a	logging.exception('code for hash %s was not found.', __func_name)
247	n/a
248	n/a
249	n/a	# Cleanup locals()
250	n/a	del __always_supported, __func_name, __get_hash
251	n/a	del __py_new, __hash_new, __get_openssl_constructor