blob: 58c340d56e3ba510b32c7fabac91fa64982be046 [file] [log] [blame]
Christian Heimes3626a502013-10-19 14:12:02 +02001#. Copyright (C) 2005-2010 Gregory P. Smith (greg@krypto.org)
Gregory P. Smithf21a5f72005-08-21 18:45:59 +00002# Licensed to PSF under a Contributor Agreement.
3#
4
5__doc__ = """hashlib module - A common interface to many hash functions.
6
Christian Heimes121b9482016-09-06 22:03:25 +02007new(name, data=b'', **kwargs) - returns a new hash object implementing the
8 given hash function; initializing the hash
9 using the given binary data.
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000010
Gregory P. Smith2f21eb32007-09-09 06:44:34 +000011Named constructor functions are also available, these are faster
12than using new(name):
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000013
Christian Heimes6fe2a752016-09-07 11:58:24 +020014md5(), sha1(), sha224(), sha256(), sha384(), sha512(), blake2b(), blake2s(),
15sha3_224, sha3_256, sha3_384, sha3_512, shake_128, and shake_256.
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000016
Gregory P. Smith13b55292010-09-06 08:30:23 +000017More algorithms may be available on your platform but the above are guaranteed
18to exist. See the algorithms_guaranteed and algorithms_available attributes
19to find out what algorithm names can be passed to new().
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000020
Christian Heimesd5e2b6f2008-03-19 21:50:51 +000021NOTE: If you want the adler32 or crc32 hash functions they are available in
22the zlib module.
23
Thomas Wouters89f507f2006-12-13 04:49:30 +000024Choose your hash function wisely. Some have known collision weaknesses.
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000025sha384 and sha512 will be slow on 32 bit platforms.
Thomas Wouters89f507f2006-12-13 04:49:30 +000026
27Hash objects have these methods:
Serhiy Storchakaf1d36d82018-07-31 09:50:16 +030028 - update(data): Update the hash object with the bytes in data. Repeated calls
29 are equivalent to a single call with the concatenation of all
30 the arguments.
31 - digest(): Return the digest of the bytes passed to the update() method
32 so far as a bytes object.
33 - hexdigest(): Like digest() except the digest is returned as a string
34 of double length, containing only hexadecimal digits.
35 - copy(): Return a copy (clone) of the hash object. This can be used to
36 efficiently compute the digests of datas that share a common
37 initial substring.
Thomas Wouters89f507f2006-12-13 04:49:30 +000038
Serhiy Storchakaf1d36d82018-07-31 09:50:16 +030039For example, to obtain the digest of the byte string 'Nobody inspects the
Thomas Wouters89f507f2006-12-13 04:49:30 +000040spammish repetition':
41
42 >>> import hashlib
43 >>> m = hashlib.md5()
Guido van Rossume22905a2007-08-27 23:09:25 +000044 >>> m.update(b"Nobody inspects")
45 >>> m.update(b" the spammish repetition")
Thomas Wouters89f507f2006-12-13 04:49:30 +000046 >>> m.digest()
Gregory P. Smith63594502008-08-31 16:35:01 +000047 b'\\xbbd\\x9c\\x83\\xdd\\x1e\\xa5\\xc9\\xd9\\xde\\xc9\\xa1\\x8d\\xf0\\xff\\xe9'
Thomas Wouters89f507f2006-12-13 04:49:30 +000048
49More condensed:
50
Guido van Rossume22905a2007-08-27 23:09:25 +000051 >>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest()
Thomas Wouters89f507f2006-12-13 04:49:30 +000052 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
53
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000054"""
55
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +000056# This tuple and __get_builtin_constructor() must be modified if a new
57# always available algorithm is added.
Christian Heimes121b9482016-09-06 22:03:25 +020058__always_supported = ('md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512',
Christian Heimes6fe2a752016-09-07 11:58:24 +020059 'blake2b', 'blake2s',
60 'sha3_224', 'sha3_256', 'sha3_384', 'sha3_512',
61 'shake_128', 'shake_256')
62
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +000063
Raymond Hettingerbf1d2bc2011-01-24 04:52:27 +000064algorithms_guaranteed = set(__always_supported)
65algorithms_available = set(__always_supported)
Gregory P. Smith86508cc2010-03-01 02:05:26 +000066
Gregory P. Smith13b55292010-09-06 08:30:23 +000067__all__ = __always_supported + ('new', 'algorithms_guaranteed',
Christian Heimes3626a502013-10-19 14:12:02 +020068 'algorithms_available', 'pbkdf2_hmac')
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +000069
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000070
Christian Heimese5351072013-10-22 14:59:12 +020071__builtin_constructor_cache = {}
72
Christian Heimes8a0fe7b2020-06-19 16:11:02 +020073# Prefer our blake2 implementation
74# OpenSSL 1.1.0 comes with a limited implementation of blake2b/s. The OpenSSL
75# implementations neither support keyed blake2 (blake2 MAC) nor advanced
76# features like salt, personalization, or tree hashing. OpenSSL hash-only
77# variants are available as 'blake2b512' and 'blake2s256', though.
Christian Heimes995b5d32019-09-13 15:31:19 +020078__block_openssl_constructor = {
Christian Heimes995b5d32019-09-13 15:31:19 +020079 'blake2b', 'blake2s',
80}
81
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000082def __get_builtin_constructor(name):
Christian Heimese5351072013-10-22 14:59:12 +020083 cache = __builtin_constructor_cache
84 constructor = cache.get(name)
85 if constructor is not None:
86 return constructor
Gregory P. Smith12c9d022011-05-14 15:15:49 -070087 try:
Christian Heimes995b5d32019-09-13 15:31:19 +020088 if name in {'SHA1', 'sha1'}:
Gregory P. Smith12c9d022011-05-14 15:15:49 -070089 import _sha1
Christian Heimese5351072013-10-22 14:59:12 +020090 cache['SHA1'] = cache['sha1'] = _sha1.sha1
Christian Heimes995b5d32019-09-13 15:31:19 +020091 elif name in {'MD5', 'md5'}:
Gregory P. Smith12c9d022011-05-14 15:15:49 -070092 import _md5
Christian Heimese5351072013-10-22 14:59:12 +020093 cache['MD5'] = cache['md5'] = _md5.md5
Christian Heimes995b5d32019-09-13 15:31:19 +020094 elif name in {'SHA256', 'sha256', 'SHA224', 'sha224'}:
Gregory P. Smith12c9d022011-05-14 15:15:49 -070095 import _sha256
Christian Heimese5351072013-10-22 14:59:12 +020096 cache['SHA224'] = cache['sha224'] = _sha256.sha224
97 cache['SHA256'] = cache['sha256'] = _sha256.sha256
Christian Heimes995b5d32019-09-13 15:31:19 +020098 elif name in {'SHA512', 'sha512', 'SHA384', 'sha384'}:
Gregory P. Smith12c9d022011-05-14 15:15:49 -070099 import _sha512
Christian Heimese5351072013-10-22 14:59:12 +0200100 cache['SHA384'] = cache['sha384'] = _sha512.sha384
101 cache['SHA512'] = cache['sha512'] = _sha512.sha512
Christian Heimes995b5d32019-09-13 15:31:19 +0200102 elif name in {'blake2b', 'blake2s'}:
Christian Heimes121b9482016-09-06 22:03:25 +0200103 import _blake2
104 cache['blake2b'] = _blake2.blake2b
105 cache['blake2s'] = _blake2.blake2s
Christian Heimes995b5d32019-09-13 15:31:19 +0200106 elif name in {'sha3_224', 'sha3_256', 'sha3_384', 'sha3_512'}:
Christian Heimes6fe2a752016-09-07 11:58:24 +0200107 import _sha3
108 cache['sha3_224'] = _sha3.sha3_224
109 cache['sha3_256'] = _sha3.sha3_256
110 cache['sha3_384'] = _sha3.sha3_384
111 cache['sha3_512'] = _sha3.sha3_512
Christian Heimes995b5d32019-09-13 15:31:19 +0200112 elif name in {'shake_128', 'shake_256'}:
113 import _sha3
Christian Heimes6fe2a752016-09-07 11:58:24 +0200114 cache['shake_128'] = _sha3.shake_128
115 cache['shake_256'] = _sha3.shake_256
Brett Cannoncd171c82013-07-04 17:43:24 -0400116 except ImportError:
Gregory P. Smitha3221f82011-05-14 15:35:19 -0700117 pass # no extension module, this hash is unsupported.
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000118
Christian Heimese5351072013-10-22 14:59:12 +0200119 constructor = cache.get(name)
120 if constructor is not None:
121 return constructor
122
Gregory P. Smith76c28f72012-07-21 21:19:53 -0700123 raise ValueError('unsupported hash type ' + name)
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +0000124
125
126def __get_openssl_constructor(name):
Christian Heimes995b5d32019-09-13 15:31:19 +0200127 if name in __block_openssl_constructor:
Christian Heimes8a0fe7b2020-06-19 16:11:02 +0200128 # Prefer our builtin blake2 implementation.
Christian Heimes32a2cee2016-09-07 02:35:13 +0200129 return __get_builtin_constructor(name)
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +0000130 try:
Christian Heimesd5b3f6b2020-05-16 22:27:06 +0200131 # MD5, SHA1, and SHA2 are in all supported OpenSSL versions
132 # SHA3/shake are available in OpenSSL 1.1.1+
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +0000133 f = getattr(_hashlib, 'openssl_' + name)
134 # Allow the C module to raise ValueError. The function will be
Christian Heimes4cc2f932020-05-25 10:43:10 +0200135 # defined but the hash not actually available. Don't fall back to
136 # builtin if the current security policy blocks a digest, bpo#40695.
137 f(usedforsecurity=False)
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +0000138 # Use the C function directly (very fast)
139 return f
140 except (AttributeError, ValueError):
141 return __get_builtin_constructor(name)
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000142
143
Christian Heimes121b9482016-09-06 22:03:25 +0200144def __py_new(name, data=b'', **kwargs):
145 """new(name, data=b'', **kwargs) - Return a new hashing object using the
Serhiy Storchakaf1d36d82018-07-31 09:50:16 +0300146 named algorithm; optionally initialized with data (which must be
147 a bytes-like object).
Christian Heimes121b9482016-09-06 22:03:25 +0200148 """
149 return __get_builtin_constructor(name)(data, **kwargs)
150
151
152def __hash_new(name, data=b'', **kwargs):
Gregory P. Smith2f21eb32007-09-09 06:44:34 +0000153 """new(name, data=b'') - Return a new hashing object using the named algorithm;
Serhiy Storchakaf1d36d82018-07-31 09:50:16 +0300154 optionally initialized with data (which must be a bytes-like object).
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000155 """
Christian Heimes995b5d32019-09-13 15:31:19 +0200156 if name in __block_openssl_constructor:
Christian Heimes8a0fe7b2020-06-19 16:11:02 +0200157 # Prefer our builtin blake2 implementation.
Christian Heimes121b9482016-09-06 22:03:25 +0200158 return __get_builtin_constructor(name)(data, **kwargs)
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000159 try:
Christian Heimes909b5712020-05-22 20:04:33 +0200160 return _hashlib.new(name, data, **kwargs)
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000161 except ValueError:
162 # If the _hashlib module (OpenSSL) doesn't support the named
163 # hash, try using our builtin implementations.
164 # This allows for SHA224/256 and SHA384/512 support even though
165 # the OpenSSL library prior to 0.9.8 doesn't provide them.
Guido van Rossume22905a2007-08-27 23:09:25 +0000166 return __get_builtin_constructor(name)(data)
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000167
168
169try:
170 import _hashlib
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000171 new = __hash_new
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +0000172 __get_hash = __get_openssl_constructor
Gregory P. Smith13b55292010-09-06 08:30:23 +0000173 algorithms_available = algorithms_available.union(
174 _hashlib.openssl_md_meth_names)
Brett Cannoncd171c82013-07-04 17:43:24 -0400175except ImportError:
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000176 new = __py_new
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +0000177 __get_hash = __get_builtin_constructor
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000178
Christian Heimese92ef132013-10-13 00:52:43 +0200179try:
Christian Heimes3626a502013-10-19 14:12:02 +0200180 # OpenSSL's PKCS5_PBKDF2_HMAC requires OpenSSL 1.0+ with HMAC and SHA
Christian Heimese92ef132013-10-13 00:52:43 +0200181 from _hashlib import pbkdf2_hmac
182except ImportError:
Christian Heimes3626a502013-10-19 14:12:02 +0200183 _trans_5C = bytes((x ^ 0x5C) for x in range(256))
184 _trans_36 = bytes((x ^ 0x36) for x in range(256))
185
186 def pbkdf2_hmac(hash_name, password, salt, iterations, dklen=None):
187 """Password based key derivation function 2 (PKCS #5 v2.0)
188
189 This Python implementations based on the hmac module about as fast
190 as OpenSSL's PKCS5_PBKDF2_HMAC for short passwords and much faster
191 for long passwords.
192 """
193 if not isinstance(hash_name, str):
194 raise TypeError(hash_name)
195
196 if not isinstance(password, (bytes, bytearray)):
197 password = bytes(memoryview(password))
198 if not isinstance(salt, (bytes, bytearray)):
199 salt = bytes(memoryview(salt))
200
201 # Fast inline HMAC implementation
202 inner = new(hash_name)
203 outer = new(hash_name)
204 blocksize = getattr(inner, 'block_size', 64)
205 if len(password) > blocksize:
206 password = new(hash_name, password).digest()
207 password = password + b'\x00' * (blocksize - len(password))
208 inner.update(password.translate(_trans_36))
209 outer.update(password.translate(_trans_5C))
210
211 def prf(msg, inner=inner, outer=outer):
212 # PBKDF2_HMAC uses the password as key. We can re-use the same
Serhiy Storchaka56a6d852014-12-01 18:28:43 +0200213 # digest objects and just update copies to skip initialization.
Christian Heimes3626a502013-10-19 14:12:02 +0200214 icpy = inner.copy()
215 ocpy = outer.copy()
216 icpy.update(msg)
217 ocpy.update(icpy.digest())
218 return ocpy.digest()
219
220 if iterations < 1:
221 raise ValueError(iterations)
222 if dklen is None:
223 dklen = outer.digest_size
224 if dklen < 1:
225 raise ValueError(dklen)
226
227 dkey = b''
228 loop = 1
229 from_bytes = int.from_bytes
230 while len(dkey) < dklen:
231 prev = prf(salt + loop.to_bytes(4, 'big'))
luzpaza5293b42017-11-05 07:37:50 -0600232 # endianness doesn't matter here as long to / from use the same
Christian Heimes3626a502013-10-19 14:12:02 +0200233 rkey = int.from_bytes(prev, 'big')
234 for i in range(iterations - 1):
235 prev = prf(prev)
236 # rkey = rkey ^ prev
237 rkey ^= from_bytes(prev, 'big')
238 loop += 1
239 dkey += rkey.to_bytes(inner.digest_size, 'big')
240
241 return dkey[:dklen]
242
Christian Heimes39093e92016-09-06 20:22:28 +0200243try:
244 # OpenSSL's scrypt requires OpenSSL 1.1+
245 from _hashlib import scrypt
246except ImportError:
247 pass
248
Christian Heimese92ef132013-10-13 00:52:43 +0200249
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +0000250for __func_name in __always_supported:
251 # try them all, some may not work due to the OpenSSL
252 # version not supporting that algorithm.
253 try:
254 globals()[__func_name] = __get_hash(__func_name)
255 except ValueError:
256 import logging
257 logging.exception('code for hash %s was not found.', __func_name)
258
Christian Heimes121b9482016-09-06 22:03:25 +0200259
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +0000260# Cleanup locals()
261del __always_supported, __func_name, __get_hash
262del __py_new, __hash_new, __get_openssl_constructor