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