Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`hashlib` --- Secure hashes and message digests |
| 2 | ==================================================== |
| 3 | |
| 4 | .. module:: hashlib |
| 5 | :synopsis: Secure hash and message digest algorithms. |
Benjamin Peterson | 058e31e | 2009-01-16 03:54:08 +0000 | [diff] [blame] | 6 | .. moduleauthor:: Gregory P. Smith <greg@krypto.org> |
| 7 | .. sectionauthor:: Gregory P. Smith <greg@krypto.org> |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | |
| 9 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | .. index:: |
| 11 | single: message digest, MD5 |
| 12 | single: secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512 |
| 13 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 14 | **Source code:** :source:`Lib/hashlib.py` |
| 15 | |
| 16 | -------------- |
| 17 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 18 | This module implements a common interface to many different secure hash and |
| 19 | message digest algorithms. Included are the FIPS secure hash algorithms SHA1, |
| 20 | SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5 |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 21 | algorithm (defined in Internet :rfc:`1321`). The terms "secure hash" and |
| 22 | "message digest" are interchangeable. Older algorithms were called message |
| 23 | digests. The modern term is secure hash. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | |
Christian Heimes | d5e2b6f | 2008-03-19 21:50:51 +0000 | [diff] [blame] | 25 | .. note:: |
| 26 | If you want the adler32 or crc32 hash functions they are available in |
| 27 | the :mod:`zlib` module. |
| 28 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 29 | .. warning:: |
| 30 | |
| 31 | Some algorithms have known hash collision weaknesses, see the FAQ at the end. |
| 32 | |
| 33 | There is one constructor method named for each type of :dfn:`hash`. All return |
| 34 | a hash object with the same simple interface. For example: use :func:`sha1` to |
Ezio Melotti | c228e96 | 2013-05-04 18:06:34 +0300 | [diff] [blame] | 35 | create a SHA1 hash object. You can now feed this object with :term:`bytes-like |
| 36 | object`\ s (normally :class:`bytes`) using the :meth:`update` method. |
| 37 | At any point you can ask it for the :dfn:`digest` of the |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 38 | concatenation of the data fed to it so far using the :meth:`digest` or |
| 39 | :meth:`hexdigest` methods. |
| 40 | |
| 41 | .. note:: |
| 42 | |
Benjamin Peterson | 9cb7bd2 | 2012-12-20 20:24:37 -0600 | [diff] [blame] | 43 | For better multithreading performance, the Python :term:`GIL` is released for |
Antoine Pitrou | bcd5cbe | 2009-01-08 21:17:16 +0000 | [diff] [blame] | 44 | strings of more than 2047 bytes at object creation or on update. |
| 45 | |
| 46 | .. note:: |
| 47 | |
Benjamin Peterson | bd584d5 | 2012-12-20 20:22:47 -0600 | [diff] [blame] | 48 | Feeding string objects into :meth:`update` is not supported, as hashes work |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 49 | on bytes, not on characters. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 50 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 51 | .. index:: single: OpenSSL; (use in module hashlib) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 52 | |
| 53 | Constructors for hash algorithms that are always present in this module are |
Christian Heimes | 4a0270d | 2012-10-06 02:23:36 +0200 | [diff] [blame] | 54 | :func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, |
| 55 | :func:`sha512`, :func:`sha3_224`, :func:`sha3_256`, :func:`sha3_384`, and |
| 56 | :func:`sha3_512`. Additional algorithms may also be available depending upon |
| 57 | the OpenSSL library that Python uses on your platform. |
| 58 | |
| 59 | .. versionchanged:: 3.4 |
| 60 | Add sha3 family of hash algorithms. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 61 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 62 | For example, to obtain the digest of the byte string ``b'Nobody inspects the |
| 63 | spammish repetition'``:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 64 | |
| 65 | >>> import hashlib |
| 66 | >>> m = hashlib.md5() |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 67 | >>> m.update(b"Nobody inspects") |
| 68 | >>> m.update(b" the spammish repetition") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | >>> m.digest() |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 70 | b'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9' |
Guido van Rossum | a19f80c | 2007-11-06 20:51:31 +0000 | [diff] [blame] | 71 | >>> m.digest_size |
| 72 | 16 |
| 73 | >>> m.block_size |
| 74 | 64 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 75 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 76 | More condensed: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 77 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 78 | >>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest() |
Benjamin Peterson | 0fa3f3d | 2008-12-29 20:52:09 +0000 | [diff] [blame] | 79 | 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 80 | |
Gregory P. Smith | 13b5529 | 2010-09-06 08:30:23 +0000 | [diff] [blame] | 81 | .. function:: new(name[, data]) |
| 82 | |
| 83 | Is a generic constructor that takes the string name of the desired |
| 84 | algorithm as its first parameter. It also exists to allow access to the |
| 85 | above listed hashes as well as any other algorithms that your OpenSSL |
| 86 | library may offer. The named constructors are much faster than :func:`new` |
| 87 | and should be preferred. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 88 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 89 | Using :func:`new` with an algorithm provided by OpenSSL: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 90 | |
| 91 | >>> h = hashlib.new('ripemd160') |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 92 | >>> h.update(b"Nobody inspects the spammish repetition") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 93 | >>> h.hexdigest() |
Benjamin Peterson | 0fa3f3d | 2008-12-29 20:52:09 +0000 | [diff] [blame] | 94 | 'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 95 | |
Gregory P. Smith | 13b5529 | 2010-09-06 08:30:23 +0000 | [diff] [blame] | 96 | Hashlib provides the following constant attributes: |
Gregory P. Smith | 86508cc | 2010-03-01 02:05:26 +0000 | [diff] [blame] | 97 | |
Gregory P. Smith | 13b5529 | 2010-09-06 08:30:23 +0000 | [diff] [blame] | 98 | .. data:: algorithms_guaranteed |
Gregory P. Smith | 86508cc | 2010-03-01 02:05:26 +0000 | [diff] [blame] | 99 | |
Gregory P. Smith | 13b5529 | 2010-09-06 08:30:23 +0000 | [diff] [blame] | 100 | Contains the names of the hash algorithms guaranteed to be supported |
| 101 | by this module on all platforms. |
| 102 | |
| 103 | .. versionadded:: 3.2 |
| 104 | |
| 105 | .. data:: algorithms_available |
| 106 | |
| 107 | Contains the names of the hash algorithms that are available |
| 108 | in the running Python interpreter. These names will be recognized |
| 109 | when passed to :func:`new`. :attr:`algorithms_guaranteed` |
| 110 | will always be a subset. Duplicate algorithms with different |
| 111 | name formats may appear in this set (thanks to OpenSSL). |
Gregory P. Smith | 86508cc | 2010-03-01 02:05:26 +0000 | [diff] [blame] | 112 | |
| 113 | .. versionadded:: 3.2 |
| 114 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | The following values are provided as constant attributes of the hash objects |
| 116 | returned by the constructors: |
| 117 | |
| 118 | |
Benjamin Peterson | 4ac9ce4 | 2009-10-04 14:49:41 +0000 | [diff] [blame] | 119 | .. data:: hash.digest_size |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 120 | |
Guido van Rossum | a19f80c | 2007-11-06 20:51:31 +0000 | [diff] [blame] | 121 | The size of the resulting hash in bytes. |
| 122 | |
Benjamin Peterson | 4ac9ce4 | 2009-10-04 14:49:41 +0000 | [diff] [blame] | 123 | .. data:: hash.block_size |
Guido van Rossum | a19f80c | 2007-11-06 20:51:31 +0000 | [diff] [blame] | 124 | |
| 125 | The internal block size of the hash algorithm in bytes. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
| 127 | A hash object has the following methods: |
| 128 | |
| 129 | |
| 130 | .. method:: hash.update(arg) |
| 131 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 132 | Update the hash object with the object *arg*, which must be interpretable as |
| 133 | a buffer of bytes. Repeated calls are equivalent to a single call with the |
| 134 | concatenation of all the arguments: ``m.update(a); m.update(b)`` is |
| 135 | equivalent to ``m.update(a+b)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 136 | |
Georg Brandl | 705d9d5 | 2009-05-05 09:29:50 +0000 | [diff] [blame] | 137 | .. versionchanged:: 3.1 |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 138 | The Python GIL is released to allow other threads to run while hash |
| 139 | updates on data larger than 2048 bytes is taking place when using hash |
| 140 | algorithms supplied by OpenSSL. |
Gregory P. Smith | 3f61d61 | 2009-05-04 00:45:33 +0000 | [diff] [blame] | 141 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 142 | |
| 143 | .. method:: hash.digest() |
| 144 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 145 | Return the digest of the data passed to the :meth:`update` method so far. |
Senthil Kumaran | 627284c | 2010-12-30 07:07:58 +0000 | [diff] [blame] | 146 | This is a bytes object of size :attr:`digest_size` which may contain bytes in |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 147 | the whole range from 0 to 255. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 148 | |
| 149 | |
| 150 | .. method:: hash.hexdigest() |
| 151 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 152 | Like :meth:`digest` except the digest is returned as a string object of |
| 153 | double length, containing only hexadecimal digits. This may be used to |
| 154 | exchange the value safely in email or other non-binary environments. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 155 | |
| 156 | |
| 157 | .. method:: hash.copy() |
| 158 | |
| 159 | Return a copy ("clone") of the hash object. This can be used to efficiently |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 160 | compute the digests of data sharing a common initial substring. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 161 | |
| 162 | |
| 163 | .. seealso:: |
| 164 | |
| 165 | Module :mod:`hmac` |
| 166 | A module to generate message authentication codes using hashes. |
| 167 | |
| 168 | Module :mod:`base64` |
| 169 | Another way to encode binary hashes for non-binary environments. |
| 170 | |
| 171 | http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf |
| 172 | The FIPS 180-2 publication on Secure Hash Algorithms. |
| 173 | |
Georg Brandl | fd0eb3f | 2010-05-21 20:28:13 +0000 | [diff] [blame] | 174 | http://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_algorithms |
| 175 | Wikipedia article with information on which algorithms have known issues and |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 176 | what that means regarding their use. |
| 177 | |