Debian Codegraph @

Doc/library/hashlib.rst

raw
1 :mod:`!hashlib` --- Secure hashes and message digests
2 =====================================================
3
4 .. module:: hashlib
5 :synopsis: Secure hash and message digest algorithms.
6
7 .. moduleauthor:: Gregory P. Smith <[email protected]>
8 .. sectionauthor:: Gregory P. Smith <[email protected]>
9
10 **Source code:** :source:`Lib/hashlib.py`
11
12 .. index::
13 single: message digest, MD5
14 single: secure hash algorithm, SHA1, SHA2, SHA224, SHA256, SHA384, SHA512, SHA3, Shake, Blake2
15
16 .. testsetup::
17
18 import hashlib
19
20
21 --------------
22
23 This module implements a common interface to many different hash algorithms.
24 Included are the FIPS secure hash algorithms SHA224, SHA256, SHA384, SHA512,
25 (defined in `the FIPS 180-4 standard`_), the SHA-3 series (defined in `the FIPS
26 202 standard`_) as well as the legacy algorithms SHA1 (`formerly part of FIPS`_)
27 and the MD5 algorithm (defined in internet :rfc:`1321`).
28
29 .. note::
30
31 If you want the adler32 or crc32 hash functions, they are available in
32 the :mod:`zlib` module.
33
34
35 .. _hash-algorithms:
36
37 Hash algorithms
38 ---------------
39
40 There is one constructor method named for each type of :dfn:`hash`. All return
41 a hash object with the same simple interface. For example: use :func:`sha256`
42 to create a SHA-256 hash object. You can now feed this object with
43 :term:`bytes-like objects <bytes-like object>` (normally :class:`bytes`) using
44 the :meth:`update<hash.update>` method. At any point you can ask it for the
45 :dfn:`digest` of the concatenation of the data fed to it so far using the
46 :meth:`digest()<hash.digest>` or :meth:`hexdigest()<hash.hexdigest>` methods.
47
48 To allow multithreading, the Python :term:`GIL` is released while computing a
49 hash supplied more than 2047 bytes of data at once in its constructor or
50 :meth:`.update<hash.update>` method.
51
52
53 .. index:: single: OpenSSL; (use in module hashlib)
54
55 Constructors for hash algorithms that are always present in this module are
56 :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, :func:`sha512`,
57 :func:`sha3_224`, :func:`sha3_256`, :func:`sha3_384`, :func:`sha3_512`,
58 :func:`shake_128`, :func:`shake_256`, :func:`blake2b`, and :func:`blake2s`.
59 :func:`md5` is normally available as well, though it may be missing or blocked
60 if you are using a rare "FIPS compliant" build of Python.
61 These correspond to :data:`algorithms_guaranteed`.
62
63 Additional algorithms may also be available if your Python distribution's
64 :mod:`!hashlib` was linked against a build of OpenSSL that provides others.
65 Others *are not guaranteed available* on all installations and will only be
66 accessible by name via :func:`new`. See :data:`algorithms_available`.
67
68 .. warning::
69
70 Some algorithms have known hash collision weaknesses (including MD5 and
71 SHA1). Refer to `Attacks on cryptographic hash algorithms`_ and the
72 `hashlib-seealso`_ section at the end of this document.
73
74 .. versionadded:: 3.6
75 SHA3 (Keccak) and SHAKE constructors :func:`sha3_224`, :func:`sha3_256`,
76 :func:`sha3_384`, :func:`sha3_512`, :func:`shake_128`, :func:`shake_256`
77 were added.
78 :func:`blake2b` and :func:`blake2s` were added.
79
80 .. _hashlib-usedforsecurity:
81
82 .. versionchanged:: 3.9
83 All hashlib constructors take a keyword-only argument *usedforsecurity*
84 with default value ``True``. A false value allows the use of insecure and
85 blocked hashing algorithms in restricted environments. ``False`` indicates
86 that the hashing algorithm is not used in a security context, e.g. as a
87 non-cryptographic one-way compression function.
88
89 .. versionchanged:: 3.9
90 Hashlib now uses SHA3 and SHAKE from OpenSSL if it provides it.
91
92 .. versionchanged:: 3.12
93 For any of the MD5, SHA1, SHA2, or SHA3 algorithms that the linked
94 OpenSSL does not provide we fall back to a verified implementation from
95 the `HACL\* project`_.
96
97 Usage
98 -----
99
100 To obtain the digest of the byte string ``b"Nobody inspects the spammish
101 repetition"``::
102
103 >>> import hashlib
104 >>> m = hashlib.sha256()
105 >>> m.update(b"Nobody inspects")
106 >>> m.update(b" the spammish repetition")
107 >>> m.digest()
108 b'\x03\x1e\xdd}Ae\x15\x93\xc5\xfe\\\x00o\xa5u+7\xfd\xdf\xf7\xbcN\x84:\xa6\xaf\x0c\x95\x0fK\x94\x06'
109 >>> m.hexdigest()
110 '031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'
111
112 More condensed:
113
114 >>> hashlib.sha256(b"Nobody inspects the spammish repetition").hexdigest()
115 '031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'
116
117 Constructors
118 ------------
119
120 .. function:: new(name[, data], *, usedforsecurity=True)
121
122 Is a generic constructor that takes the string *name* of the desired
123 algorithm as its first parameter. It also exists to allow access to the
124 above listed hashes as well as any other algorithms that your OpenSSL
125 library may offer.
126
127 Using :func:`new` with an algorithm name:
128
129 >>> h = hashlib.new('sha256')
130 >>> h.update(b"Nobody inspects the spammish repetition")
131 >>> h.hexdigest()
132 '031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'
133
134
135 .. function:: md5([, data], *, usedforsecurity=True)
136 .. function:: sha1([, data], *, usedforsecurity=True)
137 .. function:: sha224([, data], *, usedforsecurity=True)
138 .. function:: sha256([, data], *, usedforsecurity=True)
139 .. function:: sha384([, data], *, usedforsecurity=True)
140 .. function:: sha512([, data], *, usedforsecurity=True)
141 .. function:: sha3_224([, data], *, usedforsecurity=True)
142 .. function:: sha3_256([, data], *, usedforsecurity=True)
143 .. function:: sha3_384([, data], *, usedforsecurity=True)
144 .. function:: sha3_512([, data], *, usedforsecurity=True)
145
146 Named constructors such as these are faster than passing an algorithm name to
147 :func:`new`.
148
149 Attributes
150 ----------
151
152 Hashlib provides the following constant module attributes:
153
154 .. data:: algorithms_guaranteed
155
156 A set containing the names of the hash algorithms guaranteed to be supported
157 by this module on all platforms. Note that 'md5' is in this list despite
158 some upstream vendors offering an odd "FIPS compliant" Python build that
159 excludes it.
160
161 .. versionadded:: 3.2
162
163 .. data:: algorithms_available
164
165 A set containing the names of the hash algorithms that are available in the
166 running Python interpreter. These names will be recognized when passed to
167 :func:`new`. :attr:`algorithms_guaranteed` will always be a subset. The
168 same algorithm may appear multiple times in this set under different names
169 (thanks to OpenSSL).
170
171 .. versionadded:: 3.2
172
173 Hash Objects
174 ------------
175
176 The following values are provided as constant attributes of the hash objects
177 returned by the constructors:
178
179 .. data:: hash.digest_size
180
181 The size of the resulting hash in bytes.
182
183 .. data:: hash.block_size
184
185 The internal block size of the hash algorithm in bytes.
186
187 A hash object has the following attributes:
188
189 .. attribute:: hash.name
190
191 The canonical name of this hash, always lowercase and always suitable as a
192 parameter to :func:`new` to create another hash of this type.
193
194 .. versionchanged:: 3.4
195 The name attribute has been present in CPython since its inception, but
196 until Python 3.4 was not formally specified, so may not exist on some
197 platforms.
198
199 A hash object has the following methods:
200
201
202 .. method:: hash.update(data)
203
204 Update the hash object with the :term:`bytes-like object`.
205 Repeated calls are equivalent to a single call with the
206 concatenation of all the arguments: ``m.update(a); m.update(b)`` is
207 equivalent to ``m.update(a+b)``.
208
209
210 .. method:: hash.digest()
211
212 Return the digest of the data passed to the :meth:`update` method so far.
213 This is a bytes object of size :attr:`digest_size` which may contain bytes in
214 the whole range from 0 to 255.
215
216
217 .. method:: hash.hexdigest()
218
219 Like :meth:`digest` except the digest is returned as a string object of
220 double length, containing only hexadecimal digits. This may be used to
221 exchange the value safely in email or other non-binary environments.
222
223
224 .. method:: hash.copy()
225
226 Return a copy ("clone") of the hash object. This can be used to efficiently
227 compute the digests of data sharing a common initial substring.
228
229
230 SHAKE variable length digests
231 -----------------------------
232
233 .. function:: shake_128([, data], *, usedforsecurity=True)
234 .. function:: shake_256([, data], *, usedforsecurity=True)
235
236 The :func:`shake_128` and :func:`shake_256` algorithms provide variable
237 length digests with length_in_bits//2 up to 128 or 256 bits of security.
238 As such, their digest methods require a length. Maximum length is not limited
239 by the SHAKE algorithm.
240
241 .. method:: shake.digest(length)
242
243 Return the digest of the data passed to the :meth:`~hash.update` method so far.
244 This is a bytes object of size *length* which may contain bytes in
245 the whole range from 0 to 255.
246
247
248 .. method:: shake.hexdigest(length)
249
250 Like :meth:`digest` except the digest is returned as a string object of
251 double length, containing only hexadecimal digits. This may be used to
252 exchange the value in email or other non-binary environments.
253
254 Example use:
255
256 >>> h = hashlib.shake_256(b'Nobody inspects the spammish repetition')
257 >>> h.hexdigest(20)
258 '44709d6fcb83d92a76dcb0b668c98e1b1d3dafe7'
259
260 File hashing
261 ------------
262
263 The hashlib module provides a helper function for efficient hashing of
264 a file or file-like object.
265
266 .. function:: file_digest(fileobj, digest, /)
267
268 Return a digest object that has been updated with contents of file object.
269
270 *fileobj* must be a file-like object opened for reading in binary mode.
271 It accepts file objects from builtin :func:`open`, :class:`~io.BytesIO`
272 instances, SocketIO objects from :meth:`socket.socket.makefile`, and
273 similar. *fileobj* must be opened in blocking mode, otherwise a
274 :exc:`BlockingIOError` may be raised.
275
276 The function may bypass Python's I/O and use the file descriptor
277 from :meth:`~io.IOBase.fileno` directly. *fileobj* must be assumed to be
278 in an unknown state after this function returns or raises. It is up to
279 the caller to close *fileobj*.
280
281 *digest* must either be a hash algorithm name as a *str*, a hash
282 constructor, or a callable that returns a hash object.
283
284 Example:
285
286 >>> import io, hashlib, hmac
287 >>> with open("library/hashlib.rst", "rb") as f:
288 ... digest = hashlib.file_digest(f, "sha256")
289 ...
290 >>> digest.hexdigest() # doctest: +ELLIPSIS
291 '...'
292
293 >>> buf = io.BytesIO(b"somedata")
294 >>> mac1 = hmac.HMAC(b"key", digestmod=hashlib.sha512)
295 >>> digest = hashlib.file_digest(buf, lambda: mac1)
296
297 >>> digest is mac1
298 True
299 >>> mac2 = hmac.HMAC(b"key", b"somedata", digestmod=hashlib.sha512)
300 >>> mac1.digest() == mac2.digest()
301 True
302
303 .. versionadded:: 3.11
304
305 .. versionchanged:: 3.14
306 Now raises a :exc:`BlockingIOError` if the file is opened in non-blocking
307 mode. Previously, spurious null bytes were added to the digest.
308
309
310 Key derivation
311 --------------
312
313 Key derivation and key stretching algorithms are designed for secure password
314 hashing. Naive algorithms such as ``sha1(password)`` are not resistant against
315 brute-force attacks. A good password hashing function must be tunable, slow, and
316 include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
317
318
319 .. function:: pbkdf2_hmac(hash_name, password, salt, iterations, dklen=None)
320
321 The function provides PKCS#5 password-based key derivation function 2. It
322 uses HMAC as pseudorandom function.
323
324 The string *hash_name* is the desired name of the hash digest algorithm for
325 HMAC, e.g. 'sha1' or 'sha256'. *password* and *salt* are interpreted as
326 buffers of bytes. Applications and libraries should limit *password* to
327 a sensible length (e.g. 1024). *salt* should be about 16 or more bytes from
328 a proper source, e.g. :func:`os.urandom`.
329
330 The number of *iterations* should be chosen based on the hash algorithm and
331 computing power. As of 2022, hundreds of thousands of iterations of SHA-256
332 are suggested. For rationale as to why and how to choose what is best for
333 your application, read *Appendix A.2.2* of NIST-SP-800-132_. The answers
334 on the `stackexchange pbkdf2 iterations question`_ explain in detail.
335
336 *dklen* is the length of the derived key in bytes. If *dklen* is ``None`` then the
337 digest size of the hash algorithm *hash_name* is used, e.g. 64 for SHA-512.
338
339 >>> from hashlib import pbkdf2_hmac
340 >>> our_app_iters = 500_000 # Application specific, read above.
341 >>> dk = pbkdf2_hmac('sha256', b'password', b'bad salt' * 2, our_app_iters)
342 >>> dk.hex()
343 '15530bba69924174860db778f2c6f8104d3aaf9d26241840c8c4a641c8d000a9'
344
345 Function only available when Python is compiled with OpenSSL.
346
347 .. versionadded:: 3.4
348
349 .. versionchanged:: 3.12
350 Function now only available when Python is built with OpenSSL. The slow
351 pure Python implementation has been removed.
352
353 .. function:: scrypt(password, *, salt, n, r, p, maxmem=0, dklen=64)
354
355 The function provides scrypt password-based key derivation function as
356 defined in :rfc:`7914`.
357
358 *password* and *salt* must be :term:`bytes-like objects
359 <bytes-like object>`. Applications and libraries should limit *password*
360 to a sensible length (e.g. 1024). *salt* should be about 16 or more
361 bytes from a proper source, e.g. :func:`os.urandom`.
362
363 *n* is the CPU/Memory cost factor, *r* the block size, *p* parallelization
364 factor and *maxmem* limits memory (OpenSSL 1.1.0 defaults to 32 MiB).
365 *dklen* is the length of the derived key in bytes.
366
367 .. versionadded:: 3.6
368
369
370 .. _hashlib-blake2:
371
372 BLAKE2
373 ------
374
375 .. sectionauthor:: Dmitry Chestnykh
376
377 .. index::
378 single: blake2b, blake2s
379
380 BLAKE2_ is a cryptographic hash function defined in :rfc:`7693` that comes in two
381 flavors:
382
383 * **BLAKE2b**, optimized for 64-bit platforms and produces digests of any size
384 between 1 and 64 bytes,
385
386 * **BLAKE2s**, optimized for 8- to 32-bit platforms and produces digests of any
387 size between 1 and 32 bytes.
388
389 BLAKE2 supports **keyed mode** (a faster and simpler replacement for HMAC_),
390 **salted hashing**, **personalization**, and **tree hashing**.
391
392 Hash objects from this module follow the API of standard library's
393 :mod:`!hashlib` objects.
394
395
396 Creating hash objects
397 ^^^^^^^^^^^^^^^^^^^^^
398
399 New hash objects are created by calling constructor functions:
400
401
402 .. function:: blake2b(data=b'', *, digest_size=64, key=b'', salt=b'', \
403 person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, \
404 node_depth=0, inner_size=0, last_node=False, \
405 usedforsecurity=True)
406
407 .. function:: blake2s(data=b'', *, digest_size=32, key=b'', salt=b'', \
408 person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, \
409 node_depth=0, inner_size=0, last_node=False, \
410 usedforsecurity=True)
411
412
413 These functions return the corresponding hash objects for calculating
414 BLAKE2b or BLAKE2s. They optionally take these general parameters:
415
416 * *data*: initial chunk of data to hash, which must be
417 :term:`bytes-like object`. It can be passed only as positional argument.
418
419 * *digest_size*: size of output digest in bytes.
420
421 * *key*: key for keyed hashing (up to 64 bytes for BLAKE2b, up to 32 bytes for
422 BLAKE2s).
423
424 * *salt*: salt for randomized hashing (up to 16 bytes for BLAKE2b, up to 8
425 bytes for BLAKE2s).
426
427 * *person*: personalization string (up to 16 bytes for BLAKE2b, up to 8 bytes
428 for BLAKE2s).
429
430 The following table shows limits for general parameters (in bytes):
431
432 ======= =========== ======== ========= ===========
433 Hash digest_size len(key) len(salt) len(person)
434 ======= =========== ======== ========= ===========
435 BLAKE2b 64 64 16 16
436 BLAKE2s 32 32 8 8
437 ======= =========== ======== ========= ===========
438
439 .. note::
440
441 BLAKE2 specification defines constant lengths for salt and personalization
442 parameters, however, for convenience, this implementation accepts byte
443 strings of any size up to the specified length. If the length of the
444 parameter is less than specified, it is padded with zeros, thus, for
445 example, ``b'salt'`` and ``b'salt\x00'`` is the same value. (This is not
446 the case for *key*.)
447
448 These sizes are available as module `constants`_ described below.
449
450 Constructor functions also accept the following tree hashing parameters:
451
452 * *fanout*: fanout (0 to 255, 0 if unlimited, 1 in sequential mode).
453
454 * *depth*: maximal depth of tree (1 to 255, 255 if unlimited, 1 in
455 sequential mode).
456
457 * *leaf_size*: maximal byte length of leaf (0 to ``2**32-1``, 0 if unlimited or in
458 sequential mode).
459
460 * *node_offset*: node offset (0 to ``2**64-1`` for BLAKE2b, 0 to ``2**48-1`` for
461 BLAKE2s, 0 for the first, leftmost, leaf, or in sequential mode).
462
463 * *node_depth*: node depth (0 to 255, 0 for leaves, or in sequential mode).
464
465 * *inner_size*: inner digest size (0 to 64 for BLAKE2b, 0 to 32 for
466 BLAKE2s, 0 in sequential mode).
467
468 * *last_node*: boolean indicating whether the processed node is the last
469 one (``False`` for sequential mode).
470
471 .. figure:: hashlib-blake2-tree.png
472 :alt: Explanation of tree mode parameters.
473 :class: invert-in-dark-mode
474
475 See section 2.10 in `BLAKE2 specification
476 <https://www.blake2.net/blake2_20130129.pdf>`_ for comprehensive review of tree
477 hashing.
478
479
480 Constants
481 ^^^^^^^^^
482
483 .. data:: blake2b.SALT_SIZE
484 .. data:: blake2s.SALT_SIZE
485
486 Salt length (maximum length accepted by constructors).
487
488
489 .. data:: blake2b.PERSON_SIZE
490 .. data:: blake2s.PERSON_SIZE
491
492 Personalization string length (maximum length accepted by constructors).
493
494
495 .. data:: blake2b.MAX_KEY_SIZE
496 .. data:: blake2s.MAX_KEY_SIZE
497
498 Maximum key size.
499
500
501 .. data:: blake2b.MAX_DIGEST_SIZE
502 .. data:: blake2s.MAX_DIGEST_SIZE
503
504 Maximum digest size that the hash function can output.
505
506
507 Examples
508 ^^^^^^^^
509
510 Simple hashing
511 """"""""""""""
512
513 To calculate hash of some data, you should first construct a hash object by
514 calling the appropriate constructor function (:func:`blake2b` or
515 :func:`blake2s`), then update it with the data by calling :meth:`~hash.update` on the
516 object, and, finally, get the digest out of the object by calling
517 :meth:`~hash.digest` (or :meth:`~hash.hexdigest` for hex-encoded string).
518
519 >>> from hashlib import blake2b
520 >>> h = blake2b()
521 >>> h.update(b'Hello world')
522 >>> h.hexdigest()
523 '6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
524
525
526 As a shortcut, you can pass the first chunk of data to update directly to the
527 constructor as the positional argument:
528
529 >>> from hashlib import blake2b
530 >>> blake2b(b'Hello world').hexdigest()
531 '6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
532
533 You can call :meth:`hash.update` as many times as you need to iteratively
534 update the hash:
535
536 >>> from hashlib import blake2b
537 >>> items = [b'Hello', b' ', b'world']
538 >>> h = blake2b()
539 >>> for item in items:
540 ... h.update(item)
541 ...
542 >>> h.hexdigest()
543 '6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
544
545
546 Using different digest sizes
547 """"""""""""""""""""""""""""
548
549 BLAKE2 has configurable size of digests up to 64 bytes for BLAKE2b and up to 32
550 bytes for BLAKE2s. For example, to replace SHA-1 with BLAKE2b without changing
551 the size of output, we can tell BLAKE2b to produce 20-byte digests:
552
553 >>> from hashlib import blake2b
554 >>> h = blake2b(digest_size=20)
555 >>> h.update(b'Replacing SHA1 with the more secure function')
556 >>> h.hexdigest()
557 'd24f26cf8de66472d58d4e1b1774b4c9158b1f4c'
558 >>> h.digest_size
559 20
560 >>> len(h.digest())
561 20
562
563 Hash objects with different digest sizes have completely different outputs
564 (shorter hashes are *not* prefixes of longer hashes); BLAKE2b and BLAKE2s
565 produce different outputs even if the output length is the same:
566
567 >>> from hashlib import blake2b, blake2s
568 >>> blake2b(digest_size=10).hexdigest()
569 '6fa1d8fcfd719046d762'
570 >>> blake2b(digest_size=11).hexdigest()
571 'eb6ec15daf9546254f0809'
572 >>> blake2s(digest_size=10).hexdigest()
573 '1bf21a98c78a1c376ae9'
574 >>> blake2s(digest_size=11).hexdigest()
575 '567004bf96e4a25773ebf4'
576
577
578 Keyed hashing
579 """""""""""""
580
581 Keyed hashing can be used for authentication as a faster and simpler
582 replacement for `Hash-based message authentication code
583 <https://en.wikipedia.org/wiki/HMAC>`_ (HMAC).
584 BLAKE2 can be securely used in prefix-MAC mode thanks to the
585 indifferentiability property inherited from BLAKE.
586
587 This example shows how to get a (hex-encoded) 128-bit authentication code for
588 message ``b'message data'`` with key ``b'pseudorandom key'``::
589
590 >>> from hashlib import blake2b
591 >>> h = blake2b(key=b'pseudorandom key', digest_size=16)
592 >>> h.update(b'message data')
593 >>> h.hexdigest()
594 '3d363ff7401e02026f4a4687d4863ced'
595
596
597 As a practical example, a web application can symmetrically sign cookies sent
598 to users and later verify them to make sure they weren't tampered with::
599
600 >>> from hashlib import blake2b
601 >>> from hmac import compare_digest
602 >>>
603 >>> SECRET_KEY = b'pseudorandomly generated server secret key'
604 >>> AUTH_SIZE = 16
605 >>>
606 >>> def sign(cookie):
607 ... h = blake2b(digest_size=AUTH_SIZE, key=SECRET_KEY)
608 ... h.update(cookie)
609 ... return h.hexdigest().encode('utf-8')
610 >>>
611 >>> def verify(cookie, sig):
612 ... good_sig = sign(cookie)
613 ... return compare_digest(good_sig, sig)
614 >>>
615 >>> cookie = b'user-alice'
616 >>> sig = sign(cookie)
617 >>> print("{0},{1}".format(cookie.decode('utf-8'), sig))
618 user-alice,b'43b3c982cf697e0c5ab22172d1ca7421'
619 >>> verify(cookie, sig)
620 True
621 >>> verify(b'user-bob', sig)
622 False
623 >>> verify(cookie, b'0102030405060708090a0b0c0d0e0f00')
624 False
625
626 Even though there's a native keyed hashing mode, BLAKE2 can, of course, be used
627 in HMAC construction with :mod:`hmac` module::
628
629 >>> import hmac, hashlib
630 >>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)
631 >>> m.update(b'message')
632 >>> m.hexdigest()
633 'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'
634
635
636 Randomized hashing
637 """"""""""""""""""
638
639 By setting *salt* parameter users can introduce randomization to the hash
640 function. Randomized hashing is useful for protecting against collision attacks
641 on the hash function used in digital signatures.
642
643 Randomized hashing is designed for situations where one party, the message
644 preparer, generates all or part of a message to be signed by a second
645 party, the message signer. If the message preparer is able to find
646 cryptographic hash function collisions (i.e., two messages producing the
647 same hash value), then they might prepare meaningful versions of the message
648 that would produce the same hash value and digital signature, but with
649 different results (e.g., transferring $1,000,000 to an account, rather than
650 $10). Cryptographic hash functions have been designed with collision
651 resistance as a major goal, but the current concentration on attacking
652 cryptographic hash functions may result in a given cryptographic hash
653 function providing less collision resistance than expected. Randomized
654 hashing offers the signer additional protection by reducing the likelihood
655 that a preparer can generate two or more messages that ultimately yield the
656 same hash value during the digital signature generation process --- even if
657 it is practical to find collisions for the hash function. However, the use
658 of randomized hashing may reduce the amount of security provided by a
659 digital signature when all portions of the message are prepared
660 by the signer.
661
662 (`NIST SP-800-106 "Randomized Hashing for Digital Signatures"
663 <https://csrc.nist.gov/pubs/sp/800/106/final>`_)
664
665 In BLAKE2 the salt is processed as a one-time input to the hash function during
666 initialization, rather than as an input to each compression function.
667
668 .. warning::
669
670 *Salted hashing* (or just hashing) with BLAKE2 or any other general-purpose
671 cryptographic hash function, such as SHA-256, is not suitable for hashing
672 passwords. See `BLAKE2 FAQ <https://www.blake2.net/#qa>`_ for more
673 information.
674 ..
675
676 >>> import os
677 >>> from hashlib import blake2b
678 >>> msg = b'some message'
679 >>> # Calculate the first hash with a random salt.
680 >>> salt1 = os.urandom(blake2b.SALT_SIZE)
681 >>> h1 = blake2b(salt=salt1)
682 >>> h1.update(msg)
683 >>> # Calculate the second hash with a different random salt.
684 >>> salt2 = os.urandom(blake2b.SALT_SIZE)
685 >>> h2 = blake2b(salt=salt2)
686 >>> h2.update(msg)
687 >>> # The digests are different.
688 >>> h1.digest() != h2.digest()
689 True
690
691
692 Personalization
693 """""""""""""""
694
695 Sometimes it is useful to force hash function to produce different digests for
696 the same input for different purposes. Quoting the authors of the Skein hash
697 function:
698
699 We recommend that all application designers seriously consider doing this;
700 we have seen many protocols where a hash that is computed in one part of
701 the protocol can be used in an entirely different part because two hash
702 computations were done on similar or related data, and the attacker can
703 force the application to make the hash inputs the same. Personalizing each
704 hash function used in the protocol summarily stops this type of attack.
705
706 (`The Skein Hash Function Family
707 <https://www.schneier.com/wp-content/uploads/2016/02/skein.pdf>`_,
708 p. 21)
709
710 BLAKE2 can be personalized by passing bytes to the *person* argument::
711
712 >>> from hashlib import blake2b
713 >>> FILES_HASH_PERSON = b'MyApp Files Hash'
714 >>> BLOCK_HASH_PERSON = b'MyApp Block Hash'
715 >>> h = blake2b(digest_size=32, person=FILES_HASH_PERSON)
716 >>> h.update(b'the same content')
717 >>> h.hexdigest()
718 '20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'
719 >>> h = blake2b(digest_size=32, person=BLOCK_HASH_PERSON)
720 >>> h.update(b'the same content')
721 >>> h.hexdigest()
722 'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'
723
724 Personalization together with the keyed mode can also be used to derive different
725 keys from a single one.
726
727 >>> from hashlib import blake2s
728 >>> from base64 import b64decode, b64encode
729 >>> orig_key = b64decode(b'Rm5EPJai72qcK3RGBpW3vPNfZy5OZothY+kHY6h21KM=')
730 >>> enc_key = blake2s(key=orig_key, person=b'kEncrypt').digest()
731 >>> mac_key = blake2s(key=orig_key, person=b'kMAC').digest()
732 >>> print(b64encode(enc_key).decode('utf-8'))
733 rbPb15S/Z9t+agffno5wuhB77VbRi6F9Iv2qIxU7WHw=
734 >>> print(b64encode(mac_key).decode('utf-8'))
735 G9GtHFE1YluXY1zWPlYk1e/nWfu0WSEb0KRcjhDeP/o=
736
737 Tree mode
738 """""""""
739
740 Here's an example of hashing a minimal tree with two leaf nodes::
741
742 10
743 / \
744 00 01
745
746 This example uses 64-byte internal digests, and returns the 32-byte final
747 digest::
748
749 >>> from hashlib import blake2b
750 >>>
751 >>> FANOUT = 2
752 >>> DEPTH = 2
753 >>> LEAF_SIZE = 4096
754 >>> INNER_SIZE = 64
755 >>>
756 >>> buf = bytearray(6000)
757 >>>
758 >>> # Left leaf
759 ... h00 = blake2b(buf[0:LEAF_SIZE], fanout=FANOUT, depth=DEPTH,
760 ... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
761 ... node_offset=0, node_depth=0, last_node=False)
762 >>> # Right leaf
763 ... h01 = blake2b(buf[LEAF_SIZE:], fanout=FANOUT, depth=DEPTH,
764 ... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
765 ... node_offset=1, node_depth=0, last_node=True)
766 >>> # Root node
767 ... h10 = blake2b(digest_size=32, fanout=FANOUT, depth=DEPTH,
768 ... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
769 ... node_offset=0, node_depth=1, last_node=True)
770 >>> h10.update(h00.digest())
771 >>> h10.update(h01.digest())
772 >>> h10.hexdigest()
773 '3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa'
774
775 Credits
776 ^^^^^^^
777
778 BLAKE2_ was designed by *Jean-Philippe Aumasson*, *Samuel Neves*, *Zooko
779 Wilcox-O'Hearn*, and *Christian Winnerlein* based on SHA-3_ finalist BLAKE_
780 created by *Jean-Philippe Aumasson*, *Luca Henzen*, *Willi Meier*, and
781 *Raphael C.-W. Phan*.
782
783 It uses core algorithm from ChaCha_ cipher designed by *Daniel J. Bernstein*.
784
785 The stdlib implementation is based on pyblake2_ module. It was written by
786 *Dmitry Chestnykh* based on C implementation written by *Samuel Neves*. The
787 documentation was copied from pyblake2_ and written by *Dmitry Chestnykh*.
788
789 The C code was partly rewritten for Python by *Christian Heimes*.
790
791 The following public domain dedication applies for both C hash function
792 implementation, extension code, and this documentation:
793
794 To the extent possible under law, the author(s) have dedicated all copyright
795 and related and neighboring rights to this software to the public domain
796 worldwide. This software is distributed without any warranty.
797
798 You should have received a copy of the CC0 Public Domain Dedication along
799 with this software. If not, see
800 https://creativecommons.org/publicdomain/zero/1.0/.
801
802 The following people have helped with development or contributed their changes
803 to the project and the public domain according to the Creative Commons Public
804 Domain Dedication 1.0 Universal:
805
806 * *Alexandr Sokolovskiy*
807
808 .. _BLAKE2: https://www.blake2.net
809 .. _HMAC: https://en.wikipedia.org/wiki/Hash-based_message_authentication_code
810 .. _BLAKE: https://web.archive.org/web/20200918190133/https://131002.net/blake/
811 .. _SHA-3: https://en.wikipedia.org/wiki/Secure_Hash_Algorithms
812 .. _ChaCha: https://cr.yp.to/chacha.html
813 .. _pyblake2: https://pythonhosted.org/pyblake2/
814 .. _NIST-SP-800-132: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf
815 .. _stackexchange pbkdf2 iterations question: https://security.stackexchange.com/questions/3959/recommended-of-iterations-when-using-pbkdf2-sha256/
816 .. _Attacks on cryptographic hash algorithms: https://en.wikipedia.org/wiki/Cryptographic_hash_function#Attacks_on_cryptographic_hash_algorithms
817 .. _the FIPS 180-4 standard: https://csrc.nist.gov/pubs/fips/180-4/upd1/final
818 .. _the FIPS 202 standard: https://csrc.nist.gov/pubs/fips/202/final
819 .. _HACL\* project: https://github.com/hacl-star/hacl-star
820 .. _formerly part of FIPS: https://csrc.nist.gov/news/2023/decision-to-revise-fips-180-4
821
822
823 .. _hashlib-seealso:
824
825 .. seealso::
826
827 Module :mod:`hmac`
828 A module to generate message authentication codes using hashes.
829
830 Module :mod:`base64`
831 Another way to encode binary hashes for non-binary environments.
832
833 https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.180-4.pdf
834 The FIPS 180-4 publication on Secure Hash Algorithms.
835
836 https://csrc.nist.gov/pubs/fips/202/final
837 The FIPS 202 publication on the SHA-3 Standard.
838
839 https://www.blake2.net/
840 Official BLAKE2 website.
841
842 https://en.wikipedia.org/wiki/Cryptographic_hash_function
843 Wikipedia article with information on which algorithms have known issues
844 and what that means regarding their use.
845
846 https://www.ietf.org/rfc/rfc8018.txt
847 PKCS #5: Password-Based Cryptography Specification Version 2.1
848
849 https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf
850 NIST Recommendation for Password-Based Key Derivation.