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 | |
| 14 | This module implements a common interface to many different secure hash and |
| 15 | message digest algorithms. Included are the FIPS secure hash algorithms SHA1, |
| 16 | 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] | 17 | algorithm (defined in Internet :rfc:`1321`). The terms "secure hash" and |
| 18 | "message digest" are interchangeable. Older algorithms were called message |
| 19 | digests. The modern term is secure hash. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 20 | |
Christian Heimes | d5e2b6f | 2008-03-19 21:50:51 +0000 | [diff] [blame] | 21 | .. note:: |
| 22 | If you want the adler32 or crc32 hash functions they are available in |
| 23 | the :mod:`zlib` module. |
| 24 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 25 | .. warning:: |
| 26 | |
| 27 | Some algorithms have known hash collision weaknesses, see the FAQ at the end. |
| 28 | |
| 29 | There is one constructor method named for each type of :dfn:`hash`. All return |
| 30 | 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] | 31 | create a SHA1 hash object. You can now feed this object with objects conforming |
| 32 | to the buffer interface (normally :class:`bytes` objects) using the |
| 33 | :meth:`update` method. At any point you can ask it for the :dfn:`digest` of the |
| 34 | concatenation of the data fed to it so far using the :meth:`digest` or |
| 35 | :meth:`hexdigest` methods. |
| 36 | |
| 37 | .. note:: |
| 38 | |
Antoine Pitrou | bcd5cbe | 2009-01-08 21:17:16 +0000 | [diff] [blame] | 39 | For better multithreading performance, the Python GIL is released for |
| 40 | strings of more than 2047 bytes at object creation or on update. |
| 41 | |
| 42 | .. note:: |
| 43 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 44 | Feeding string objects is to :meth:`update` is not supported, as hashes work |
| 45 | on bytes, not on characters. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 46 | |
Thomas Wouters | 1b7f891 | 2007-09-19 03:06:30 +0000 | [diff] [blame] | 47 | .. index:: single: OpenSSL; (use in module hashlib) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | |
| 49 | Constructors for hash algorithms that are always present in this module are |
| 50 | :func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, and |
| 51 | :func:`sha512`. Additional algorithms may also be available depending upon the |
| 52 | OpenSSL library that Python uses on your platform. |
| 53 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 54 | For example, to obtain the digest of the byte string ``b'Nobody inspects the |
| 55 | spammish repetition'``:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 56 | |
| 57 | >>> import hashlib |
| 58 | >>> m = hashlib.md5() |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 59 | >>> m.update(b"Nobody inspects") |
| 60 | >>> m.update(b" the spammish repetition") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 61 | >>> m.digest() |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 62 | 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] | 63 | >>> m.digest_size |
| 64 | 16 |
| 65 | >>> m.block_size |
| 66 | 64 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 67 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 68 | More condensed: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 70 | >>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest() |
Benjamin Peterson | 0fa3f3d | 2008-12-29 20:52:09 +0000 | [diff] [blame] | 71 | 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 72 | |
| 73 | A generic :func:`new` constructor that takes the string name of the desired |
| 74 | algorithm as its first parameter also exists to allow access to the above listed |
| 75 | hashes as well as any other algorithms that your OpenSSL library may offer. The |
| 76 | named constructors are much faster than :func:`new` and should be preferred. |
| 77 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 78 | Using :func:`new` with an algorithm provided by OpenSSL: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 79 | |
| 80 | >>> h = hashlib.new('ripemd160') |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 81 | >>> h.update(b"Nobody inspects the spammish repetition") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 82 | >>> h.hexdigest() |
Benjamin Peterson | 0fa3f3d | 2008-12-29 20:52:09 +0000 | [diff] [blame] | 83 | 'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
| 85 | The following values are provided as constant attributes of the hash objects |
| 86 | returned by the constructors: |
| 87 | |
| 88 | |
Benjamin Peterson | f3d7dbe | 2009-10-04 14:54:52 +0000 | [diff] [blame] | 89 | .. data:: hash.digest_size |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 90 | |
Guido van Rossum | a19f80c | 2007-11-06 20:51:31 +0000 | [diff] [blame] | 91 | The size of the resulting hash in bytes. |
| 92 | |
Benjamin Peterson | f3d7dbe | 2009-10-04 14:54:52 +0000 | [diff] [blame] | 93 | .. data:: hash.block_size |
Guido van Rossum | a19f80c | 2007-11-06 20:51:31 +0000 | [diff] [blame] | 94 | |
| 95 | The internal block size of the hash algorithm in bytes. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 96 | |
| 97 | A hash object has the following methods: |
| 98 | |
| 99 | |
| 100 | .. method:: hash.update(arg) |
| 101 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 102 | Update the hash object with the object *arg*, which must be interpretable as |
| 103 | a buffer of bytes. Repeated calls are equivalent to a single call with the |
| 104 | concatenation of all the arguments: ``m.update(a); m.update(b)`` is |
| 105 | equivalent to ``m.update(a+b)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 106 | |
Georg Brandl | 705d9d5 | 2009-05-05 09:29:50 +0000 | [diff] [blame] | 107 | .. versionchanged:: 3.1 |
Gregory P. Smith | 3f61d61 | 2009-05-04 00:45:33 +0000 | [diff] [blame] | 108 | |
| 109 | The Python GIL is released to allow other threads to run while |
| 110 | hash updates on data larger than 2048 bytes is taking place when |
| 111 | using hash algorithms supplied by OpenSSL. |
| 112 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 113 | |
| 114 | .. method:: hash.digest() |
| 115 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 116 | Return the digest of the data passed to the :meth:`update` method so far. |
| 117 | This is a bytes array of size :attr:`digest_size` which may contain bytes in |
| 118 | the whole range from 0 to 255. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 119 | |
| 120 | |
| 121 | .. method:: hash.hexdigest() |
| 122 | |
Georg Brandl | 67ced42 | 2007-09-06 14:09:10 +0000 | [diff] [blame] | 123 | Like :meth:`digest` except the digest is returned as a string object of |
| 124 | double length, containing only hexadecimal digits. This may be used to |
| 125 | exchange the value safely in email or other non-binary environments. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
| 127 | |
| 128 | .. method:: hash.copy() |
| 129 | |
| 130 | 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] | 131 | compute the digests of data sharing a common initial substring. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 132 | |
| 133 | |
| 134 | .. seealso:: |
| 135 | |
| 136 | Module :mod:`hmac` |
| 137 | A module to generate message authentication codes using hashes. |
| 138 | |
| 139 | Module :mod:`base64` |
| 140 | Another way to encode binary hashes for non-binary environments. |
| 141 | |
| 142 | http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf |
| 143 | The FIPS 180-2 publication on Secure Hash Algorithms. |
| 144 | |
Georg Brandl | 8c5a7bb | 2010-05-21 20:36:03 +0000 | [diff] [blame] | 145 | http://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_algorithms |
| 146 | Wikipedia article with information on which algorithms have known issues and |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 147 | what that means regarding their use. |
| 148 | |