1#. Copyright (C) 2005-2010 Gregory P. Smith (greg@krypto.org) 2# Licensed to PSF under a Contributor Agreement. 3# 4 5__doc__ = """hashlib module - A common interface to many hash functions. 6 7new(name, data=b'', **kwargs) - returns a new hash object implementing the 8 given hash function; initializing the hash 9 using the given binary data. 10 11Named constructor functions are also available, these are faster 12than using new(name): 13 14md5(), sha1(), sha224(), sha256(), sha384(), sha512(), blake2b(), blake2s(), 15sha3_224, sha3_256, sha3_384, sha3_512, shake_128, and shake_256. 16 17More 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(). 20 21NOTE: If you want the adler32 or crc32 hash functions they are available in 22the zlib module. 23 24Choose your hash function wisely. Some have known collision weaknesses. 25sha384 and sha512 will be slow on 32 bit platforms. 26 27Hash objects have these methods: 28 - 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. 38 39For example, to obtain the digest of the byte string 'Nobody inspects the 40spammish repetition': 41 42 >>> import hashlib 43 >>> m = hashlib.md5() 44 >>> m.update(b"Nobody inspects") 45 >>> m.update(b" the spammish repetition") 46 >>> m.digest() 47 b'\\xbbd\\x9c\\x83\\xdd\\x1e\\xa5\\xc9\\xd9\\xde\\xc9\\xa1\\x8d\\xf0\\xff\\xe9' 48 49More condensed: 50 51 >>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest() 52 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2' 53 54""" 55 56# This tuple and __get_builtin_constructor() must be modified if a new 57# always available algorithm is added. 58__always_supported = ('md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512', 59 'blake2b', 'blake2s', 60 'sha3_224', 'sha3_256', 'sha3_384', 'sha3_512', 61 'shake_128', 'shake_256') 62 63 64algorithms_guaranteed = set(__always_supported) 65algorithms_available = set(__always_supported) 66 67__all__ = __always_supported + ('new', 'algorithms_guaranteed', 68 'algorithms_available', 'pbkdf2_hmac') 69 70 71__builtin_constructor_cache = {} 72 73# 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. 78__block_openssl_constructor = { 79 'blake2b', 'blake2s', 80} 81 82def __get_builtin_constructor(name): 83 cache = __builtin_constructor_cache 84 constructor = cache.get(name) 85 if constructor is not None: 86 return constructor 87 try: 88 if name in {'SHA1', 'sha1'}: 89 import _sha1 90 cache['SHA1'] = cache['sha1'] = _sha1.sha1 91 elif name in {'MD5', 'md5'}: 92 import _md5 93 cache['MD5'] = cache['md5'] = _md5.md5 94 elif name in {'SHA256', 'sha256', 'SHA224', 'sha224'}: 95 import _sha256 96 cache['SHA224'] = cache['sha224'] = _sha256.sha224 97 cache['SHA256'] = cache['sha256'] = _sha256.sha256 98 elif name in {'SHA512', 'sha512', 'SHA384', 'sha384'}: 99 import _sha512 100 cache['SHA384'] = cache['sha384'] = _sha512.sha384 101 cache['SHA512'] = cache['sha512'] = _sha512.sha512 102 elif name in {'blake2b', 'blake2s'}: 103 import _blake2 104 cache['blake2b'] = _blake2.blake2b 105 cache['blake2s'] = _blake2.blake2s 106 elif name in {'sha3_224', 'sha3_256', 'sha3_384', 'sha3_512'}: 107 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 112 elif name in {'shake_128', 'shake_256'}: 113 import _sha3 114 cache['shake_128'] = _sha3.shake_128 115 cache['shake_256'] = _sha3.shake_256 116 except ImportError: 117 pass # no extension module, this hash is unsupported. 118 119 constructor = cache.get(name) 120 if constructor is not None: 121 return constructor 122 123 raise ValueError('unsupported hash type ' + name) 124 125 126def __get_openssl_constructor(name): 127 if name in __block_openssl_constructor: 128 # Prefer our builtin blake2 implementation. 129 return __get_builtin_constructor(name) 130 try: 131 # MD5, SHA1, and SHA2 are in all supported OpenSSL versions 132 # SHA3/shake are available in OpenSSL 1.1.1+ 133 f = getattr(_hashlib, 'openssl_' + name) 134 # Allow the C module to raise ValueError. The function will be 135 # 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) 138 # Use the C function directly (very fast) 139 return f 140 except (AttributeError, ValueError): 141 return __get_builtin_constructor(name) 142 143 144def __py_new(name, data=b'', **kwargs): 145 """new(name, data=b'', **kwargs) - Return a new hashing object using the 146 named algorithm; optionally initialized with data (which must be 147 a bytes-like object). 148 """ 149 return __get_builtin_constructor(name)(data, **kwargs) 150 151 152def __hash_new(name, data=b'', **kwargs): 153 """new(name, data=b'') - Return a new hashing object using the named algorithm; 154 optionally initialized with data (which must be a bytes-like object). 155 """ 156 if name in __block_openssl_constructor: 157 # Prefer our builtin blake2 implementation. 158 return __get_builtin_constructor(name)(data, **kwargs) 159 try: 160 return _hashlib.new(name, data, **kwargs) 161 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. 166 return __get_builtin_constructor(name)(data) 167 168 169try: 170 import _hashlib 171 new = __hash_new 172 __get_hash = __get_openssl_constructor 173 algorithms_available = algorithms_available.union( 174 _hashlib.openssl_md_meth_names) 175except ImportError: 176 new = __py_new 177 __get_hash = __get_builtin_constructor 178 179try: 180 # OpenSSL's PKCS5_PBKDF2_HMAC requires OpenSSL 1.0+ with HMAC and SHA 181 from _hashlib import pbkdf2_hmac 182except ImportError: 183 _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 213 # digest objects and just update copies to skip initialization. 214 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')) 232 # endianness doesn't matter here as long to / from use the same 233 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 243try: 244 # OpenSSL's scrypt requires OpenSSL 1.1+ 245 from _hashlib import scrypt 246except ImportError: 247 pass 248 249 250for __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 259 260# Cleanup locals() 261del __always_supported, __func_name, __get_hash 262del __py_new, __hash_new, __get_openssl_constructor 263