Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libsha.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents 6990fe9c40f6
children 0a150ea8cbea
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
10735
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \section{\module{sha} ---
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
2 SHA message digest algorithm}
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 \declaremodule{builtin}{sha}
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
5 \modulesynopsis{NIST's secure hash algorithm, SHA.}
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
7
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9 This module implements the interface to NIST's\index{NIST} secure hash
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10 algorithm,\index{Secure Hash Algorithm} known as SHA. It is used in
14659
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
11 the same way as the \refmodule{md5} module:\ use \function{new()}
10735
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
12 to create an sha object, then feed this object with arbitrary strings
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
13 using the \method{update()} method, and at any point you can ask it
13625
fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope
Thomas Wouters <thomas@python.org>
parents: 11458
diff changeset
14 for the \dfn{digest} of the concatenation of the strings fed to it
14659
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
15 so far.\index{checksum!SHA} SHA digests are 160 bits instead of
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
16 MD5's 128 bits.
10735
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
17
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
18
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
19 \begin{funcdesc}{new}{\optional{string}}
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
20 Return a new sha object. If \var{string} is present, the method
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
21 call \code{update(\var{string})} is made.
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
22 \end{funcdesc}
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
23
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
24
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
25 The following values are provided as constants in the module and as
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
26 attributes of the sha objects returned by \function{new()}:
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
27
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
28 \begin{datadesc}{blocksize}
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29 Size of the blocks fed into the hash function; this is always
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30 \code{1}. This size is used to allow an arbitrary string to be
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
31 hashed.
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
32 \end{datadesc}
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
33
20844
6990fe9c40f6 [Patch #476612] Change docs to describe PEP247 interface
Andrew M. Kuchling <amk@amk.ca>
parents: 19779
diff changeset
34 \begin{datadesc}{digest_size}
10735
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35 The size of the resulting digest in bytes. This is always
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
36 \code{20}.
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
37 \end{datadesc}
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39
14659
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
40 An sha object has the same methods as md5 objects:
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
41
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
42 \begin{methoddesc}[sha]{update}{arg}
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
43 Update the sha object with the string \var{arg}. Repeated calls are
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
44 equivalent to a single call with the concatenation of all the
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 14659
diff changeset
45 arguments: \code{m.update(a); m.update(b)} is equivalent to
14659
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
46 \code{m.update(a+b)}.
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
47 \end{methoddesc}
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
48
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
49 \begin{methoddesc}[sha]{digest}{}
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
50 Return the digest of the strings passed to the \method{update()}
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
51 method so far. This is a 20-byte string which may contain
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
52 non-\ASCII{} characters, including null bytes.
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
53 \end{methoddesc}
10735
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
54
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
55 \begin{methoddesc}[sha]{hexdigest}{}
14659
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
56 Like \method{digest()} except the digest is returned as a string of
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
57 length 40, containing only hexadecimal digits. This may
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
58 be used to exchange the value safely in email or other non-binary
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
59 environments.
10735
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60 \end{methoddesc}
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
61
14659
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
62 \begin{methoddesc}[sha]{copy}{}
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
63 Return a copy (``clone'') of the sha object. This can be used to
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
64 efficiently compute the digests of strings that share a common initial
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
65 substring.
699fbbba29a7 Repaired some glitches in the MD5 and SHA docs; copied the descriptions of
Tim Peters <tim.peters@gmail.com>
parents: 14619
diff changeset
66 \end{methoddesc}
10735
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
68 \begin{seealso}
19604
4ac9a44c7e47 Update the links to the FIPS document that defines the Secure Hash
Fred Drake <fdrake@acm.org>
parents: 18416
diff changeset
69 \seetitle[http://csrc.nist.gov/publications/fips/fips180-1/fip180-1.txt]
4ac9a44c7e47 Update the links to the FIPS document that defines the Secure Hash
Fred Drake <fdrake@acm.org>
parents: 18416
diff changeset
70 {Secure Hash Standard}
4ac9a44c7e47 Update the links to the FIPS document that defines the Secure Hash
Fred Drake <fdrake@acm.org>
parents: 18416
diff changeset
71 {The Secure Hash Algorithm is defined by NIST document FIPS
4ac9a44c7e47 Update the links to the FIPS document that defines the Secure Hash
Fred Drake <fdrake@acm.org>
parents: 18416
diff changeset
72 PUB 180-1:
4ac9a44c7e47 Update the links to the FIPS document that defines the Secure Hash
Fred Drake <fdrake@acm.org>
parents: 18416
diff changeset
73 \citetitle[http://csrc.nist.gov/publications/fips/fips180-1/fip180-1.txt]
4ac9a44c7e47 Update the links to the FIPS document that defines the Secure Hash
Fred Drake <fdrake@acm.org>
parents: 18416
diff changeset
74 {Secure Hash Standard}, published in April of 1995. It is
4ac9a44c7e47 Update the links to the FIPS document that defines the Secure Hash
Fred Drake <fdrake@acm.org>
parents: 18416
diff changeset
75 available online as plain text (at least one diagram was
4ac9a44c7e47 Update the links to the FIPS document that defines the Secure Hash
Fred Drake <fdrake@acm.org>
parents: 18416
diff changeset
76 omitted) and as PDF at
4ac9a44c7e47 Update the links to the FIPS document that defines the Secure Hash
Fred Drake <fdrake@acm.org>
parents: 18416
diff changeset
77 \url{http://csrc.nist.gov/publications/fips/fips180-1/fip180-1.pdf}.}
19779
07bb09df3324 Added an additional link to NIST information on secure hashing.
Fred Drake <fdrake@acm.org>
parents: 19604
diff changeset
78
07bb09df3324 Added an additional link to NIST information on secure hashing.
Fred Drake <fdrake@acm.org>
parents: 19604
diff changeset
79 \seetitle[http://csrc.nist.gov/encryption/tkhash.html]
07bb09df3324 Added an additional link to NIST information on secure hashing.
Fred Drake <fdrake@acm.org>
parents: 19604
diff changeset
80 {Cryptographic Toolkit (Secure Hashing)}
07bb09df3324 Added an additional link to NIST information on secure hashing.
Fred Drake <fdrake@acm.org>
parents: 19604
diff changeset
81 {Links from NIST to various information on secure hashing.}
10735
7442ccedd5fd Add section for the sha module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82 \end{seealso}