Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libhashlib.tex @ 39042:c02fa187e0f4 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Part of SF patch #1484695. This removes dead code. The chksum was already verified in .frombuf() on the lines above. If there was a problem an exception is raised, so there was no way this condition could have been true.
author Neal Norwitz <nnorwitz@gmail.com>
date Mon, 10 Jul 2006 00:23:17 +0000
parents 5a6c7d6def0c
children e85d5b20ea60
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
35378
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
1 \section{\module{hashlib} ---
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
2 Secure hashes and message digests}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
3
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
4 \declaremodule{builtin}{hashlib}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
5 \modulesynopsis{Secure hash and message digest algorithms.}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
6 \moduleauthor{Gregory P. Smith}{greg@users.sourceforge.net}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
7 \sectionauthor{Gregory P. Smith}{greg@users.sourceforge.net}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
8
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
9 \versionadded{2.5}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
10
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
11 \index{message digest, MD5}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
12 \index{secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
13
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
14 This module implements a common interface to many different secure hash and
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
15 message digest algorithms. Included are the FIPS secure hash algorithms SHA1,
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
16 SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
17 algorithm (defined in Internet \rfc{1321}).
36391
78bd78a1ce74 Correct misspellings.
Georg Brandl <georg@python.org>
parents: 35378
diff changeset
18 The terms secure hash and message digest are interchangeable. Older
35378
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
19 algorithms were called message digests. The modern term is secure hash.
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
20
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
21 \warning{Some algorithms have known hash collision weaknesses, see the FAQ at the end.}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
22
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
23 There is one constructor method named for each type of \dfn{hash}. All return
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
24 a hash object with the same simple interface.
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
25 For example: use \function{sha1()} to create a SHA1 hash object.
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
26 You can now feed this object with arbitrary strings using the \method{update()}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
27 method. At any point you can ask it for the \dfn{digest} of the concatenation
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
28 of the strings fed to it so far using the \method{digest()} or
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
29 \method{hexdigest()} methods.
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
30
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
31 Constructors for hash algorithms that are always present in this module are
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
32 \function{md5()}, \function{sha1()}, \function{sha224()}, \function{sha256()},
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
33 \function{sha384()}, and \function{sha512()}. Additional algorithms may also
37395
5a6c7d6def0c Grammar fix
Andrew M. Kuchling <amk@amk.ca>
parents: 36391
diff changeset
34 be available depending upon the OpenSSL library that Python uses on your platform.
35378
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
35 \index{OpenSSL}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
36
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
37 For example, to obtain the digest of the string \code{'Nobody inspects
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
38 the spammish repetition'}:
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
39
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
40 \begin{verbatim}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
41 >>> import hashlib
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
42 >>> m = hashlib.md5()
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
43 >>> m.update("Nobody inspects")
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
44 >>> m.update(" the spammish repetition")
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
45 >>> m.digest()
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
46 '\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
47 \end{verbatim}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
48
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
49 More condensed:
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
50
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
51 \begin{verbatim}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
52 >>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
53 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
54 \end{verbatim}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
55
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
56 A generic \function{new()} constructor that takes the string name of the
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
57 desired algorithm as its first parameter also exists to allow access to the
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
58 above listed hashes as well as any other algorithms that your OpenSSL library
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
59 may offer. The named constructors are much faster than \function{new()} and
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
60 should be preferred.
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
61
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
62 Using \function{new()} with an algorithm provided by OpenSSL:
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
63
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
64 \begin{verbatim}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
65 >>> h = hashlib.new('ripemd160')
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
66 >>> h.update("Nobody inspects the spammish repetition")
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
67 >>> h.hexdigest()
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
68 'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
69 \end{verbatim}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
70
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
71 The following values are provided as constant attributes of the hash objects
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
72 returned by the constructors:
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
73
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
74 \begin{datadesc}{digest_size}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
75 The size of the resulting digest in bytes.
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
76 \end{datadesc}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
77
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
78 A hash object has the following methods:
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
79
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
80 \begin{methoddesc}[hash]{update}{arg}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
81 Update the hash object with the string \var{arg}. Repeated calls are
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
82 equivalent to a single call with the concatenation of all the
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
83 arguments: \code{m.update(a); m.update(b)} is equivalent to
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
84 \code{m.update(a+b)}.
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
85 \end{methoddesc}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
86
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
87 \begin{methoddesc}[hash]{digest}{}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
88 Return the digest of the strings passed to the \method{update()}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
89 method so far. This is a 16-byte string which may contain
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
90 non-\ASCII{} characters, including null bytes.
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
91 \end{methoddesc}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
92
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
93 \begin{methoddesc}[hash]{hexdigest}{}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
94 Like \method{digest()} except the digest is returned as a string of
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
95 double length, containing only hexadecimal digits. This may
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
96 be used to exchange the value safely in email or other non-binary
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
97 environments.
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
98 \end{methoddesc}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
99
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
100 \begin{methoddesc}[hash]{copy}{}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
101 Return a copy (``clone'') of the hash object. This can be used to
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
102 efficiently compute the digests of strings that share a common initial
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
103 substring.
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
104 \end{methoddesc}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
105
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
106 \begin{seealso}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
107 \seemodule{hmac}{A module to generate message authentication codes using hashes.}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
108 \seemodule{base64}{Another way to encode binary hashes for non-binary environments.}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
109 \seeurl{http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
110 {The FIPS 180-2 publication on Secure Hash Algorithms.}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
111 \seeurl{http://www.cryptography.com/cnews/hash.html}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
112 {Hash Collision FAQ with information on which algorithms have known issues and
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
113 what that means regarding their use.}
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
114 \end{seealso}