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 |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 35 | create a SHA1 hash object. You can now feed this object with objects conforming |
| 36 | to the buffer interface (normally :class:`bytes` objects) using the |
| 37 | :meth:`update` method. At any point you can ask it for the :dfn:`digest` of the |
| 38 | concatenation of the data fed to it so far using the :meth:`digest` or |
| 39 | :meth:`hexdigest` methods. |
| 40 | |
| 41 | .. note:: |
| 42 | |
Antoine Pitrou | bcd5cbe | 2009-01-08 21:17:16 +0000 | [diff] [blame] | 43 | For better multithreading performance, the Python GIL is released for |
| 44 | strings of more than 2047 bytes at object creation or on update. |
| 45 | |
| 46 | .. note:: |
| 47 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 48 | Feeding string objects is to :meth:`update` is not supported, as hashes work |
| 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 |
| 54 | :func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, and |
| 55 | :func:`sha512`. Additional algorithms may also be available depending upon the |
| 56 | OpenSSL library that Python uses on your platform. |
| 57 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 58 | For example, to obtain the digest of the byte string ``b'Nobody inspects the |
| 59 | spammish repetition'``:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
| 61 | >>> import hashlib |
| 62 | >>> m = hashlib.md5() |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 63 | >>> m.update(b"Nobody inspects") |
| 64 | >>> m.update(b" the spammish repetition") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 65 | >>> m.digest() |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 66 | 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] | 67 | >>> m.digest_size |
| 68 | 16 |
| 69 | >>> m.block_size |
| 70 | 64 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 72 | More condensed: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 74 | >>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest() |
Benjamin Peterson | 0fa3f3d | 2008-12-29 20:52:09 +0000 | [diff] [blame] | 75 | 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 76 | |
Gregory P. Smith | 13b5529 | 2010-09-06 08:30:23 +0000 | [diff] [blame] | 77 | .. function:: new(name[, data]) |
| 78 | |
| 79 | Is a generic constructor that takes the string name of the desired |
| 80 | algorithm as its first parameter. It also exists to allow access to the |
| 81 | above listed hashes as well as any other algorithms that your OpenSSL |
| 82 | library may offer. The named constructors are much faster than :func:`new` |
| 83 | and should be preferred. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 85 | Using :func:`new` with an algorithm provided by OpenSSL: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 86 | |
| 87 | >>> h = hashlib.new('ripemd160') |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 88 | >>> h.update(b"Nobody inspects the spammish repetition") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 89 | >>> h.hexdigest() |
Benjamin Peterson | 0fa3f3d | 2008-12-29 20:52:09 +0000 | [diff] [blame] | 90 | 'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 91 | |
Gregory P. Smith | 13b5529 | 2010-09-06 08:30:23 +0000 | [diff] [blame] | 92 | Hashlib provides the following constant attributes: |
Gregory P. Smith | 86508cc | 2010-03-01 02:05:26 +0000 | [diff] [blame] | 93 | |
Gregory P. Smith | 13b5529 | 2010-09-06 08:30:23 +0000 | [diff] [blame] | 94 | .. data:: algorithms_guaranteed |
Gregory P. Smith | 86508cc | 2010-03-01 02:05:26 +0000 | [diff] [blame] | 95 | |
Gregory P. Smith | 13b5529 | 2010-09-06 08:30:23 +0000 | [diff] [blame] | 96 | Contains the names of the hash algorithms guaranteed to be supported |
| 97 | by this module on all platforms. |
| 98 | |
| 99 | .. versionadded:: 3.2 |
| 100 | |
| 101 | .. data:: algorithms_available |
| 102 | |
| 103 | Contains the names of the hash algorithms that are available |
| 104 | in the running Python interpreter. These names will be recognized |
| 105 | when passed to :func:`new`. :attr:`algorithms_guaranteed` |
| 106 | will always be a subset. Duplicate algorithms with different |
| 107 | name formats may appear in this set (thanks to OpenSSL). |
Gregory P. Smith | 86508cc | 2010-03-01 02:05:26 +0000 | [diff] [blame] | 108 | |
| 109 | .. versionadded:: 3.2 |
| 110 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 111 | The following values are provided as constant attributes of the hash objects |
| 112 | returned by the constructors: |
| 113 | |
| 114 | |
Benjamin Peterson | 4ac9ce4 | 2009-10-04 14:49:41 +0000 | [diff] [blame] | 115 | .. data:: hash.digest_size |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | |
Guido van Rossum | a19f80c | 2007-11-06 20:51:31 +0000 | [diff] [blame] | 117 | The size of the resulting hash in bytes. |
| 118 | |
Benjamin Peterson | 4ac9ce4 | 2009-10-04 14:49:41 +0000 | [diff] [blame] | 119 | .. data:: hash.block_size |
Guido van Rossum | a19f80c | 2007-11-06 20:51:31 +0000 | [diff] [blame] | 120 | |
| 121 | The internal block size of the hash algorithm in bytes. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 122 | |
| 123 | A hash object has the following methods: |
| 124 | |
| 125 | |
| 126 | .. method:: hash.update(arg) |
| 127 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 128 | Update the hash object with the object *arg*, which must be interpretable as |
| 129 | a buffer of bytes. Repeated calls are equivalent to a single call with the |
| 130 | concatenation of all the arguments: ``m.update(a); m.update(b)`` is |
| 131 | equivalent to ``m.update(a+b)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 132 | |
Georg Brandl | 705d9d5 | 2009-05-05 09:29:50 +0000 | [diff] [blame] | 133 | .. versionchanged:: 3.1 |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 134 | The Python GIL is released to allow other threads to run while hash |
| 135 | updates on data larger than 2048 bytes is taking place when using hash |
| 136 | algorithms supplied by OpenSSL. |
Gregory P. Smith | 3f61d61 | 2009-05-04 00:45:33 +0000 | [diff] [blame] | 137 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 138 | |
| 139 | .. method:: hash.digest() |
| 140 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 141 | 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] | 142 | 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] | 143 | the whole range from 0 to 255. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 144 | |
| 145 | |
| 146 | .. method:: hash.hexdigest() |
| 147 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 148 | Like :meth:`digest` except the digest is returned as a string object of |
| 149 | double length, containing only hexadecimal digits. This may be used to |
| 150 | exchange the value safely in email or other non-binary environments. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 151 | |
| 152 | |
| 153 | .. method:: hash.copy() |
| 154 | |
| 155 | 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] | 156 | compute the digests of data sharing a common initial substring. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 157 | |
| 158 | |
| 159 | .. seealso:: |
| 160 | |
| 161 | Module :mod:`hmac` |
| 162 | A module to generate message authentication codes using hashes. |
| 163 | |
| 164 | Module :mod:`base64` |
| 165 | Another way to encode binary hashes for non-binary environments. |
| 166 | |
| 167 | http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf |
| 168 | The FIPS 180-2 publication on Secure Hash Algorithms. |
| 169 | |
Georg Brandl | fd0eb3f | 2010-05-21 20:28:13 +0000 | [diff] [blame] | 170 | http://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_algorithms |
| 171 | Wikipedia article with information on which algorithms have known issues and |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 172 | what that means regarding their use. |
| 173 | |