Mercurial > cpython-lru_cache-weakref

annotate Doc/library/hashlib.rst @ 54294:dba767bc3155 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
remove mention of old ctypes version
author Benjamin Peterson <benjamin@python.org>
date Sat, 23 May 2009 20:59:09 +0000
parents e4ff4273493b
children 3aff597910c4
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2 :mod:`hashlib` --- Secure hashes and message digests
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 ====================================================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 .. module:: hashlib
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 :synopsis: Secure hash and message digest algorithms.
50788
e11c99e1e6e7 Merged revisions 68521,68527,68534-68536,68540,68547,68552,68563,68570,68572,68575,68579-68580,68584 via svnmerge from
Georg Brandl <georg@python.org>
parents: 46014
diff changeset
7 .. moduleauthor:: Gregory P. Smith <greg@krypto.org>
e11c99e1e6e7 Merged revisions 68521,68527,68534-68536,68540,68547,68552,68563,68570,68572,68575,68579-68580,68584 via svnmerge from
Georg Brandl <georg@python.org>
parents: 46014
diff changeset
8 .. sectionauthor:: Gregory P. Smith <greg@krypto.org>
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 .. versionadded:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 single: message digest, MD5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 single: secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 This module implements a common interface to many different secure hash and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 message digest algorithms. Included are the FIPS secure hash algorithms SHA1,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 algorithm (defined in Internet :rfc:`1321`). The terms secure hash and message
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 digest are interchangeable. Older algorithms were called message digests. The
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 modern term is secure hash.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23
45895
19d4b697fbf9 Mention that crc32 and adler32 are available in a different module (zlib).
Gregory P. Smith <greg@mad-scientist.com>
parents: 43773
diff changeset
24 .. note::
19d4b697fbf9 Mention that crc32 and adler32 are available in a different module (zlib).
Gregory P. Smith <greg@mad-scientist.com>
parents: 43773
diff changeset
25 If you want the adler32 or crc32 hash functions they are available in
19d4b697fbf9 Mention that crc32 and adler32 are available in a different module (zlib).
Gregory P. Smith <greg@mad-scientist.com>
parents: 43773
diff changeset
26 the :mod:`zlib` module.
19d4b697fbf9 Mention that crc32 and adler32 are available in a different module (zlib).
Gregory P. Smith <greg@mad-scientist.com>
parents: 43773
diff changeset
27
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 .. warning::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 Some algorithms have known hash collision weaknesses, see the FAQ at the end.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 There is one constructor method named for each type of :dfn:`hash`. All return
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 a hash object with the same simple interface. For example: use :func:`sha1` to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 create a SHA1 hash object. You can now feed this object with arbitrary strings
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 using the :meth:`update` method. At any point you can ask it for the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 :dfn:`digest` of the concatenation of the strings fed to it so far using the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 :meth:`digest` or :meth:`hexdigest` methods.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 42604
diff changeset
39 .. index:: single: OpenSSL; (use in module hashlib)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 Constructors for hash algorithms that are always present in this module are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 :func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43 :func:`sha512`. Additional algorithms may also be available depending upon the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 OpenSSL library that Python uses on your platform.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 For example, to obtain the digest of the string ``'Nobody inspects the spammish
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 45895
diff changeset
47 repetition'``:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 >>> import hashlib
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 >>> m = hashlib.md5()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51 >>> m.update("Nobody inspects")
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 >>> m.update(" the spammish repetition")
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 >>> m.digest()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
54 '\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
43773
d7db467cd940 Fixes Issue 1385: The hmac module now computes the correct hmac when using
Gregory P. Smith <greg@mad-scientist.com>
parents: 43325
diff changeset
55 >>> m.digest_size
d7db467cd940 Fixes Issue 1385: The hmac module now computes the correct hmac when using
Gregory P. Smith <greg@mad-scientist.com>
parents: 43325
diff changeset
56 16
d7db467cd940 Fixes Issue 1385: The hmac module now computes the correct hmac when using
Gregory P. Smith <greg@mad-scientist.com>
parents: 43325
diff changeset
57 >>> m.block_size
d7db467cd940 Fixes Issue 1385: The hmac module now computes the correct hmac when using
Gregory P. Smith <greg@mad-scientist.com>
parents: 43325
diff changeset
58 64
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 45895
diff changeset
60 More condensed:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 >>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 A generic :func:`new` constructor that takes the string name of the desired
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 algorithm as its first parameter also exists to allow access to the above listed
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 hashes as well as any other algorithms that your OpenSSL library may offer. The
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68 named constructors are much faster than :func:`new` and should be preferred.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69
46014
31cf38bdaac0 Enable doctest running for several other documents.
Georg Brandl <georg@python.org>
parents: 45895
diff changeset
70 Using :func:`new` with an algorithm provided by OpenSSL:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 >>> h = hashlib.new('ripemd160')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 >>> h.update("Nobody inspects the spammish repetition")
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
74 >>> h.hexdigest()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
75 'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 The following values are provided as constant attributes of the hash objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 returned by the constructors:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 .. data:: digest_size
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82
43773
d7db467cd940 Fixes Issue 1385: The hmac module now computes the correct hmac when using
Gregory P. Smith <greg@mad-scientist.com>
parents: 43325
diff changeset
83 The size of the resulting hash in bytes.
d7db467cd940 Fixes Issue 1385: The hmac module now computes the correct hmac when using
Gregory P. Smith <greg@mad-scientist.com>
parents: 43325
diff changeset
84
d7db467cd940 Fixes Issue 1385: The hmac module now computes the correct hmac when using
Gregory P. Smith <greg@mad-scientist.com>
parents: 43325
diff changeset
85 .. data:: block_size
d7db467cd940 Fixes Issue 1385: The hmac module now computes the correct hmac when using
Gregory P. Smith <greg@mad-scientist.com>
parents: 43325
diff changeset
86
d7db467cd940 Fixes Issue 1385: The hmac module now computes the correct hmac when using
Gregory P. Smith <greg@mad-scientist.com>
parents: 43325
diff changeset
87 The internal block size of the hash algorithm in bytes.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89 A hash object has the following methods:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 .. method:: hash.update(arg)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 Update the hash object with the string *arg*. Repeated calls are equivalent to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 a single call with the concatenation of all the arguments: ``m.update(a);
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 m.update(b)`` is equivalent to ``m.update(a+b)``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97
53726
e4ff4273493b Issue #4751: For hashlib algorithms provided by OpenSSL, the Python
Gregory P. Smith <greg@mad-scientist.com>
parents: 50788
diff changeset
98 .. versionchanged:: 2.7
e4ff4273493b Issue #4751: For hashlib algorithms provided by OpenSSL, the Python
Gregory P. Smith <greg@mad-scientist.com>
parents: 50788
diff changeset
99
e4ff4273493b Issue #4751: For hashlib algorithms provided by OpenSSL, the Python
Gregory P. Smith <greg@mad-scientist.com>
parents: 50788
diff changeset
100 The Python GIL is released to allow other threads to run while
e4ff4273493b Issue #4751: For hashlib algorithms provided by OpenSSL, the Python
Gregory P. Smith <greg@mad-scientist.com>
parents: 50788
diff changeset
101 hash updates on data larger than 2048 bytes is taking place when
e4ff4273493b Issue #4751: For hashlib algorithms provided by OpenSSL, the Python
Gregory P. Smith <greg@mad-scientist.com>
parents: 50788
diff changeset
102 using hash algorithms supplied by OpenSSL.
e4ff4273493b Issue #4751: For hashlib algorithms provided by OpenSSL, the Python
Gregory P. Smith <greg@mad-scientist.com>
parents: 50788
diff changeset
103
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 .. method:: hash.digest()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
106
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 Return the digest of the strings passed to the :meth:`update` method so far.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 This is a string of :attr:`digest_size` bytes which may contain non-ASCII
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109 characters, including null bytes.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
110
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
111
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
112 .. method:: hash.hexdigest()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
113
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
114 Like :meth:`digest` except the digest is returned as a string of double length,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 containing only hexadecimal digits. This may be used to exchange the value
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116 safely in email or other non-binary environments.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 .. method:: hash.copy()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 Return a copy ("clone") of the hash object. This can be used to efficiently
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 compute the digests of strings that share a common initial substring.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125 .. seealso::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
126
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 Module :mod:`hmac`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128 A module to generate message authentication codes using hashes.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
129
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
130 Module :mod:`base64`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
131 Another way to encode binary hashes for non-binary environments.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
132
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
134 The FIPS 180-2 publication on Secure Hash Algorithms.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
135
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
136 http://www.cryptography.com/cnews/hash.html
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
137 Hash Collision FAQ with information on which algorithms have known issues and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
138 what that means regarding their use.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
139