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
  17 This module implements a common interface to many different secure hash and
  18 message digest algorithms.  Included are the FIPS secure hash algorithms SHA1,
  19 SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5
  20 algorithm (defined in Internet :rfc:`1321`). The terms secure hash and message
  21 digest are interchangeable.  Older algorithms were called message digests.  The
  22 modern 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
  32 There is one constructor method named for each type of :dfn:`hash`.  All return
  33 a hash object with the same simple interface. For example: use :func:`sha1` to
  34 create a SHA1 hash object. You can now feed this object with arbitrary strings
  35 using 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
  41 Constructors 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
  44 OpenSSL library that Python uses on your platform.
  45
  46 For example, to obtain the digest of the string ``'Nobody inspects the spammish
  47 repetition'``:
  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
  60 More condensed:
  61
  62    >>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
  63    'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
  64
  65 A generic :func:`new` constructor that takes the string name of the desired
  66 algorithm as its first parameter also exists to allow access to the above listed
  67 hashes as well as any other algorithms that your OpenSSL library may offer.  The
  68 named constructors are much faster than :func:`new` and should be preferred.
  69
  70 Using :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
  77 The following values are provided as constant attributes of the hash objects
  78 returned 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
  89 A 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    .. versionchanged:: 2.7
  99
 100       The Python GIL is released to allow other threads to run while
 101       hash updates on data larger than 2048 bytes is taking place when
 102       using hash algorithms supplied by OpenSSL.
 103
 104
 105 .. method:: hash.digest()
 106
 107    Return the digest of the strings passed to the :meth:`update` method so far.
 108    This is a string of :attr:`digest_size` bytes which may contain non-ASCII
 109    characters, including null bytes.
 110
 111
 112 .. method:: hash.hexdigest()
 113
 114    Like :meth:`digest` except the digest is returned as a string of double length,
 115    containing only hexadecimal digits.  This may  be used to exchange the value
 116    safely in email or other non-binary environments.
 117
 118
 119 .. method:: hash.copy()
 120
 121    Return a copy ("clone") of the hash object.  This can be used to efficiently
 122    compute the digests of strings that share a common initial substring.
 123
 124
 125 .. seealso::
 126
 127    Module :mod:`hmac`
 128       A module to generate message authentication codes using hashes.
 129
 130    Module :mod:`base64`
 131       Another way to encode binary hashes for non-binary environments.
 132
 133    http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
 134       The FIPS 180-2 publication on Secure Hash Algorithms.
 135
 136    http://www.cryptography.com/cnews/hash.html
 137       Hash Collision FAQ with information on which algorithms have known issues and
 138       what that means regarding their use.
 139