1 :mod:`hashlib` --- Secure hashes and message digests 2 ==================================================== 3 4 .. module:: hashlib 5 :synopsis: Secure hash and message digest algorithms. 6 .. moduleauthor:: Gregory P. Smith <greg@krypto.org> 7 .. sectionauthor:: Gregory P. Smith <greg@krypto.org> 8 9 10 .. versionadded:: 2.5 11 12 .. index:: 13 single: message digest, MD5 14 single: secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512 15 16 **Source code:** :source:`Lib/hashlib.py` 17 18 -------------- 19 20 This module implements a common interface to many different secure hash and 21 message digest algorithms. Included are the FIPS secure hash algorithms SHA1, 22 SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5 23 algorithm (defined in Internet :rfc:`1321`). The terms secure hash and message 24 digest are interchangeable. Older algorithms were called message digests. The 25 modern term is secure hash. 26 27 .. note:: 28 29 If you want the adler32 or crc32 hash functions, they are available in 30 the :mod:`zlib` module. 31 32 .. warning:: 33 34 Some algorithms have known hash collision weaknesses, refer to the "See 35 also" section at the end. 36 37 There is one constructor method named for each type of :dfn:`hash`. All return 38 a hash object with the same simple interface. For example: use :func:`sha1` to 39 create a SHA1 hash object. You can now feed this object with arbitrary strings 40 using the :meth:`update` method. At any point you can ask it for the 41 :dfn:`digest` of the concatenation of the strings fed to it so far using the 42 :meth:`digest` or :meth:`hexdigest` methods. 43 44 .. index:: single: OpenSSL; (use in module hashlib) 45 46 Constructors for hash algorithms that are always present in this module are 47 :func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, and 48 :func:`sha512`. Additional algorithms may also be available depending upon the 49 OpenSSL library that Python uses on your platform. 50 51 For example, to obtain the digest of the string ``'Nobody inspects the spammish 52 repetition'``: 53 54 >>> import hashlib 55 >>> m = hashlib.md5() 56 >>> m.update("Nobody inspects") 57 >>> m.update(" the spammish repetition") 58 >>> m.digest() 59 '\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9' 60 >>> m.digest_size 61 16 62 >>> m.block_size 63 64 64 65 More condensed: 66 67 >>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest() 68 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2' 69 70 A generic :func:`new` constructor that takes the string name of the desired 71 algorithm as its first parameter also exists to allow access to the above listed 72 hashes as well as any other algorithms that your OpenSSL library may offer. The 73 named constructors are much faster than :func:`new` and should be preferred. 74 75 Using :func:`new` with an algorithm provided by OpenSSL: 76 77 >>> h = hashlib.new('ripemd160') 78 >>> h.update("Nobody inspects the spammish repetition") 79 >>> h.hexdigest() 80 'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc' 81 82 This module provides the following constant attribute: 83 84 .. data:: hashlib.algorithms 85 86 A tuple providing the names of the hash algorithms guaranteed to be 87 supported by this module. 88 89 .. versionadded:: 2.7 90 91 .. data:: algorithms_guaranteed 92 93 A set containing the names of the hash algorithms guaranteed to be supported 94 by this module on all platforms. 95 96 .. versionadded:: 2.7.9 97 98 .. data:: algorithms_available 99 100 A set containing the names of the hash algorithms that are available in the 101 running Python interpreter. These names will be recognized when passed to 102 :func:`new`. :attr:`algorithms_guaranteed` will always be a subset. The 103 same algorithm may appear multiple times in this set under different names 104 (thanks to OpenSSL). 105 106 .. versionadded:: 2.7.9 107 108 109 The following values are provided as constant attributes of the hash objects 110 returned by the constructors: 111 112 113 .. data:: hash.digest_size 114 115 The size of the resulting hash in bytes. 116 117 .. data:: hash.block_size 118 119 The internal block size of the hash algorithm in bytes. 120 121 A hash object has the following methods: 122 123 124 .. method:: hash.update(arg) 125 126 Update the hash object with the string *arg*. Repeated calls are equivalent to 127 a single call with the concatenation of all the arguments: ``m.update(a); 128 m.update(b)`` is equivalent to ``m.update(a+b)``. 129 130 .. versionchanged:: 2.7 131 The Python GIL is released to allow other threads to run while 132 hash updates on data larger than 2048 bytes is taking place when 133 using hash algorithms supplied by OpenSSL. 134 135 136 .. method:: hash.digest() 137 138 Return the digest of the strings passed to the :meth:`update` method so far. 139 This is a string of :attr:`digest_size` bytes which may contain non-ASCII 140 characters, including null bytes. 141 142 143 .. method:: hash.hexdigest() 144 145 Like :meth:`digest` except the digest is returned as a string of double length, 146 containing only hexadecimal digits. This may be used to exchange the value 147 safely in email or other non-binary environments. 148 149 150 .. method:: hash.copy() 151 152 Return a copy ("clone") of the hash object. This can be used to efficiently 153 compute the digests of strings that share a common initial substring. 154 155 156 Key derivation 157 -------------- 158 159 Key derivation and key stretching algorithms are designed for secure password 160 hashing. Naive algorithms such as ``sha1(password)`` are not resistant against 161 brute-force attacks. A good password hashing function must be tunable, slow, and 162 include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_. 163 164 165 .. function:: pbkdf2_hmac(name, password, salt, rounds, dklen=None) 166 167 The function provides PKCS#5 password-based key derivation function 2. It 168 uses HMAC as pseudorandom function. 169 170 The string *name* is the desired name of the hash digest algorithm for 171 HMAC, e.g. 'sha1' or 'sha256'. *password* and *salt* are interpreted as 172 buffers of bytes. Applications and libraries should limit *password* to 173 a sensible value (e.g. 1024). *salt* should be about 16 or more bytes from 174 a proper source, e.g. :func:`os.urandom`. 175 176 The number of *rounds* should be chosen based on the hash algorithm and 177 computing power. As of 2013, at least 100,000 rounds of SHA-256 is suggested. 178 179 *dklen* is the length of the derived key. If *dklen* is ``None`` then the 180 digest size of the hash algorithm *name* is used, e.g. 64 for SHA-512. 181 182 >>> import hashlib, binascii 183 >>> dk = hashlib.pbkdf2_hmac('sha256', b'password', b'salt', 100000) 184 >>> binascii.hexlify(dk) 185 b'0394a2ede332c9a13eb82e9b24631604c31df978b4e2f0fbd2c549944f9d79a5' 186 187 .. versionadded:: 2.7.8 188 189 .. note:: 190 191 A fast implementation of *pbkdf2_hmac* is available with OpenSSL. The 192 Python implementation uses an inline version of :mod:`hmac`. It is about 193 three times slower and doesn't release the GIL. 194 195 196 .. seealso:: 197 198 Module :mod:`hmac` 199 A module to generate message authentication codes using hashes. 200 201 Module :mod:`base64` 202 Another way to encode binary hashes for non-binary environments. 203 204 http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf 205 The FIPS 180-2 publication on Secure Hash Algorithms. 206 207 https://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_algorithms 208 Wikipedia article with information on which algorithms have known issues and 209 what that means regarding their use. 210 211