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

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

Issue 26798: add BLAKE2 to hashlib
Left Patch Set: Created 3 years, 6 months ago
Right 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:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « Doc/library/hashlib-blake2.rst ('k') | 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 single: blake2b, blake2s 15
14 16 .. testsetup::
15 **Source code:** :source:`Lib/hashlib.py` 17
18 import hashlib
19
16 20
17 -------------- 21 --------------
18 22
19 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
20 message digest algorithms. Included are the FIPS secure hash algorithms SHA1, 24 message digest algorithms. Included are the FIPS secure hash algorithms SHA1,
21 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
22 algorithm (defined in Internet :rfc:`1321`). The terms "secure hash" and 26 algorithm (defined in Internet :rfc:`1321`). The terms "secure hash" and
23 "message digest" are interchangeable. Older algorithms were called message 27 "message digest" are interchangeable. Older algorithms were called message
24 digests. The modern term is secure hash. 28 digests. The modern term is secure hash.
25 29
26 .. note:: 30 .. note::
27 31
28 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
29 the :mod:`zlib` module. 33 the :mod:`zlib` module.
30 34
31 .. warning:: 35 .. warning::
32 36
33 Some algorithms have known hash collision weaknesses, refer to the "See 37 Some algorithms have known hash collision weaknesses, refer to the "See
34 also" section at the end. 38 also" section at the end.
35 39
36 40
37 .. _hash-algorithms: 41 .. _hash-algorithms:
38 42
39 Hash algorithms 43 Hash algorithms
40 --------------- 44 ---------------
41 45
42 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
43 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
44 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
45 object`\ s (normally :class:`bytes`) using the :meth:`update` method. 49 objects <bytes-like object>` (normally :class:`bytes`) using the :meth:`update` method.
46 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
47 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
48 :meth:`hexdigest` methods. 52 :meth:`hexdigest` methods.
49 53
50 .. note:: 54 .. note::
51 55
52 For better multithreading performance, the Python :term:`GIL` is released for 56 For better multithreading performance, the Python :term:`GIL` is released for
53 data larger than 2047 bytes at object creation or on update. 57 data larger than 2047 bytes at object creation or on update.
54 58
55 .. note:: 59 .. note::
56 60
57 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
58 on bytes, not on characters. 62 on bytes, not on characters.
59 63
60 .. index:: single: OpenSSL; (use in module hashlib) 64 .. index:: single: OpenSSL; (use in module hashlib)
61 65
62 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
63 :func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, 67 :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`,
64 and :func:`sha512`. Additional algorithms may also be available depending upon 68 :func:`sha512`, :func:`blake2b`, and :func:`blake2s`.
65 the OpenSSL library that Python uses on your platform. 69 :func:`md5` is normally available as well, though it
70 may be missing if you are using a rare "FIPS compliant" build of Python.
71 Additional algorithms may also be available depending upon the OpenSSL
72 library that Python uses on your platform.
73
74 .. versionadded:: 3.6
75 :func:`blake2b` and :func:`blake2s` were added.
66 76
67 For example, to obtain the digest of the byte string ``b'Nobody inspects the 77 For example, to obtain the digest of the byte string ``b'Nobody inspects the
68 spammish repetition'``:: 78 spammish repetition'``::
69 79
70 >>> import hashlib 80 >>> import hashlib
71 >>> m = hashlib.md5() 81 >>> m = hashlib.sha256()
72 >>> m.update(b"Nobody inspects") 82 >>> m.update(b"Nobody inspects")
73 >>> m.update(b" the spammish repetition") 83 >>> m.update(b" the spammish repetition")
74 >>> m.digest() 84 >>> m.digest()
75 b'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9' 85 b'\x03\x1e\xdd}Ae\x15\x93\xc5\xfe\\\x00o\xa5u+7\xfd\xdf\xf7\xbcN\x84:\xa6\xaf \x0c\x95\x0fK\x94\x06'
76 >>> m.digest_size 86 >>> m.digest_size
77 16 87 32
78 >>> m.block_size 88 >>> m.block_size
79 64 89 64
80 90
81 More condensed: 91 More condensed:
82 92
83 >>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest() 93 >>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest()
84 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2' 94 'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
85 95
86 .. function:: new(name[, data]) 96 .. function:: new(name[, data])
87 97
88 Is a generic constructor that takes the string name of the desired 98 Is a generic constructor that takes the string name of the desired
89 algorithm as its first parameter. It also exists to allow access to the 99 algorithm as its first parameter. It also exists to allow access to the
90 above listed hashes as well as any other algorithms that your OpenSSL 100 above listed hashes as well as any other algorithms that your OpenSSL
91 library may offer. The named constructors are much faster than :func:`new` 101 library may offer. The named constructors are much faster than :func:`new`
92 and should be preferred. 102 and should be preferred.
93 103
94 Using :func:`new` with an algorithm provided by OpenSSL: 104 Using :func:`new` with an algorithm provided by OpenSSL:
95 105
96 >>> h = hashlib.new('ripemd160') 106 >>> h = hashlib.new('ripemd160')
97 >>> h.update(b"Nobody inspects the spammish repetition") 107 >>> h.update(b"Nobody inspects the spammish repetition")
98 >>> h.hexdigest() 108 >>> h.hexdigest()
99 'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc' 109 'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'
100 110
101 Hashlib provides the following constant attributes: 111 Hashlib provides the following constant attributes:
102 112
103 .. data:: algorithms_guaranteed 113 .. data:: algorithms_guaranteed
104 114
105 A set containing the names of the hash algorithms guaranteed to be supported 115 A set containing the names of the hash algorithms guaranteed to be supported
106 by this module on all platforms. 116 by this module on all platforms. Note that 'md5' is in this list despite
117 some upstream vendors offering an odd "FIPS compliant" Python build that
118 excludes it.
107 119
108 .. versionadded:: 3.2 120 .. versionadded:: 3.2
109 121
110 .. data:: algorithms_available 122 .. data:: algorithms_available
111 123
112 A set containing the names of the hash algorithms that are available in the 124 A set containing the names of the hash algorithms that are available in the
113 running Python interpreter. These names will be recognized when passed to 125 running Python interpreter. These names will be recognized when passed to
114 :func:`new`. :attr:`algorithms_guaranteed` will always be a subset. The 126 :func:`new`. :attr:`algorithms_guaranteed` will always be a subset. The
115 same algorithm may appear multiple times in this set under different names 127 same algorithm may appear multiple times in this set under different names
116 (thanks to OpenSSL). 128 (thanks to OpenSSL).
(...skipping 118 matching lines...) Expand 10 before | Expand all | Expand 10 after
235 247
236 http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf 248 http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
237 The FIPS 180-2 publication on Secure Hash Algorithms. 249 The FIPS 180-2 publication on Secure Hash Algorithms.
238 250
239 https://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_ algorithms 251 https://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_ algorithms
240 Wikipedia article with information on which algorithms have known issues a nd 252 Wikipedia article with information on which algorithms have known issues a nd
241 what that means regarding their use. 253 what that means regarding their use.
242 254
243 https://www.ietf.org/rfc/rfc2898.txt 255 https://www.ietf.org/rfc/rfc2898.txt
244 PKCS #5: Password-Based Cryptography Specification Version 2.0 256 PKCS #5: Password-Based Cryptography Specification Version 2.0
LEFTRIGHT

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