Doc/library/sha.rst

   1
   2 :mod:`sha` --- SHA-1 message digest algorithm
   3 =============================================
   4
   5 .. module:: sha
   6    :synopsis: NIST's secure hash algorithm, SHA.
   7    :deprecated:
   8 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
   9
  10
  11 .. deprecated:: 2.5
  12    Use the :mod:`hashlib` module instead.
  13
  14 .. index::
  15    single: NIST
  16    single: Secure Hash Algorithm
  17    single: checksum; SHA
  18
  19 This module implements the interface to NIST's secure hash  algorithm, known as
  20 SHA-1.  SHA-1 is an improved version of the original SHA hash algorithm.  It is
  21 used in the same way as the :mod:`md5` module: use :func:`new` to create an sha
  22 object, then feed this object with arbitrary strings using the :meth:`update`
  23 method, and at any point you can ask it for the :dfn:`digest` of the
  24 concatenation of the strings fed to it so far.  SHA-1 digests are 160 bits
  25 instead of MD5's 128 bits.
  26
  27
  28 .. function:: new([string])
  29
  30    Return a new sha object.  If *string* is present, the method call
  31    ``update(string)`` is made.
  32
  33 The following values are provided as constants in the module and as attributes
  34 of the sha objects returned by :func:`new`:
  35
  36
  37 .. data:: blocksize
  38
  39    Size of the blocks fed into the hash function; this is always ``1``.  This size
  40    is used to allow an arbitrary string to be hashed.
  41
  42
  43 .. data:: digest_size
  44
  45    The size of the resulting digest in bytes.  This is always ``20``.
  46
  47 An sha object has the same methods as md5 objects:
  48
  49
  50 .. method:: sha.update(arg)
  51
  52    Update the sha object with the string *arg*.  Repeated calls are equivalent to a
  53    single call with the concatenation of all the arguments: ``m.update(a);
  54    m.update(b)`` is equivalent to ``m.update(a+b)``.
  55
  56
  57 .. method:: sha.digest()
  58
  59    Return the digest of the strings passed to the :meth:`update` method so far.
  60    This is a 20-byte string which may contain non-ASCII characters, including null
  61    bytes.
  62
  63
  64 .. method:: sha.hexdigest()
  65
  66    Like :meth:`digest` except the digest is returned as a string of length 40,
  67    containing only hexadecimal digits.  This may  be used to exchange the value
  68    safely in email or other non-binary environments.
  69
  70
  71 .. method:: sha.copy()
  72
  73    Return a copy ("clone") of the sha object.  This can be used to efficiently
  74    compute the digests of strings that share a common initial substring.
  75
  76
  77 .. seealso::
  78
  79    `Secure Hash Standard <http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf>`_
  80       The Secure Hash Algorithm is defined by NIST document FIPS PUB 180-2: `Secure
  81       Hash Standard
  82       <http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf>`_,
  83       published in August 2002.
  84
  85    `Cryptographic Toolkit (Secure Hashing) <http://csrc.nist.gov/CryptoToolkit/tkhash.html>`_
  86       Links from NIST to various information on secure hashing.
  87