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

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

Issue 16113: Add SHA-3 (Keccak) support
Left Patch Set: Created 5 years, 8 months ago
Right Patch Set: Created 3 years, 1 month 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::
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 object`\ s (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.
70 Additional algorithms may also be available depending upon the OpenSSL
71 library that Python uses on your platform. On most platforms the
72 :func:`sha3_224`, :func:`sha3_256`, :func:`sha3_384`, :func:`sha3_512`,
73 :func:`shake_128`, :func:`shake_256` are also available.
74
75 .. versionadded:: 3.6
76 SHA3 (Keccak) and SHAKE constructors :func:`sha3_224`, :func:`sha3_256`,
77 :func:`sha3_384`, :func:`sha3_512`, :func:`shake_128`, :func:`shake_256`.
65 78
66 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
67 spammish repetition'``:: 80 spammish repetition'``::
68 81
69 >>> import hashlib 82 >>> import hashlib
70 >>> m = hashlib.md5() 83 >>> m = hashlib.sha256()
71 >>> m.update(b"Nobody inspects") 84 >>> m.update(b"Nobody inspects")
72 >>> m.update(b" the spammish repetition") 85 >>> m.update(b" the spammish repetition")
73 >>> m.digest() 86 >>> m.digest()
74 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'
75 >>> m.digest_size 88 >>> m.digest_size
76 16 89 32
77 >>> m.block_size 90 >>> m.block_size
78 64 91 64
79 92
80 More condensed: 93 More condensed:
81 94
82 >>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest() 95 >>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest()
83 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2' 96 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
84 97
85 .. function:: new(name[, data]) 98 .. function:: new(name[, data])
86 99
87 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
88 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
89 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
90 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`
91 and should be preferred. 104 and should be preferred.
92 105
93 Using :func:`new` with an algorithm provided by OpenSSL: 106 Using :func:`new` with an algorithm provided by OpenSSL:
94 107
95 >>> h = hashlib.new('ripemd160') 108 >>> h = hashlib.new('ripemd160')
96 >>> h.update(b"Nobody inspects the spammish repetition") 109 >>> h.update(b"Nobody inspects the spammish repetition")
97 >>> h.hexdigest() 110 >>> h.hexdigest()
98 'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc' 111 'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'
99 112
100 Hashlib provides the following constant attributes: 113 Hashlib provides the following constant attributes:
101 114
102 .. data:: algorithms_guaranteed 115 .. data:: algorithms_guaranteed
103 116
104 Contains the names of the hash algorithms guaranteed to be supported 117 A set containing the names of the hash algorithms guaranteed to be supported
105 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.
106 121
107 .. versionadded:: 3.2 122 .. versionadded:: 3.2
108 123
109 .. data:: algorithms_available 124 .. data:: algorithms_available
110 125
111 Contains the names of the hash algorithms that are available 126 A set containing the names of the hash algorithms that are available in the
112 in the running Python interpreter. These names will be recognized 127 running Python interpreter. These names will be recognized when passed to
113 when passed to :func:`new`. :attr:`algorithms_guaranteed` 128 :func:`new`. :attr:`algorithms_guaranteed` will always be a subset. The
114 will always be a subset. Duplicate algorithms with different 129 same algorithm may appear multiple times in this set under different names
115 name formats may appear in this set (thanks to OpenSSL). 130 (thanks to OpenSSL).
116 131
117 .. versionadded:: 3.2 132 .. versionadded:: 3.2
118 133
119 The following values are provided as constant attributes of the hash objects 134 The following values are provided as constant attributes of the hash objects
120 returned by the constructors: 135 returned by the constructors:
121 136
122 137
123 .. data:: hash.digest_size 138 .. data:: hash.digest_size
124 139
125 The size of the resulting hash in bytes. 140 The size of the resulting hash in bytes.
(...skipping 43 matching lines...) Expand 10 before | Expand all | Expand 10 after
169 double length, containing only hexadecimal digits. This may be used to 184 double length, containing only hexadecimal digits. This may be used to
170 exchange the value safely in email or other non-binary environments. 185 exchange the value safely in email or other non-binary environments.
171 186
172 187
173 .. method:: hash.copy() 188 .. method:: hash.copy()
174 189
175 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
176 compute the digests of data sharing a common initial substring. 191 compute the digests of data sharing a common initial substring.
177 192
178 193
179 Key Derivation Function 194 SHAKE variable length digests
180 ----------------------- 195 -----------------------------
196
197 The :func:`shake_128` and :func:`shake_256` algorithms provide variable
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.
201
202 .. method:: shake.digest(length)
203
204 Return the digest of the data passed to the :meth:`update` method so far.
205 This is a bytes object of size ``length`` which may contain bytes in
206 the whole range from 0 to 255.
207
208
209 .. method:: shake.hexdigest(length)
210
211 Like :meth:`digest` except the digest is returned as a string object of
212 double length, containing only hexadecimal digits. This may be used to
213 exchange the value safely in email or other non-binary environments.
214
215
216 Key derivation
217 --------------
181 218
182 Key derivation and key stretching algorithms are designed for secure password 219 Key derivation and key stretching algorithms are designed for secure password
183 hashing. Naive algorithms such as ``sha1(password)`` are not resistant 220 hashing. Naive algorithms such as ``sha1(password)`` are not resistant against
184 against brute-force attacks. A good password hashing function must be tunable, 221 brute-force attacks. A good password hashing function must be tunable, slow, and
185 slow and include a salt. 222 include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
186 223
187 224
188 .. function:: pbkdf2_hmac(name, password, salt, rounds, dklen=None) 225 .. function:: pbkdf2_hmac(hash_name, password, salt, iterations, dklen=None)
189 226
190 The function provides PKCS#5 password-based key derivation function 2. It 227 The function provides PKCS#5 password-based key derivation function 2. It
191 uses HMAC as pseudorandom function. 228 uses HMAC as pseudorandom function.
192 229
193 The string *name* is the desired name of the hash digest algorithm for 230 The string *hash_name* is the desired name of the hash digest algorithm for
194 HMAC, e.g. 'sha1' or 'sha256'. *password* and *salt* are interpreted as 231 HMAC, e.g. 'sha1' or 'sha256'. *password* and *salt* are interpreted as
195 buffers of bytes. Applications and libraries should limit *password* to 232 buffers of bytes. Applications and libraries should limit *password* to
196 a sensible value (e.g. 1024). *salt* should be about 16 or more bytes from 233 a sensible length (e.g. 1024). *salt* should be about 16 or more bytes from
197 a proper source, e.g. :func:`os.urandom`. 234 a proper source, e.g. :func:`os.urandom`.
198 235
199 The number of *rounds* should be chosen based on the hash algorithm and 236 The number of *iterations* should be chosen based on the hash algorithm and
200 computing power. As of 2013 a value of at least 100,000 rounds of SHA-256 237 computing power. As of 2013, at least 100,000 iterations of SHA-256 are
201 have been suggested. 238 suggested.
202 239
203 *dklen* is the length of the derived key. If *dklen* is ``None`` then the 240 *dklen* is the length of the derived key. If *dklen* is ``None`` then the
204 digest size of the hash algorithm *name* is used, e.g. 64 for SHA-512. 241 digest size of the hash algorithm *hash_name* is used, e.g. 64 for SHA-512.
205 242
206 >>> import hashlib, binascii 243 >>> import hashlib, binascii
207 >>> dk = hashlib.pbkdf2_hmac('sha256', b'password', b'salt', 100000) 244 >>> dk = hashlib.pbkdf2_hmac('sha256', b'password', b'salt', 100000)
208 >>> binascii.hexlify(dk) 245 >>> binascii.hexlify(dk)
209 b'0394a2ede332c9a13eb82e9b24631604c31df978b4e2f0fbd2c549944f9d79a5' 246 b'0394a2ede332c9a13eb82e9b24631604c31df978b4e2f0fbd2c549944f9d79a5'
210 247
211 .. versionadded:: 3.4 248 .. versionadded:: 3.4
212 249
213 .. note:: A fast implementation of *pbkdf2_hmac* is available with OpenSSL. 250 .. note::
214 The Python implementation uses an inline version of :mod:`hmac`. It is 251
215 about three times slower and doesn't release the GIL. 252 A fast implementation of *pbkdf2_hmac* is available with OpenSSL. The
253 Python implementation uses an inline version of :mod:`hmac`. It is about
254 three times slower and doesn't release the GIL.
216 255
217 256
218 .. seealso:: 257 .. seealso::
219 258
220 Module :mod:`hmac` 259 Module :mod:`hmac`
221 A module to generate message authentication codes using hashes. 260 A module to generate message authentication codes using hashes.
222 261
223 Module :mod:`base64` 262 Module :mod:`base64`
224 Another way to encode binary hashes for non-binary environments. 263 Another way to encode binary hashes for non-binary environments.
225 264
226 http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf 265 http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
227 The FIPS 180-2 publication on Secure Hash Algorithms. 266 The FIPS 180-2 publication on Secure Hash Algorithms.
228 267
229 http://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_a lgorithms 268 https://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_ algorithms
230 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
231 what that means regarding their use. 270 what that means regarding their use.
232 271
233 http://www.ietf.org/rfc/rfc2898.txt 272 https://www.ietf.org/rfc/rfc2898.txt
234 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+