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
19This module implements the interface to NIST's secure hash  algorithm, known as
20SHA-1.  SHA-1 is an improved version of the original SHA hash algorithm.  It is
21used in the same way as the :mod:`md5` module: use :func:`new` to create an sha
22object, then feed this object with arbitrary strings using the :meth:`update`
23method, and at any point you can ask it for the :dfn:`digest` of the
24concatenation of the strings fed to it so far.  SHA-1 digests are 160 bits
25instead 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
33The following values are provided as constants in the module and as attributes
34of 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
47An 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
88