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

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

Issue 16113: Add SHA-3 (Keccak) support
Patch Set: Created 3 years, 3 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') | Lib/test/test_hashlib.py » ('J')
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 .. moduleauthor:: Gregory P. Smith <greg@krypto.org> 6 .. moduleauthor:: Gregory P. Smith <greg@krypto.org>
7 .. sectionauthor:: Gregory P. Smith <greg@krypto.org> 7 .. sectionauthor:: Gregory P. Smith <greg@krypto.org>
8 8
9 9
10 .. index:: 10 .. index::
gregory.p.smith 2016/06/02 23:41:52 add new algorithms to the index?
11 single: message digest, MD5 11 single: message digest, MD5
12 single: secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512 12 single: secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512
13 13
14 **Source code:** :source:`Lib/hashlib.py` 14 **Source code:** :source:`Lib/hashlib.py`
15 15
16 -------------- 16 --------------
17 17
18 This module implements a common interface to many different secure hash and 18 This module implements a common interface to many different secure hash and
19 message digest algorithms. Included are the FIPS secure hash algorithms SHA1, 19 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 20 SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5
(...skipping 34 matching lines...) Expand 10 before | Expand all | Expand 10 after
55 55
56 Feeding string objects into :meth:`update` is not supported, as hashes work 56 Feeding string objects into :meth:`update` is not supported, as hashes work
57 on bytes, not on characters. 57 on bytes, not on characters.
58 58
59 .. index:: single: OpenSSL; (use in module hashlib) 59 .. index:: single: OpenSSL; (use in module hashlib)
60 60
61 Constructors for hash algorithms that are always present in this module are 61 Constructors for hash algorithms that are always present in this module are
62 :func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, 62 :func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`,
63 and :func:`sha512`. Additional algorithms may also be available depending upon 63 and :func:`sha512`. Additional algorithms may also be available depending upon
64 the OpenSSL library that Python uses on your platform. 64 the OpenSSL library that Python uses on your platform.
65
66 Python provides additional hash algorithms on all common and modern platforms.
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
68 compile the implementations. The algorithms are available on all recent Unix
69 and Windows systems with X86, X86_64 and ARMv6+ CPUs.
70
71 .. versionadded:: 3.6
72 SHA3 (Keccak) and SHAKE constructors :func:`sha3_224`, :func:`sha3_256`,
73 :func:`sha3_384`, :func:`sha3_512`, :func:`shake_128`, :func:`shake_256`.
65 74
66 For example, to obtain the digest of the byte string ``b'Nobody inspects the 75 For example, to obtain the digest of the byte string ``b'Nobody inspects the
67 spammish repetition'``:: 76 spammish repetition'``::
68 77
69 >>> import hashlib 78 >>> import hashlib
70 >>> m = hashlib.md5() 79 >>> m = hashlib.md5()
71 >>> m.update(b"Nobody inspects") 80 >>> m.update(b"Nobody inspects")
72 >>> m.update(b" the spammish repetition") 81 >>> m.update(b" the spammish repetition")
73 >>> m.digest() 82 >>> m.digest()
74 b'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9' 83 b'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
(...skipping 92 matching lines...) Expand 10 before | Expand all | Expand 10 after
167 176
168 Like :meth:`digest` except the digest is returned as a string object of 177 Like :meth:`digest` except the digest is returned as a string object of
169 double length, containing only hexadecimal digits. This may be used to 178 double length, containing only hexadecimal digits. This may be used to
170 exchange the value safely in email or other non-binary environments. 179 exchange the value safely in email or other non-binary environments.
171 180
172 181
173 .. method:: hash.copy() 182 .. method:: hash.copy()
174 183
175 Return a copy ("clone") of the hash object. This can be used to efficiently 184 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. 185 compute the digests of data sharing a common initial substring.
186
187
188 SHAKE variable length digest
189 ----------------------------
gregory.p.smith 2016/06/02 23:41:52 digests
190
191 SHA3's SHAKE algorithm provides variable length digest.
gregory.p.smith 2016/06/02 23:41:52 Instead of "SHA3's SHAKE" here, mention the specif
192
193 .. method:: shake.digest(length)
gregory.p.smith 2016/06/02 23:41:52 Are there any constraints on the length? Is length
194
195 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
197 the whole range from 0 to 255.
198
199
200 .. method:: skahe.hexdigest(length)
gregory.p.smith 2016/06/02 23:41:52 shake
201
202 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
204 exchange the value safely in email or other non-binary environments.
177 205
178 206
179 Key derivation 207 Key derivation
180 -------------- 208 --------------
181 209
182 Key derivation and key stretching algorithms are designed for secure password 210 Key derivation and key stretching algorithms are designed for secure password
183 hashing. Naive algorithms such as ``sha1(password)`` are not resistant against 211 hashing. Naive algorithms such as ``sha1(password)`` are not resistant against
184 brute-force attacks. A good password hashing function must be tunable, slow, and 212 brute-force attacks. A good password hashing function must be tunable, slow, and
185 include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_. 213 include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
186 214
(...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after
227 255
228 http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf 256 http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
229 The FIPS 180-2 publication on Secure Hash Algorithms. 257 The FIPS 180-2 publication on Secure Hash Algorithms.
230 258
231 https://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_ algorithms 259 https://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_ algorithms
232 Wikipedia article with information on which algorithms have known issues a nd 260 Wikipedia article with information on which algorithms have known issues a nd
233 what that means regarding their use. 261 what that means regarding their use.
234 262
235 https://www.ietf.org/rfc/rfc2898.txt 263 https://www.ietf.org/rfc/rfc2898.txt
236 PKCS #5: Password-Based Cryptography Specification Version 2.0 264 PKCS #5: Password-Based Cryptography Specification Version 2.0
OLDNEW
« no previous file with comments | « no previous file | Lib/hashlib.py » ('j') | Lib/test/test_hashlib.py » ('J')

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