| 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. |