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

Side by Side Diff: Doc/library/hashlib.rst

Issue 16113: Add SHA-3 (Keccak) support
Patch Set: Created 3 years, 2 months 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:
View unified diff | Download patch
« no previous file with comments | « no previous file | Lib/hashlib.py » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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
7 .. moduleauthor:: Gregory P. Smith <greg@krypto.org> 7 .. moduleauthor:: Gregory P. Smith <greg@krypto.org>
8 .. sectionauthor:: Gregory P. Smith <greg@krypto.org> 8 .. sectionauthor:: Gregory P. Smith <greg@krypto.org>
9 9
10 **Source code:** :source:`Lib/hashlib.py` 10 **Source code:** :source:`Lib/hashlib.py`
(...skipping 50 matching lines...) Expand 10 before | Expand all | Expand 10 after
61 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
62 on bytes, not on characters. 62 on bytes, not on characters.
63 63
64 .. index:: single: OpenSSL; (use in module hashlib) 64 .. index:: single: OpenSSL; (use in module hashlib)
65 65
66 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
67 :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, 67 :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`,
68 and :func:`sha512`. :func:`md5` is normally available as well, though it 68 and :func:`sha512`. :func:`md5` is normally available as well, though it
69 may be missing if you are using a rare "FIPS compliant" build of Python. 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 70 Additional algorithms may also be available depending upon the OpenSSL
71 library that Python uses on your platform. 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`.
72 78
73 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
74 spammish repetition'``:: 80 spammish repetition'``::
75 81
76 >>> import hashlib 82 >>> import hashlib
77 >>> m = hashlib.sha256() 83 >>> m = hashlib.sha256()
78 >>> m.update(b"Nobody inspects") 84 >>> m.update(b"Nobody inspects")
79 >>> m.update(b" the spammish repetition") 85 >>> m.update(b" the spammish repetition")
80 >>> m.digest() 86 >>> m.digest()
81 b'\x03\x1e\xdd}Ae\x15\x93\xc5\xfe\\\x00o\xa5u+7\xfd\xdf\xf7\xbcN\x84:\xa6\xaf \x0c\x95\x0fK\x94\x06' 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'
(...skipping 94 matching lines...) Expand 10 before | Expand all | Expand 10 after
176 182
177 Like :meth:`digest` except the digest is returned as a string object of 183 Like :meth:`digest` except the digest is returned as a string object of
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.
192
193
194 SHAKE variable length digests
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.
186 214
187 215
188 Key derivation 216 Key derivation
189 -------------- 217 --------------
190 218
191 Key derivation and key stretching algorithms are designed for secure password 219 Key derivation and key stretching algorithms are designed for secure password
192 hashing. Naive algorithms such as ``sha1(password)`` are not resistant against 220 hashing. Naive algorithms such as ``sha1(password)`` are not resistant against
193 brute-force attacks. A good password hashing function must be tunable, slow, and 221 brute-force attacks. A good password hashing function must be tunable, slow, and
194 include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_. 222 include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
195 223
(...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after
236 264
237 http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf 265 http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
238 The FIPS 180-2 publication on Secure Hash Algorithms. 266 The FIPS 180-2 publication on Secure Hash Algorithms.
239 267
240 https://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_ algorithms 268 https://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_ algorithms
241 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
242 what that means regarding their use. 270 what that means regarding their use.
243 271
244 https://www.ietf.org/rfc/rfc2898.txt 272 https://www.ietf.org/rfc/rfc2898.txt
245 PKCS #5: Password-Based Cryptography Specification Version 2.0 273 PKCS #5: Password-Based Cryptography Specification Version 2.0
OLDNEW
« no previous file with comments | « no previous file | Lib/hashlib.py » ('j') | no next file with comments »

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