blob: 77673f06eb2ca856c42db364dbaa556ab5a6a49f [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
Guido van Rossume22905a2007-08-27 23:09:25 +00007new(name, data=b'') - 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
14md5(), sha1(), sha224(), sha256(), sha384(), and sha512()
15
Gregory P. Smith13b55292010-09-06 08:30:23 +000016More algorithms may be available on your platform but the above are guaranteed
17to exist. See the algorithms_guaranteed and algorithms_available attributes
18to find out what algorithm names can be passed to new().
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000019
Christian Heimesd5e2b6f2008-03-19 21:50:51 +000020NOTE: If you want the adler32 or crc32 hash functions they are available in
21the zlib module.
22
Thomas Wouters89f507f2006-12-13 04:49:30 +000023Choose your hash function wisely. Some have known collision weaknesses.
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000024sha384 and sha512 will be slow on 32 bit platforms.
Thomas Wouters89f507f2006-12-13 04:49:30 +000025
26Hash objects have these methods:
Gregory P. Smith2f21eb32007-09-09 06:44:34 +000027 - update(arg): Update the hash object with the bytes in arg. Repeated calls
Thomas Wouters89f507f2006-12-13 04:49:30 +000028 are equivalent to a single call with the concatenation of all
29 the arguments.
Gregory P. Smith2f21eb32007-09-09 06:44:34 +000030 - digest(): Return the digest of the bytes passed to the update() method
31 so far.
32 - hexdigest(): Like digest() except the digest is returned as a unicode
33 object of double length, containing only hexadecimal digits.
Thomas Wouters89f507f2006-12-13 04:49:30 +000034 - copy(): Return a copy (clone) of the hash object. This can be used to
35 efficiently compute the digests of strings that share a common
36 initial substring.
37
38For example, to obtain the digest of the string 'Nobody inspects the
39spammish repetition':
40
41 >>> import hashlib
42 >>> m = hashlib.md5()
Guido van Rossume22905a2007-08-27 23:09:25 +000043 >>> m.update(b"Nobody inspects")
44 >>> m.update(b" the spammish repetition")
Thomas Wouters89f507f2006-12-13 04:49:30 +000045 >>> m.digest()
Gregory P. Smith63594502008-08-31 16:35:01 +000046 b'\\xbbd\\x9c\\x83\\xdd\\x1e\\xa5\\xc9\\xd9\\xde\\xc9\\xa1\\x8d\\xf0\\xff\\xe9'
Thomas Wouters89f507f2006-12-13 04:49:30 +000047
48More condensed:
49
Guido van Rossume22905a2007-08-27 23:09:25 +000050 >>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest()
Thomas Wouters89f507f2006-12-13 04:49:30 +000051 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
52
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000053"""
54
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +000055# This tuple and __get_builtin_constructor() must be modified if a new
56# always available algorithm is added.
Christian Heimes4a0270d2012-10-06 02:23:36 +020057__always_supported = ('md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512',
58 'sha3_224', 'sha3_256', 'sha3_384', 'sha3_512')
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +000059
Raymond Hettingerbf1d2bc2011-01-24 04:52:27 +000060algorithms_guaranteed = set(__always_supported)
61algorithms_available = set(__always_supported)
Gregory P. Smith86508cc2010-03-01 02:05:26 +000062
Gregory P. Smith13b55292010-09-06 08:30:23 +000063__all__ = __always_supported + ('new', 'algorithms_guaranteed',
Christian Heimes3626a502013-10-19 14:12:02 +020064 'algorithms_available', 'pbkdf2_hmac')
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +000065
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000066
Christian Heimese5351072013-10-22 14:59:12 +020067__builtin_constructor_cache = {}
68
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000069def __get_builtin_constructor(name):
Christian Heimese5351072013-10-22 14:59:12 +020070 cache = __builtin_constructor_cache
71 constructor = cache.get(name)
72 if constructor is not None:
73 return constructor
Gregory P. Smith12c9d022011-05-14 15:15:49 -070074 try:
75 if name in ('SHA1', 'sha1'):
76 import _sha1
Christian Heimese5351072013-10-22 14:59:12 +020077 cache['SHA1'] = cache['sha1'] = _sha1.sha1
Gregory P. Smith12c9d022011-05-14 15:15:49 -070078 elif name in ('MD5', 'md5'):
79 import _md5
Christian Heimese5351072013-10-22 14:59:12 +020080 cache['MD5'] = cache['md5'] = _md5.md5
Gregory P. Smith12c9d022011-05-14 15:15:49 -070081 elif name in ('SHA256', 'sha256', 'SHA224', 'sha224'):
82 import _sha256
Christian Heimese5351072013-10-22 14:59:12 +020083 cache['SHA224'] = cache['sha224'] = _sha256.sha224
84 cache['SHA256'] = cache['sha256'] = _sha256.sha256
Gregory P. Smith12c9d022011-05-14 15:15:49 -070085 elif name in ('SHA512', 'sha512', 'SHA384', 'sha384'):
86 import _sha512
Christian Heimese5351072013-10-22 14:59:12 +020087 cache['SHA384'] = cache['sha384'] = _sha512.sha384
88 cache['SHA512'] = cache['sha512'] = _sha512.sha512
Christian Heimes4a0270d2012-10-06 02:23:36 +020089 elif name in {'sha3_224', 'sha3_256', 'sha3_384', 'sha3_512',
90 'SHA3_224', 'SHA3_256', 'SHA3_384', 'SHA3_512'}:
91 import _sha3
Christian Heimese5351072013-10-22 14:59:12 +020092 cache['SHA3_224'] = cache['sha3_224'] = _sha3.sha3_224
93 cache['SHA3_256'] = cache['sha3_256'] = _sha3.sha3_256
94 cache['SHA3_384'] = cache['sha3_384'] = _sha3.sha3_384
95 cache['SHA3_512'] = cache['sha3_512'] = _sha3.sha3_512
Brett Cannoncd171c82013-07-04 17:43:24 -040096 except ImportError:
Gregory P. Smitha3221f82011-05-14 15:35:19 -070097 pass # no extension module, this hash is unsupported.
Gregory P. Smithf21a5f72005-08-21 18:45:59 +000098
Christian Heimese5351072013-10-22 14:59:12 +020099 constructor = cache.get(name)
100 if constructor is not None:
101 return constructor
102
Gregory P. Smith76c28f72012-07-21 21:19:53 -0700103 raise ValueError('unsupported hash type ' + name)
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +0000104
105
106def __get_openssl_constructor(name):
107 try:
108 f = getattr(_hashlib, 'openssl_' + name)
109 # Allow the C module to raise ValueError. The function will be
110 # defined but the hash not actually available thanks to OpenSSL.
111 f()
112 # Use the C function directly (very fast)
113 return f
114 except (AttributeError, ValueError):
115 return __get_builtin_constructor(name)
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000116
117
Guido van Rossume22905a2007-08-27 23:09:25 +0000118def __py_new(name, data=b''):
Gregory P. Smith2f21eb32007-09-09 06:44:34 +0000119 """new(name, data=b'') - Return a new hashing object using the named algorithm;
Guido van Rossume22905a2007-08-27 23:09:25 +0000120 optionally initialized with data (which must be bytes).
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000121 """
Guido van Rossume22905a2007-08-27 23:09:25 +0000122 return __get_builtin_constructor(name)(data)
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000123
124
Guido van Rossume22905a2007-08-27 23:09:25 +0000125def __hash_new(name, data=b''):
126 """new(name, data=b'') - Return a new hashing object using the named algorithm;
127 optionally initialized with data (which must be bytes).
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000128 """
129 try:
Guido van Rossume22905a2007-08-27 23:09:25 +0000130 return _hashlib.new(name, data)
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000131 except ValueError:
132 # If the _hashlib module (OpenSSL) doesn't support the named
133 # hash, try using our builtin implementations.
134 # This allows for SHA224/256 and SHA384/512 support even though
135 # the OpenSSL library prior to 0.9.8 doesn't provide them.
Guido van Rossume22905a2007-08-27 23:09:25 +0000136 return __get_builtin_constructor(name)(data)
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000137
138
139try:
140 import _hashlib
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000141 new = __hash_new
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +0000142 __get_hash = __get_openssl_constructor
Gregory P. Smith13b55292010-09-06 08:30:23 +0000143 algorithms_available = algorithms_available.union(
144 _hashlib.openssl_md_meth_names)
Brett Cannoncd171c82013-07-04 17:43:24 -0400145except ImportError:
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000146 new = __py_new
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +0000147 __get_hash = __get_builtin_constructor
Gregory P. Smithf21a5f72005-08-21 18:45:59 +0000148
Christian Heimese92ef132013-10-13 00:52:43 +0200149try:
Christian Heimes3626a502013-10-19 14:12:02 +0200150 # OpenSSL's PKCS5_PBKDF2_HMAC requires OpenSSL 1.0+ with HMAC and SHA
Christian Heimese92ef132013-10-13 00:52:43 +0200151 from _hashlib import pbkdf2_hmac
152except ImportError:
Christian Heimes3626a502013-10-19 14:12:02 +0200153 _trans_5C = bytes((x ^ 0x5C) for x in range(256))
154 _trans_36 = bytes((x ^ 0x36) for x in range(256))
155
156 def pbkdf2_hmac(hash_name, password, salt, iterations, dklen=None):
157 """Password based key derivation function 2 (PKCS #5 v2.0)
158
159 This Python implementations based on the hmac module about as fast
160 as OpenSSL's PKCS5_PBKDF2_HMAC for short passwords and much faster
161 for long passwords.
162 """
163 if not isinstance(hash_name, str):
164 raise TypeError(hash_name)
165
166 if not isinstance(password, (bytes, bytearray)):
167 password = bytes(memoryview(password))
168 if not isinstance(salt, (bytes, bytearray)):
169 salt = bytes(memoryview(salt))
170
171 # Fast inline HMAC implementation
172 inner = new(hash_name)
173 outer = new(hash_name)
174 blocksize = getattr(inner, 'block_size', 64)
175 if len(password) > blocksize:
176 password = new(hash_name, password).digest()
177 password = password + b'\x00' * (blocksize - len(password))
178 inner.update(password.translate(_trans_36))
179 outer.update(password.translate(_trans_5C))
180
181 def prf(msg, inner=inner, outer=outer):
182 # PBKDF2_HMAC uses the password as key. We can re-use the same
183 # digest objects and and just update copies to skip initialization.
184 icpy = inner.copy()
185 ocpy = outer.copy()
186 icpy.update(msg)
187 ocpy.update(icpy.digest())
188 return ocpy.digest()
189
190 if iterations < 1:
191 raise ValueError(iterations)
192 if dklen is None:
193 dklen = outer.digest_size
194 if dklen < 1:
195 raise ValueError(dklen)
196
197 dkey = b''
198 loop = 1
199 from_bytes = int.from_bytes
200 while len(dkey) < dklen:
201 prev = prf(salt + loop.to_bytes(4, 'big'))
202 # endianess doesn't matter here as long to / from use the same
203 rkey = int.from_bytes(prev, 'big')
204 for i in range(iterations - 1):
205 prev = prf(prev)
206 # rkey = rkey ^ prev
207 rkey ^= from_bytes(prev, 'big')
208 loop += 1
209 dkey += rkey.to_bytes(inner.digest_size, 'big')
210
211 return dkey[:dklen]
212
Christian Heimese92ef132013-10-13 00:52:43 +0200213
Gregory P. Smithd8fe8bf2009-08-16 22:08:56 +0000214for __func_name in __always_supported:
215 # try them all, some may not work due to the OpenSSL
216 # version not supporting that algorithm.
217 try:
218 globals()[__func_name] = __get_hash(__func_name)
219 except ValueError:
220 import logging
221 logging.exception('code for hash %s was not found.', __func_name)
222
223# Cleanup locals()
224del __always_supported, __func_name, __get_hash
225del __py_new, __hash_new, __get_openssl_constructor