3 # Copyright (C) 2005 Gregory P. Smith (greg@krypto.org)
4 # Licensed to PSF under a Contributor Agreement.
7 __doc__
= """hashlib module - A common interface to many hash functions.
9 new(name, string='') - returns a new hash object implementing the
10 given hash function; initializing the hash
11 using the given string data.
13 Named constructor functions are also available, these are much faster
16 md5(), sha1(), sha224(), sha256(), sha384(), and sha512()
18 More algorithms may be available on your platform but the above are guaranteed
19 to exist. See the algorithms_guaranteed and algorithms_available attributes
20 to find out what algorithm names can be passed to new().
22 NOTE: If you want the adler32 or crc32 hash functions they are available in
25 Choose your hash function wisely. Some have known collision weaknesses.
26 sha384 and sha512 will be slow on 32 bit platforms.
28 Hash objects have these methods:
29 - update(arg): Update the hash object with the string arg. Repeated calls
30 are equivalent to a single call with the concatenation of all
32 - digest(): Return the digest of the strings passed to the update() method
33 so far. This may contain non-ASCII characters, including
35 - hexdigest(): Like digest() except the digest is returned as a string of
36 double length, containing only hexadecimal digits.
37 - copy(): Return a copy (clone) of the hash object. This can be used to
38 efficiently compute the digests of strings that share a common
41 For example, to obtain the digest of the string 'Nobody inspects the
46 >>> m.update("Nobody inspects")
47 >>> m.update(" the spammish repetition")
49 '\\xbbd\\x9c\\x83\\xdd\\x1e\\xa5\\xc9\\xd9\\xde\\xc9\\xa1\\x8d\\xf0\\xff\\xe9'
53 >>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
54 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
58 # This tuple and __get_builtin_constructor() must be modified if a new
59 # always available algorithm is added.
60 __always_supported
= ('md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512')
62 algorithms_guaranteed
= set(__always_supported
)
63 algorithms_available
= set(__always_supported
)
65 algorithms
= __always_supported
67 __all__
= __always_supported
+ ('new', 'algorithms_guaranteed',
68 'algorithms_available', 'algorithms',
72 def __get_builtin_constructor(name
):
74 if name
in ('SHA1', 'sha1'):
77 elif name
in ('MD5', 'md5'):
80 elif name
in ('SHA256', 'sha256', 'SHA224', 'sha224'):
87 elif name
in ('SHA512', 'sha512', 'SHA384', 'sha384'):
95 pass # no extension module, this hash is unsupported.
97 raise ValueError('unsupported hash type ' + name
)
100 def __get_openssl_constructor(name
):
102 f
= getattr(_hashlib
, 'openssl_' + name
)
103 # Allow the C module to raise ValueError. The function will be
104 # defined but the hash not actually available thanks to OpenSSL.
106 # Use the C function directly (very fast)
108 except (AttributeError, ValueError):
109 return __get_builtin_constructor(name
)
112 def __py_new(name
, string
=''):
113 """new(name, string='') - Return a new hashing object using the named algorithm;
114 optionally initialized with a string.
116 return __get_builtin_constructor(name
)(string
)
119 def __hash_new(name
, string
=''):
120 """new(name, string='') - Return a new hashing object using the named algorithm;
121 optionally initialized with a string.
124 return _hashlib
.new(name
, string
)
126 # If the _hashlib module (OpenSSL) doesn't support the named
127 # hash, try using our builtin implementations.
128 # This allows for SHA224/256 and SHA384/512 support even though
129 # the OpenSSL library prior to 0.9.8 doesn't provide them.
130 return __get_builtin_constructor(name
)(string
)
136 __get_hash
= __get_openssl_constructor
137 algorithms_available
= algorithms_available
.union(
138 _hashlib
.openssl_md_meth_names
)
141 __get_hash
= __get_builtin_constructor
143 for __func_name
in __always_supported
:
144 # try them all, some may not work due to the OpenSSL
145 # version not supporting that algorithm.
147 globals()[__func_name
] = __get_hash(__func_name
)
150 logging
.exception('code for hash %s was not found.', __func_name
)
154 # OpenSSL's PKCS5_PBKDF2_HMAC requires OpenSSL 1.0+ with HMAC and SHA
155 from _hashlib
import pbkdf2_hmac
160 _trans_5C
= b
"".join(chr(x ^
0x5C) for x
in range(256))
161 _trans_36
= b
"".join(chr(x ^
0x36) for x
in range(256))
163 def pbkdf2_hmac(hash_name
, password
, salt
, iterations
, dklen
=None):
164 """Password based key derivation function 2 (PKCS #5 v2.0)
166 This Python implementations based on the hmac module about as fast
167 as OpenSSL's PKCS5_PBKDF2_HMAC for short passwords and much faster
170 if not isinstance(hash_name
, str):
171 raise TypeError(hash_name
)
173 if not isinstance(password
, (bytes
, bytearray
)):
174 password
= bytes(buffer(password
))
175 if not isinstance(salt
, (bytes
, bytearray
)):
176 salt
= bytes(buffer(salt
))
178 # Fast inline HMAC implementation
179 inner
= new(hash_name
)
180 outer
= new(hash_name
)
181 blocksize
= getattr(inner
, 'block_size', 64)
182 if len(password
) > blocksize
:
183 password
= new(hash_name
, password
).digest()
184 password
= password
+ b
'\x00' * (blocksize
- len(password
))
185 inner
.update(password
.translate(_trans_36
))
186 outer
.update(password
.translate(_trans_5C
))
188 def prf(msg
, inner
=inner
, outer
=outer
):
189 # PBKDF2_HMAC uses the password as key. We can re-use the same
190 # digest objects and just update copies to skip initialization.
194 ocpy
.update(icpy
.digest())
198 raise ValueError(iterations
)
200 dklen
= outer
.digest_size
202 raise ValueError(dklen
)
204 hex_format_string
= "%%0%ix" % (new(hash_name
).digest_size
* 2)
208 while len(dkey
) < dklen
:
209 prev
= prf(salt
+ struct
.pack(b
'>I', loop
))
210 rkey
= int(binascii
.hexlify(prev
), 16)
211 for i
in xrange(iterations
- 1):
213 rkey ^
= int(binascii
.hexlify(prev
), 16)
215 dkey
+= binascii
.unhexlify(hex_format_string
% rkey
)
220 del __always_supported
, __func_name
, __get_hash
221 del __py_new
, __hash_new
, __get_openssl_constructor