Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libhashlib.tex @ 37850:ebe59cd18273

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Use explicit relative import for an, ehm, relative import.
author Thomas Wouters <thomas@python.org>
date Tue, 18 Apr 2006 21:41:36 +0000
parents 78bd78a1ce74
children 5a6c7d6def0c
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
9330080a3d41 whoops, missed adding this last night in my hashlib commit
Gregory P. Smith <greg@mad-scientist.com>
parents:
diff changeset
34 be available depending upon the OpenSSL library python uses on your platform.
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}