/Doc/library/hashlib.rst

  1
  2:mod:`hashlib` --- Secure hashes and message digests
  3====================================================
  4
  5.. module:: hashlib
  6   :synopsis: Secure hash and message digest algorithms.
  7.. moduleauthor:: Gregory P. Smith <greg@krypto.org>
  8.. sectionauthor:: Gregory P. Smith <greg@krypto.org>
  9
 10
 11.. versionadded:: 2.5
 12
 13.. index::
 14   single: message digest, MD5
 15   single: secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512
 16
 17This module implements a common interface to many different secure hash and
 18message digest algorithms.  Included are the FIPS secure hash algorithms SHA1,
 19SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5
 20algorithm (defined in Internet :rfc:`1321`). The terms secure hash and message
 21digest are interchangeable.  Older algorithms were called message digests.  The
 22modern term is secure hash.
 23
 24.. note::
 25   If you want the adler32 or crc32 hash functions they are available in
 26   the :mod:`zlib` module.
 27
 28.. warning::
 29
 30   Some algorithms have known hash collision weaknesses, see the FAQ at the end.
 31
 32There is one constructor method named for each type of :dfn:`hash`.  All return
 33a hash object with the same simple interface. For example: use :func:`sha1` to
 34create a SHA1 hash object. You can now feed this object with arbitrary strings
 35using the :meth:`update` method.  At any point you can ask it for the
 36:dfn:`digest` of the concatenation of the strings fed to it so far using the
 37:meth:`digest` or :meth:`hexdigest` methods.
 38
 39.. index:: single: OpenSSL; (use in module hashlib)
 40
 41Constructors for hash algorithms that are always present in this module are
 42:func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, and
 43:func:`sha512`.  Additional algorithms may also be available depending upon the
 44OpenSSL library that Python uses on your platform.
 45
 46For example, to obtain the digest of the string ``'Nobody inspects the spammish
 47repetition'``:
 48
 49   >>> import hashlib
 50   >>> m = hashlib.md5()
 51   >>> m.update("Nobody inspects")
 52   >>> m.update(" the spammish repetition")
 53   >>> m.digest()
 54   '\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
 55   >>> m.digest_size
 56   16
 57   >>> m.block_size
 58   64
 59
 60More condensed:
 61
 62   >>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
 63   'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
 64
 65A generic :func:`new` constructor that takes the string name of the desired
 66algorithm as its first parameter also exists to allow access to the above listed
 67hashes as well as any other algorithms that your OpenSSL library may offer.  The
 68named constructors are much faster than :func:`new` and should be preferred.
 69
 70Using :func:`new` with an algorithm provided by OpenSSL:
 71
 72   >>> h = hashlib.new('ripemd160')
 73   >>> h.update("Nobody inspects the spammish repetition")
 74   >>> h.hexdigest()
 75   'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'
 76
 77The following values are provided as constant attributes of the hash objects
 78returned by the constructors:
 79
 80
 81.. data:: digest_size
 82
 83   The size of the resulting hash in bytes.
 84
 85.. data:: block_size
 86
 87   The internal block size of the hash algorithm in bytes.
 88
 89A hash object has the following methods:
 90
 91
 92.. method:: hash.update(arg)
 93
 94   Update the hash object with the string *arg*.  Repeated calls are equivalent to
 95   a single call with the concatenation of all the arguments: ``m.update(a);
 96   m.update(b)`` is equivalent to ``m.update(a+b)``.
 97
 98
 99.. method:: hash.digest()
100
101   Return the digest of the strings passed to the :meth:`update` method so far.
102   This is a string of :attr:`digest_size` bytes which may contain non-ASCII
103   characters, including null bytes.
104
105
106.. method:: hash.hexdigest()
107
108   Like :meth:`digest` except the digest is returned as a string of double length,
109   containing only hexadecimal digits.  This may  be used to exchange the value
110   safely in email or other non-binary environments.
111
112
113.. method:: hash.copy()
114
115   Return a copy ("clone") of the hash object.  This can be used to efficiently
116   compute the digests of strings that share a common initial substring.
117
118
119.. seealso::
120
121   Module :mod:`hmac`
122      A module to generate message authentication codes using hashes.
123
124   Module :mod:`base64`
125      Another way to encode binary hashes for non-binary environments.
126
127   http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
128      The FIPS 180-2 publication on Secure Hash Algorithms.
129
130   http://www.cryptography.com/cnews/hash.html
131      Hash Collision FAQ with information on which algorithms have known issues and
132      what that means regarding their use.
133