Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(11590)

Delta Between Two Patch Sets: Doc/library/hashlib.rst

Issue 16113: Add SHA-3 (Keccak) support
Left Patch Set: Created 3 years, 3 months ago
Right Patch Set: Created 3 years ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « no previous file | Lib/hashlib.py » ('j') | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
1 :mod:`hashlib` --- Secure hashes and message digests 1 :mod:`hashlib` --- Secure hashes and message digests
2 ==================================================== 2 ====================================================
3 3
4 .. module:: hashlib 4 .. module:: hashlib
5 :synopsis: Secure hash and message digest algorithms. 5 :synopsis: Secure hash and message digest algorithms.
6
6 .. moduleauthor:: Gregory P. Smith <greg@krypto.org> 7 .. moduleauthor:: Gregory P. Smith <greg@krypto.org>
7 .. sectionauthor:: Gregory P. Smith <greg@krypto.org> 8 .. sectionauthor:: Gregory P. Smith <greg@krypto.org>
8 9
10 **Source code:** :source:`Lib/hashlib.py`
9 11
10 .. index:: 12 .. index::
gregory.p.smith 2016/06/02 23:41:52 add new algorithms to the index?
11 single: message digest, MD5 13 single: message digest, MD5
12 single: secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512 14 single: secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512
13 15
14 **Source code:** :source:`Lib/hashlib.py` 16 .. testsetup::
17
18 import hashlib
19
15 20
16 -------------- 21 --------------
17 22
18 This module implements a common interface to many different secure hash and 23 This module implements a common interface to many different secure hash and
19 message digest algorithms. Included are the FIPS secure hash algorithms SHA1, 24 message digest algorithms. Included are the FIPS secure hash algorithms SHA1,
20 SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5 25 SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5
21 algorithm (defined in Internet :rfc:`1321`). The terms "secure hash" and 26 algorithm (defined in Internet :rfc:`1321`). The terms "secure hash" and
22 "message digest" are interchangeable. Older algorithms were called message 27 "message digest" are interchangeable. Older algorithms were called message
23 digests. The modern term is secure hash. 28 digests. The modern term is secure hash.
24 29
25 .. note:: 30 .. note::
26 31
27 If you want the adler32 or crc32 hash functions, they are available in 32 If you want the adler32 or crc32 hash functions, they are available in
28 the :mod:`zlib` module. 33 the :mod:`zlib` module.
29 34
30 .. warning:: 35 .. warning::
31 36
32 Some algorithms have known hash collision weaknesses, refer to the "See 37 Some algorithms have known hash collision weaknesses, refer to the "See
33 also" section at the end. 38 also" section at the end.
34 39
35 40
36 .. _hash-algorithms: 41 .. _hash-algorithms:
37 42
38 Hash algorithms 43 Hash algorithms
39 --------------- 44 ---------------
40 45
41 There is one constructor method named for each type of :dfn:`hash`. All return 46 There is one constructor method named for each type of :dfn:`hash`. All return
42 a hash object with the same simple interface. For example: use :func:`sha1` to 47 a hash object with the same simple interface. For example: use :func:`sha256` to
43 create a SHA1 hash object. You can now feed this object with :term:`bytes-like 48 create a SHA-256 hash object. You can now feed this object with :term:`bytes-lik e
44 objects <bytes-like object>` (normally :class:`bytes`) using the :meth:`update` method. 49 objects <bytes-like object>` (normally :class:`bytes`) using the :meth:`update` method.
45 At any point you can ask it for the :dfn:`digest` of the 50 At any point you can ask it for the :dfn:`digest` of the
46 concatenation of the data fed to it so far using the :meth:`digest` or 51 concatenation of the data fed to it so far using the :meth:`digest` or
47 :meth:`hexdigest` methods. 52 :meth:`hexdigest` methods.
48 53
49 .. note:: 54 .. note::
50 55
51 For better multithreading performance, the Python :term:`GIL` is released for 56 For better multithreading performance, the Python :term:`GIL` is released for
52 data larger than 2047 bytes at object creation or on update. 57 data larger than 2047 bytes at object creation or on update.
53 58
54 .. note:: 59 .. note::
55 60
56 Feeding string objects into :meth:`update` is not supported, as hashes work 61 Feeding string objects into :meth:`update` is not supported, as hashes work
57 on bytes, not on characters. 62 on bytes, not on characters.
58 63
59 .. index:: single: OpenSSL; (use in module hashlib) 64 .. index:: single: OpenSSL; (use in module hashlib)
60 65
61 Constructors for hash algorithms that are always present in this module are 66 Constructors for hash algorithms that are always present in this module are
62 :func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, 67 :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`,
63 and :func:`sha512`. Additional algorithms may also be available depending upon 68 and :func:`sha512`. :func:`md5` is normally available as well, though it
64 the OpenSSL library that Python uses on your platform. 69 may be missing if you are using a rare "FIPS compliant" build of Python.
65 70 Additional algorithms may also be available depending upon the OpenSSL
66 Python provides additional hash algorithms on all common and modern platforms. 71 library that Python uses on your platform. On most platforms the
gregory.p.smith 2016/06/02 23:41:52 I don't like this paragraph. It calls things hist
67 Some historic platforms or compilers don't have the necessary features to 72 :func:`sha3_224`, :func:`sha3_256`, :func:`sha3_384`, :func:`sha3_512`,
68 compile the implementations. The algorithms are available on all recent Unix 73 :func:`shake_128`, :func:`shake_256` are also available.
69 and Windows systems with X86, X86_64 and ARMv6+ CPUs.
70 74
71 .. versionadded:: 3.6 75 .. versionadded:: 3.6
72 SHA3 (Keccak) and SHAKE constructors :func:`sha3_224`, :func:`sha3_256`, 76 SHA3 (Keccak) and SHAKE constructors :func:`sha3_224`, :func:`sha3_256`,
73 :func:`sha3_384`, :func:`sha3_512`, :func:`shake_128`, :func:`shake_256`. 77 :func:`sha3_384`, :func:`sha3_512`, :func:`shake_128`, :func:`shake_256`.
74 78
75 For example, to obtain the digest of the byte string ``b'Nobody inspects the 79 For example, to obtain the digest of the byte string ``b'Nobody inspects the
76 spammish repetition'``:: 80 spammish repetition'``::
77 81
78 >>> import hashlib 82 >>> import hashlib
79 >>> m = hashlib.md5() 83 >>> m = hashlib.sha256()
80 >>> m.update(b"Nobody inspects") 84 >>> m.update(b"Nobody inspects")
81 >>> m.update(b" the spammish repetition") 85 >>> m.update(b" the spammish repetition")
82 >>> m.digest() 86 >>> m.digest()
83 b'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9' 87 b'\x03\x1e\xdd}Ae\x15\x93\xc5\xfe\\\x00o\xa5u+7\xfd\xdf\xf7\xbcN\x84:\xa6\xaf \x0c\x95\x0fK\x94\x06'
84 >>> m.digest_size 88 >>> m.digest_size
85 16 89 32
86 >>> m.block_size 90 >>> m.block_size
87 64 91 64
88 92
89 More condensed: 93 More condensed:
90 94
91 >>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest() 95 >>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest()
92 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2' 96 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
93 97
94 .. function:: new(name[, data]) 98 .. function:: new(name[, data])
95 99
96 Is a generic constructor that takes the string name of the desired 100 Is a generic constructor that takes the string name of the desired
97 algorithm as its first parameter. It also exists to allow access to the 101 algorithm as its first parameter. It also exists to allow access to the
98 above listed hashes as well as any other algorithms that your OpenSSL 102 above listed hashes as well as any other algorithms that your OpenSSL
99 library may offer. The named constructors are much faster than :func:`new` 103 library may offer. The named constructors are much faster than :func:`new`
100 and should be preferred. 104 and should be preferred.
101 105
102 Using :func:`new` with an algorithm provided by OpenSSL: 106 Using :func:`new` with an algorithm provided by OpenSSL:
103 107
104 >>> h = hashlib.new('ripemd160') 108 >>> h = hashlib.new('ripemd160')
105 >>> h.update(b"Nobody inspects the spammish repetition") 109 >>> h.update(b"Nobody inspects the spammish repetition")
106 >>> h.hexdigest() 110 >>> h.hexdigest()
107 'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc' 111 'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'
108 112
109 Hashlib provides the following constant attributes: 113 Hashlib provides the following constant attributes:
110 114
111 .. data:: algorithms_guaranteed 115 .. data:: algorithms_guaranteed
112 116
113 A set containing the names of the hash algorithms guaranteed to be supported 117 A set containing the names of the hash algorithms guaranteed to be supported
114 by this module on all platforms. 118 by this module on all platforms. Note that 'md5' is in this list despite
119 some upstream vendors offering an odd "FIPS compliant" Python build that
120 excludes it.
115 121
116 .. versionadded:: 3.2 122 .. versionadded:: 3.2
117 123
118 .. data:: algorithms_available 124 .. data:: algorithms_available
119 125
120 A set containing the names of the hash algorithms that are available in the 126 A set containing the names of the hash algorithms that are available in the
121 running Python interpreter. These names will be recognized when passed to 127 running Python interpreter. These names will be recognized when passed to
122 :func:`new`. :attr:`algorithms_guaranteed` will always be a subset. The 128 :func:`new`. :attr:`algorithms_guaranteed` will always be a subset. The
123 same algorithm may appear multiple times in this set under different names 129 same algorithm may appear multiple times in this set under different names
124 (thanks to OpenSSL). 130 (thanks to OpenSSL).
(...skipping 53 matching lines...) Expand 10 before | Expand all | Expand 10 after
178 double length, containing only hexadecimal digits. This may be used to 184 double length, containing only hexadecimal digits. This may be used to
179 exchange the value safely in email or other non-binary environments. 185 exchange the value safely in email or other non-binary environments.
180 186
181 187
182 .. method:: hash.copy() 188 .. method:: hash.copy()
183 189
184 Return a copy ("clone") of the hash object. This can be used to efficiently 190 Return a copy ("clone") of the hash object. This can be used to efficiently
185 compute the digests of data sharing a common initial substring. 191 compute the digests of data sharing a common initial substring.
186 192
187 193
188 SHAKE variable length digest 194 SHAKE variable length digests
189 ---------------------------- 195 -----------------------------
gregory.p.smith 2016/06/02 23:41:52 digests
190 196
191 SHA3's SHAKE algorithm provides variable length digest. 197 The :func:`shake_128` and :func:`shake_256` algorithms provide variable
gregory.p.smith 2016/06/02 23:41:52 Instead of "SHA3's SHAKE" here, mention the specif
198 length digests with length_in_bits//2 up to 128 or 256 bits of security.
199 As such, their digest methods require a length. Maximum length is not limited
200 by the SHAKE algorithm.
192 201
193 .. method:: shake.digest(length) 202 .. method:: shake.digest(length)
gregory.p.smith 2016/06/02 23:41:52 Are there any constraints on the length? Is length
194 203
195 Return the digest of the data passed to the :meth:`update` method so far. 204 Return the digest of the data passed to the :meth:`update` method so far.
196 This is a bytes object of size ``length`` which may contain bytes in 205 This is a bytes object of size ``length`` which may contain bytes in
197 the whole range from 0 to 255. 206 the whole range from 0 to 255.
198 207
199 208
200 .. method:: skahe.hexdigest(length) 209 .. method:: shake.hexdigest(length)
gregory.p.smith 2016/06/02 23:41:52 shake
201 210
202 Like :meth:`digest` except the digest is returned as a string object of 211 Like :meth:`digest` except the digest is returned as a string object of
203 double length, containing only hexadecimal digits. This may be used to 212 double length, containing only hexadecimal digits. This may be used to
204 exchange the value safely in email or other non-binary environments. 213 exchange the value safely in email or other non-binary environments.
205 214
206 215
207 Key derivation 216 Key derivation
208 -------------- 217 --------------
209 218
210 Key derivation and key stretching algorithms are designed for secure password 219 Key derivation and key stretching algorithms are designed for secure password
(...skipping 44 matching lines...) Expand 10 before | Expand all | Expand 10 after
255 264
256 http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf 265 http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
257 The FIPS 180-2 publication on Secure Hash Algorithms. 266 The FIPS 180-2 publication on Secure Hash Algorithms.
258 267
259 https://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_ algorithms 268 https://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_ algorithms
260 Wikipedia article with information on which algorithms have known issues a nd 269 Wikipedia article with information on which algorithms have known issues a nd
261 what that means regarding their use. 270 what that means regarding their use.
262 271
263 https://www.ietf.org/rfc/rfc2898.txt 272 https://www.ietf.org/rfc/rfc2898.txt
264 PKCS #5: Password-Based Cryptography Specification Version 2.0 273 PKCS #5: Password-Based Cryptography Specification Version 2.0
LEFTRIGHT
« no previous file | Lib/hashlib.py » ('j') | Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Toggle Comments ('s')

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+