Issue #29062: Merge hashlib-blake2.rst into hashlib.rst
This commit is contained in:
INADA Naoki
parent
4c4ff5f4d4
commit
e2f9e77df2
|
|
@ -15,6 +15,5 @@ Here's an overview:
|
|||
.. toctree::
|
||||
|
||||
hashlib.rst
|
||||
hashlib-blake2.rst
|
||||
hmac.rst
|
||||
secrets.rst
|
||||
|
|
|
|||
|
|
@ -1,444 +0,0 @@
|
|||
.. _hashlib-blake2:
|
||||
|
||||
:mod:`hashlib` --- BLAKE2 hash functions
|
||||
========================================
|
||||
|
||||
.. module:: hashlib
|
||||
:synopsis: BLAKE2 hash function for Python
|
||||
.. sectionauthor:: Dmitry Chestnykh
|
||||
|
||||
.. index::
|
||||
single: blake2b, blake2s
|
||||
|
||||
BLAKE2_ is a cryptographic hash function defined in RFC-7693_ that comes in two
|
||||
flavors:
|
||||
|
||||
* **BLAKE2b**, optimized for 64-bit platforms and produces digests of any size
|
||||
between 1 and 64 bytes,
|
||||
|
||||
* **BLAKE2s**, optimized for 8- to 32-bit platforms and produces digests of any
|
||||
size between 1 and 32 bytes.
|
||||
|
||||
BLAKE2 supports **keyed mode** (a faster and simpler replacement for HMAC_),
|
||||
**salted hashing**, **personalization**, and **tree hashing**.
|
||||
|
||||
Hash objects from this module follow the API of standard library's
|
||||
:mod:`hashlib` objects.
|
||||
|
||||
|
||||
Module
|
||||
======
|
||||
|
||||
Creating hash objects
|
||||
---------------------
|
||||
|
||||
New hash objects are created by calling constructor functions:
|
||||
|
||||
|
||||
.. function:: blake2b(data=b'', digest_size=64, key=b'', salt=b'', \
|
||||
person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, \
|
||||
node_depth=0, inner_size=0, last_node=False)
|
||||
|
||||
.. function:: blake2s(data=b'', digest_size=32, key=b'', salt=b'', \
|
||||
person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, \
|
||||
node_depth=0, inner_size=0, last_node=False)
|
||||
|
||||
|
||||
These functions return the corresponding hash objects for calculating
|
||||
BLAKE2b or BLAKE2s. They optionally take these general parameters:
|
||||
|
||||
* *data*: initial chunk of data to hash, which must be interpretable as buffer
|
||||
of bytes.
|
||||
|
||||
* *digest_size*: size of output digest in bytes.
|
||||
|
||||
* *key*: key for keyed hashing (up to 64 bytes for BLAKE2b, up to 32 bytes for
|
||||
BLAKE2s).
|
||||
|
||||
* *salt*: salt for randomized hashing (up to 16 bytes for BLAKE2b, up to 8
|
||||
bytes for BLAKE2s).
|
||||
|
||||
* *person*: personalization string (up to 16 bytes for BLAKE2b, up to 8 bytes
|
||||
for BLAKE2s).
|
||||
|
||||
The following table shows limits for general parameters (in bytes):
|
||||
|
||||
======= =========== ======== ========= ===========
|
||||
Hash digest_size len(key) len(salt) len(person)
|
||||
======= =========== ======== ========= ===========
|
||||
BLAKE2b 64 64 16 16
|
||||
BLAKE2s 32 32 8 8
|
||||
======= =========== ======== ========= ===========
|
||||
|
||||
.. note::
|
||||
|
||||
BLAKE2 specification defines constant lengths for salt and personalization
|
||||
parameters, however, for convenience, this implementation accepts byte
|
||||
strings of any size up to the specified length. If the length of the
|
||||
parameter is less than specified, it is padded with zeros, thus, for
|
||||
example, ``b'salt'`` and ``b'salt\x00'`` is the same value. (This is not
|
||||
the case for *key*.)
|
||||
|
||||
These sizes are available as module `constants`_ described below.
|
||||
|
||||
Constructor functions also accept the following tree hashing parameters:
|
||||
|
||||
* *fanout*: fanout (0 to 255, 0 if unlimited, 1 in sequential mode).
|
||||
|
||||
* *depth*: maximal depth of tree (1 to 255, 255 if unlimited, 1 in
|
||||
sequential mode).
|
||||
|
||||
* *leaf_size*: maximal byte length of leaf (0 to 2**32-1, 0 if unlimited or in
|
||||
sequential mode).
|
||||
|
||||
* *node_offset*: node offset (0 to 2**64-1 for BLAKE2b, 0 to 2**48-1 for
|
||||
BLAKE2s, 0 for the first, leftmost, leaf, or in sequential mode).
|
||||
|
||||
* *node_depth*: node depth (0 to 255, 0 for leaves, or in sequential mode).
|
||||
|
||||
* *inner_size*: inner digest size (0 to 64 for BLAKE2b, 0 to 32 for
|
||||
BLAKE2s, 0 in sequential mode).
|
||||
|
||||
* *last_node*: boolean indicating whether the processed node is the last
|
||||
one (`False` for sequential mode).
|
||||
|
||||
.. figure:: hashlib-blake2-tree.png
|
||||
:alt: Explanation of tree mode parameters.
|
||||
|
||||
See section 2.10 in `BLAKE2 specification
|
||||
<https://blake2.net/blake2_20130129.pdf>`_ for comprehensive review of tree
|
||||
hashing.
|
||||
|
||||
|
||||
Constants
|
||||
---------
|
||||
|
||||
.. data:: blake2b.SALT_SIZE
|
||||
.. data:: blake2s.SALT_SIZE
|
||||
|
||||
Salt length (maximum length accepted by constructors).
|
||||
|
||||
|
||||
.. data:: blake2b.PERSON_SIZE
|
||||
.. data:: blake2s.PERSON_SIZE
|
||||
|
||||
Personalization string length (maximum length accepted by constructors).
|
||||
|
||||
|
||||
.. data:: blake2b.MAX_KEY_SIZE
|
||||
.. data:: blake2s.MAX_KEY_SIZE
|
||||
|
||||
Maximum key size.
|
||||
|
||||
|
||||
.. data:: blake2b.MAX_DIGEST_SIZE
|
||||
.. data:: blake2s.MAX_DIGEST_SIZE
|
||||
|
||||
Maximum digest size that the hash function can output.
|
||||
|
||||
|
||||
Examples
|
||||
========
|
||||
|
||||
Simple hashing
|
||||
--------------
|
||||
|
||||
To calculate hash of some data, you should first construct a hash object by
|
||||
calling the appropriate constructor function (:func:`blake2b` or
|
||||
:func:`blake2s`), then update it with the data by calling :meth:`update` on the
|
||||
object, and, finally, get the digest out of the object by calling
|
||||
:meth:`digest` (or :meth:`hexdigest` for hex-encoded string).
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>> h = blake2b()
|
||||
>>> h.update(b'Hello world')
|
||||
>>> h.hexdigest()
|
||||
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
|
||||
|
||||
|
||||
As a shortcut, you can pass the first chunk of data to update directly to the
|
||||
constructor as the first argument (or as *data* keyword argument):
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>> blake2b(b'Hello world').hexdigest()
|
||||
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
|
||||
|
||||
You can call :meth:`hash.update` as many times as you need to iteratively
|
||||
update the hash:
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>> items = [b'Hello', b' ', b'world']
|
||||
>>> h = blake2b()
|
||||
>>> for item in items:
|
||||
... h.update(item)
|
||||
>>> h.hexdigest()
|
||||
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
|
||||
|
||||
|
||||
Using different digest sizes
|
||||
----------------------------
|
||||
|
||||
BLAKE2 has configurable size of digests up to 64 bytes for BLAKE2b and up to 32
|
||||
bytes for BLAKE2s. For example, to replace SHA-1 with BLAKE2b without changing
|
||||
the size of output, we can tell BLAKE2b to produce 20-byte digests:
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>> h = blake2b(digest_size=20)
|
||||
>>> h.update(b'Replacing SHA1 with the more secure function')
|
||||
>>> h.hexdigest()
|
||||
'd24f26cf8de66472d58d4e1b1774b4c9158b1f4c'
|
||||
>>> h.digest_size
|
||||
20
|
||||
>>> len(h.digest())
|
||||
20
|
||||
|
||||
Hash objects with different digest sizes have completely different outputs
|
||||
(shorter hashes are *not* prefixes of longer hashes); BLAKE2b and BLAKE2s
|
||||
produce different outputs even if the output length is the same:
|
||||
|
||||
>>> from hashlib import blake2b, blake2s
|
||||
>>> blake2b(digest_size=10).hexdigest()
|
||||
'6fa1d8fcfd719046d762'
|
||||
>>> blake2b(digest_size=11).hexdigest()
|
||||
'eb6ec15daf9546254f0809'
|
||||
>>> blake2s(digest_size=10).hexdigest()
|
||||
'1bf21a98c78a1c376ae9'
|
||||
>>> blake2s(digest_size=11).hexdigest()
|
||||
'567004bf96e4a25773ebf4'
|
||||
|
||||
|
||||
Keyed hashing
|
||||
-------------
|
||||
|
||||
Keyed hashing can be used for authentication as a faster and simpler
|
||||
replacement for `Hash-based message authentication code
|
||||
<http://en.wikipedia.org/wiki/Hash-based_message_authentication_code>`_ (HMAC).
|
||||
BLAKE2 can be securely used in prefix-MAC mode thanks to the
|
||||
indifferentiability property inherited from BLAKE.
|
||||
|
||||
This example shows how to get a (hex-encoded) 128-bit authentication code for
|
||||
message ``b'message data'`` with key ``b'pseudorandom key'``::
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>> h = blake2b(key=b'pseudorandom key', digest_size=16)
|
||||
>>> h.update(b'message data')
|
||||
>>> h.hexdigest()
|
||||
'3d363ff7401e02026f4a4687d4863ced'
|
||||
|
||||
|
||||
As a practical example, a web application can symmetrically sign cookies sent
|
||||
to users and later verify them to make sure they weren't tampered with::
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>> from hmac import compare_digest
|
||||
>>>
|
||||
>>> SECRET_KEY = b'pseudorandomly generated server secret key'
|
||||
>>> AUTH_SIZE = 16
|
||||
>>>
|
||||
>>> def sign(cookie):
|
||||
... h = blake2b(data=cookie, digest_size=AUTH_SIZE, key=SECRET_KEY)
|
||||
... return h.hexdigest()
|
||||
>>>
|
||||
>>> cookie = b'user:vatrogasac'
|
||||
>>> sig = sign(cookie)
|
||||
>>> print("{0},{1}".format(cookie.decode('utf-8'), sig))
|
||||
user:vatrogasac,349cf904533767ed2d755279a8df84d0
|
||||
>>> compare_digest(cookie, sig)
|
||||
True
|
||||
>>> compare_digest(b'user:policajac', sig)
|
||||
False
|
||||
>>> compare_digesty(cookie, '0102030405060708090a0b0c0d0e0f00')
|
||||
False
|
||||
|
||||
Even though there's a native keyed hashing mode, BLAKE2 can, of course, be used
|
||||
in HMAC construction with :mod:`hmac` module::
|
||||
|
||||
>>> import hmac, hashlib
|
||||
>>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)
|
||||
>>> m.update(b'message')
|
||||
>>> m.hexdigest()
|
||||
'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'
|
||||
|
||||
|
||||
Randomized hashing
|
||||
------------------
|
||||
|
||||
By setting *salt* parameter users can introduce randomization to the hash
|
||||
function. Randomized hashing is useful for protecting against collision attacks
|
||||
on the hash function used in digital signatures.
|
||||
|
||||
Randomized hashing is designed for situations where one party, the message
|
||||
preparer, generates all or part of a message to be signed by a second
|
||||
party, the message signer. If the message preparer is able to find
|
||||
cryptographic hash function collisions (i.e., two messages producing the
|
||||
same hash value), then she might prepare meaningful versions of the message
|
||||
that would produce the same hash value and digital signature, but with
|
||||
different results (e.g., transferring $1,000,000 to an account, rather than
|
||||
$10). Cryptographic hash functions have been designed with collision
|
||||
resistance as a major goal, but the current concentration on attacking
|
||||
cryptographic hash functions may result in a given cryptographic hash
|
||||
function providing less collision resistance than expected. Randomized
|
||||
hashing offers the signer additional protection by reducing the likelihood
|
||||
that a preparer can generate two or more messages that ultimately yield the
|
||||
same hash value during the digital signature generation process --- even if
|
||||
it is practical to find collisions for the hash function. However, the use
|
||||
of randomized hashing may reduce the amount of security provided by a
|
||||
digital signature when all portions of the message are prepared
|
||||
by the signer.
|
||||
|
||||
(`NIST SP-800-106 "Randomized Hashing for Digital Signatures"
|
||||
<http://csrc.nist.gov/publications/nistpubs/800-106/NIST-SP-800-106.pdf>`_)
|
||||
|
||||
In BLAKE2 the salt is processed as a one-time input to the hash function during
|
||||
initialization, rather than as an input to each compression function.
|
||||
|
||||
.. warning::
|
||||
|
||||
*Salted hashing* (or just hashing) with BLAKE2 or any other general-purpose
|
||||
cryptographic hash function, such as SHA-256, is not suitable for hashing
|
||||
passwords. See `BLAKE2 FAQ <https://blake2.net/#qa>`_ for more
|
||||
information.
|
||||
..
|
||||
|
||||
>>> import os
|
||||
>>> from hashlib import blake2b
|
||||
>>> msg = b'some message'
|
||||
>>> # Calculate the first hash with a random salt.
|
||||
>>> salt1 = os.urandom(blake2b.SALT_SIZE)
|
||||
>>> h1 = blake2b(salt=salt1)
|
||||
>>> h1.update(msg)
|
||||
>>> # Calculate the second hash with a different random salt.
|
||||
>>> salt2 = os.urandom(blake2b.SALT_SIZE)
|
||||
>>> h2 = blake2b(salt=salt2)
|
||||
>>> h2.update(msg)
|
||||
>>> # The digests are different.
|
||||
>>> h1.digest() != h2.digest()
|
||||
True
|
||||
|
||||
|
||||
Personalization
|
||||
---------------
|
||||
|
||||
Sometimes it is useful to force hash function to produce different digests for
|
||||
the same input for different purposes. Quoting the authors of the Skein hash
|
||||
function:
|
||||
|
||||
We recommend that all application designers seriously consider doing this;
|
||||
we have seen many protocols where a hash that is computed in one part of
|
||||
the protocol can be used in an entirely different part because two hash
|
||||
computations were done on similar or related data, and the attacker can
|
||||
force the application to make the hash inputs the same. Personalizing each
|
||||
hash function used in the protocol summarily stops this type of attack.
|
||||
|
||||
(`The Skein Hash Function Family
|
||||
<http://www.skein-hash.info/sites/default/files/skein1.3.pdf>`_,
|
||||
p. 21)
|
||||
|
||||
BLAKE2 can be personalized by passing bytes to the *person* argument::
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>> FILES_HASH_PERSON = b'MyApp Files Hash'
|
||||
>>> BLOCK_HASH_PERSON = b'MyApp Block Hash'
|
||||
>>> h = blake2b(digest_size=32, person=FILES_HASH_PERSON)
|
||||
>>> h.update(b'the same content')
|
||||
>>> h.hexdigest()
|
||||
'20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'
|
||||
>>> h = blake2b(digest_size=32, person=BLOCK_HASH_PERSON)
|
||||
>>> h.update(b'the same content')
|
||||
>>> h.hexdigest()
|
||||
'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'
|
||||
|
||||
Personalization together with the keyed mode can also be used to derive different
|
||||
keys from a single one.
|
||||
|
||||
>>> from hashlib import blake2s
|
||||
>>> from base64 import b64decode, b64encode
|
||||
>>> orig_key = b64decode(b'Rm5EPJai72qcK3RGBpW3vPNfZy5OZothY+kHY6h21KM=')
|
||||
>>> enc_key = blake2s(key=orig_key, person=b'kEncrypt').digest()
|
||||
>>> mac_key = blake2s(key=orig_key, person=b'kMAC').digest()
|
||||
>>> print(b64encode(enc_key).decode('utf-8'))
|
||||
rbPb15S/Z9t+agffno5wuhB77VbRi6F9Iv2qIxU7WHw=
|
||||
>>> print(b64encode(mac_key).decode('utf-8'))
|
||||
G9GtHFE1YluXY1zWPlYk1e/nWfu0WSEb0KRcjhDeP/o=
|
||||
|
||||
Tree mode
|
||||
---------
|
||||
|
||||
Here's an example of hashing a minimal tree with two leaf nodes::
|
||||
|
||||
10
|
||||
/ \
|
||||
00 01
|
||||
|
||||
This example uses 64-byte internal digests, and returns the 32-byte final
|
||||
digest::
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>>
|
||||
>>> FANOUT = 2
|
||||
>>> DEPTH = 2
|
||||
>>> LEAF_SIZE = 4096
|
||||
>>> INNER_SIZE = 64
|
||||
>>>
|
||||
>>> buf = bytearray(6000)
|
||||
>>>
|
||||
>>> # Left leaf
|
||||
... h00 = blake2b(buf[0:LEAF_SIZE], fanout=FANOUT, depth=DEPTH,
|
||||
... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
|
||||
... node_offset=0, node_depth=0, last_node=False)
|
||||
>>> # Right leaf
|
||||
... h01 = blake2b(buf[LEAF_SIZE:], fanout=FANOUT, depth=DEPTH,
|
||||
... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
|
||||
... node_offset=1, node_depth=0, last_node=True)
|
||||
>>> # Root node
|
||||
... h10 = blake2b(digest_size=32, fanout=FANOUT, depth=DEPTH,
|
||||
... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
|
||||
... node_offset=0, node_depth=1, last_node=True)
|
||||
>>> h10.update(h00.digest())
|
||||
>>> h10.update(h01.digest())
|
||||
>>> h10.hexdigest()
|
||||
'3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa'
|
||||
|
||||
Credits
|
||||
=======
|
||||
|
||||
BLAKE2_ was designed by *Jean-Philippe Aumasson*, *Samuel Neves*, *Zooko
|
||||
Wilcox-O'Hearn*, and *Christian Winnerlein* based on SHA-3_ finalist BLAKE_
|
||||
created by *Jean-Philippe Aumasson*, *Luca Henzen*, *Willi Meier*, and
|
||||
*Raphael C.-W. Phan*.
|
||||
|
||||
It uses core algorithm from ChaCha_ cipher designed by *Daniel J. Bernstein*.
|
||||
|
||||
The stdlib implementation is based on pyblake2_ module. It was written by
|
||||
*Dmitry Chestnykh* based on C implementation written by *Samuel Neves*. The
|
||||
documentation was copied from pyblake2_ and written by *Dmitry Chestnykh*.
|
||||
|
||||
The C code was partly rewritten for Python by *Christian Heimes*.
|
||||
|
||||
The following public domain dedication applies for both C hash function
|
||||
implementation, extension code, and this documentation:
|
||||
|
||||
To the extent possible under law, the author(s) have dedicated all copyright
|
||||
and related and neighboring rights to this software to the public domain
|
||||
worldwide. This software is distributed without any warranty.
|
||||
|
||||
You should have received a copy of the CC0 Public Domain Dedication along
|
||||
with this software. If not, see
|
||||
http://creativecommons.org/publicdomain/zero/1.0/.
|
||||
|
||||
The following people have helped with development or contributed their changes
|
||||
to the project and the public domain according to the Creative Commons Public
|
||||
Domain Dedication 1.0 Universal:
|
||||
|
||||
* *Alexandr Sokolovskiy*
|
||||
|
||||
.. seealso:: Official BLAKE2 website: https://blake2.net
|
||||
|
||||
.. _RFC-7693: https://tools.ietf.org/html/rfc7693
|
||||
.. _BLAKE2: https://blake2.net
|
||||
.. _HMAC: https://en.wikipedia.org/wiki/Hash-based_message_authentication_code
|
||||
.. _BLAKE: https://131002.net/blake/
|
||||
.. _SHA-3: https://en.wikipedia.org/wiki/NIST_hash_function_competition
|
||||
.. _ChaCha: https://cr.yp.to/chacha.html
|
||||
.. _pyblake2: https://pythonhosted.org/pyblake2/
|
||||
|
||||
|
|
@ -278,7 +278,438 @@ include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
|
|||
BLAKE2
|
||||
------
|
||||
|
||||
BLAKE2 takes additional arguments, see :ref:`hashlib-blake2`.
|
||||
.. sectionauthor:: Dmitry Chestnykh
|
||||
|
||||
.. index::
|
||||
single: blake2b, blake2s
|
||||
|
||||
BLAKE2_ is a cryptographic hash function defined in RFC-7693_ that comes in two
|
||||
flavors:
|
||||
|
||||
* **BLAKE2b**, optimized for 64-bit platforms and produces digests of any size
|
||||
between 1 and 64 bytes,
|
||||
|
||||
* **BLAKE2s**, optimized for 8- to 32-bit platforms and produces digests of any
|
||||
size between 1 and 32 bytes.
|
||||
|
||||
BLAKE2 supports **keyed mode** (a faster and simpler replacement for HMAC_),
|
||||
**salted hashing**, **personalization**, and **tree hashing**.
|
||||
|
||||
Hash objects from this module follow the API of standard library's
|
||||
:mod:`hashlib` objects.
|
||||
|
||||
|
||||
Creating hash objects
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
New hash objects are created by calling constructor functions:
|
||||
|
||||
|
||||
.. function:: blake2b(data=b'', digest_size=64, key=b'', salt=b'', \
|
||||
person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, \
|
||||
node_depth=0, inner_size=0, last_node=False)
|
||||
|
||||
.. function:: blake2s(data=b'', digest_size=32, key=b'', salt=b'', \
|
||||
person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, \
|
||||
node_depth=0, inner_size=0, last_node=False)
|
||||
|
||||
|
||||
These functions return the corresponding hash objects for calculating
|
||||
BLAKE2b or BLAKE2s. They optionally take these general parameters:
|
||||
|
||||
* *data*: initial chunk of data to hash, which must be interpretable as buffer
|
||||
of bytes.
|
||||
|
||||
* *digest_size*: size of output digest in bytes.
|
||||
|
||||
* *key*: key for keyed hashing (up to 64 bytes for BLAKE2b, up to 32 bytes for
|
||||
BLAKE2s).
|
||||
|
||||
* *salt*: salt for randomized hashing (up to 16 bytes for BLAKE2b, up to 8
|
||||
bytes for BLAKE2s).
|
||||
|
||||
* *person*: personalization string (up to 16 bytes for BLAKE2b, up to 8 bytes
|
||||
for BLAKE2s).
|
||||
|
||||
The following table shows limits for general parameters (in bytes):
|
||||
|
||||
======= =========== ======== ========= ===========
|
||||
Hash digest_size len(key) len(salt) len(person)
|
||||
======= =========== ======== ========= ===========
|
||||
BLAKE2b 64 64 16 16
|
||||
BLAKE2s 32 32 8 8
|
||||
======= =========== ======== ========= ===========
|
||||
|
||||
.. note::
|
||||
|
||||
BLAKE2 specification defines constant lengths for salt and personalization
|
||||
parameters, however, for convenience, this implementation accepts byte
|
||||
strings of any size up to the specified length. If the length of the
|
||||
parameter is less than specified, it is padded with zeros, thus, for
|
||||
example, ``b'salt'`` and ``b'salt\x00'`` is the same value. (This is not
|
||||
the case for *key*.)
|
||||
|
||||
These sizes are available as module `constants`_ described below.
|
||||
|
||||
Constructor functions also accept the following tree hashing parameters:
|
||||
|
||||
* *fanout*: fanout (0 to 255, 0 if unlimited, 1 in sequential mode).
|
||||
|
||||
* *depth*: maximal depth of tree (1 to 255, 255 if unlimited, 1 in
|
||||
sequential mode).
|
||||
|
||||
* *leaf_size*: maximal byte length of leaf (0 to 2**32-1, 0 if unlimited or in
|
||||
sequential mode).
|
||||
|
||||
* *node_offset*: node offset (0 to 2**64-1 for BLAKE2b, 0 to 2**48-1 for
|
||||
BLAKE2s, 0 for the first, leftmost, leaf, or in sequential mode).
|
||||
|
||||
* *node_depth*: node depth (0 to 255, 0 for leaves, or in sequential mode).
|
||||
|
||||
* *inner_size*: inner digest size (0 to 64 for BLAKE2b, 0 to 32 for
|
||||
BLAKE2s, 0 in sequential mode).
|
||||
|
||||
* *last_node*: boolean indicating whether the processed node is the last
|
||||
one (`False` for sequential mode).
|
||||
|
||||
.. figure:: hashlib-blake2-tree.png
|
||||
:alt: Explanation of tree mode parameters.
|
||||
|
||||
See section 2.10 in `BLAKE2 specification
|
||||
<https://blake2.net/blake2_20130129.pdf>`_ for comprehensive review of tree
|
||||
hashing.
|
||||
|
||||
|
||||
Constants
|
||||
^^^^^^^^^
|
||||
|
||||
.. data:: blake2b.SALT_SIZE
|
||||
.. data:: blake2s.SALT_SIZE
|
||||
|
||||
Salt length (maximum length accepted by constructors).
|
||||
|
||||
|
||||
.. data:: blake2b.PERSON_SIZE
|
||||
.. data:: blake2s.PERSON_SIZE
|
||||
|
||||
Personalization string length (maximum length accepted by constructors).
|
||||
|
||||
|
||||
.. data:: blake2b.MAX_KEY_SIZE
|
||||
.. data:: blake2s.MAX_KEY_SIZE
|
||||
|
||||
Maximum key size.
|
||||
|
||||
|
||||
.. data:: blake2b.MAX_DIGEST_SIZE
|
||||
.. data:: blake2s.MAX_DIGEST_SIZE
|
||||
|
||||
Maximum digest size that the hash function can output.
|
||||
|
||||
|
||||
Examples
|
||||
^^^^^^^^
|
||||
|
||||
Simple hashing
|
||||
""""""""""""""
|
||||
|
||||
To calculate hash of some data, you should first construct a hash object by
|
||||
calling the appropriate constructor function (:func:`blake2b` or
|
||||
:func:`blake2s`), then update it with the data by calling :meth:`update` on the
|
||||
object, and, finally, get the digest out of the object by calling
|
||||
:meth:`digest` (or :meth:`hexdigest` for hex-encoded string).
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>> h = blake2b()
|
||||
>>> h.update(b'Hello world')
|
||||
>>> h.hexdigest()
|
||||
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
|
||||
|
||||
|
||||
As a shortcut, you can pass the first chunk of data to update directly to the
|
||||
constructor as the first argument (or as *data* keyword argument):
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>> blake2b(b'Hello world').hexdigest()
|
||||
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
|
||||
|
||||
You can call :meth:`hash.update` as many times as you need to iteratively
|
||||
update the hash:
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>> items = [b'Hello', b' ', b'world']
|
||||
>>> h = blake2b()
|
||||
>>> for item in items:
|
||||
... h.update(item)
|
||||
>>> h.hexdigest()
|
||||
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'
|
||||
|
||||
|
||||
Using different digest sizes
|
||||
""""""""""""""""""""""""""""
|
||||
|
||||
BLAKE2 has configurable size of digests up to 64 bytes for BLAKE2b and up to 32
|
||||
bytes for BLAKE2s. For example, to replace SHA-1 with BLAKE2b without changing
|
||||
the size of output, we can tell BLAKE2b to produce 20-byte digests:
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>> h = blake2b(digest_size=20)
|
||||
>>> h.update(b'Replacing SHA1 with the more secure function')
|
||||
>>> h.hexdigest()
|
||||
'd24f26cf8de66472d58d4e1b1774b4c9158b1f4c'
|
||||
>>> h.digest_size
|
||||
20
|
||||
>>> len(h.digest())
|
||||
20
|
||||
|
||||
Hash objects with different digest sizes have completely different outputs
|
||||
(shorter hashes are *not* prefixes of longer hashes); BLAKE2b and BLAKE2s
|
||||
produce different outputs even if the output length is the same:
|
||||
|
||||
>>> from hashlib import blake2b, blake2s
|
||||
>>> blake2b(digest_size=10).hexdigest()
|
||||
'6fa1d8fcfd719046d762'
|
||||
>>> blake2b(digest_size=11).hexdigest()
|
||||
'eb6ec15daf9546254f0809'
|
||||
>>> blake2s(digest_size=10).hexdigest()
|
||||
'1bf21a98c78a1c376ae9'
|
||||
>>> blake2s(digest_size=11).hexdigest()
|
||||
'567004bf96e4a25773ebf4'
|
||||
|
||||
|
||||
Keyed hashing
|
||||
"""""""""""""
|
||||
|
||||
Keyed hashing can be used for authentication as a faster and simpler
|
||||
replacement for `Hash-based message authentication code
|
||||
<http://en.wikipedia.org/wiki/Hash-based_message_authentication_code>`_ (HMAC).
|
||||
BLAKE2 can be securely used in prefix-MAC mode thanks to the
|
||||
indifferentiability property inherited from BLAKE.
|
||||
|
||||
This example shows how to get a (hex-encoded) 128-bit authentication code for
|
||||
message ``b'message data'`` with key ``b'pseudorandom key'``::
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>> h = blake2b(key=b'pseudorandom key', digest_size=16)
|
||||
>>> h.update(b'message data')
|
||||
>>> h.hexdigest()
|
||||
'3d363ff7401e02026f4a4687d4863ced'
|
||||
|
||||
|
||||
As a practical example, a web application can symmetrically sign cookies sent
|
||||
to users and later verify them to make sure they weren't tampered with::
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>> from hmac import compare_digest
|
||||
>>>
|
||||
>>> SECRET_KEY = b'pseudorandomly generated server secret key'
|
||||
>>> AUTH_SIZE = 16
|
||||
>>>
|
||||
>>> def sign(cookie):
|
||||
... h = blake2b(data=cookie, digest_size=AUTH_SIZE, key=SECRET_KEY)
|
||||
... return h.hexdigest()
|
||||
>>>
|
||||
>>> cookie = b'user:vatrogasac'
|
||||
>>> sig = sign(cookie)
|
||||
>>> print("{0},{1}".format(cookie.decode('utf-8'), sig))
|
||||
user:vatrogasac,349cf904533767ed2d755279a8df84d0
|
||||
>>> compare_digest(cookie, sig)
|
||||
True
|
||||
>>> compare_digest(b'user:policajac', sig)
|
||||
False
|
||||
>>> compare_digesty(cookie, '0102030405060708090a0b0c0d0e0f00')
|
||||
False
|
||||
|
||||
Even though there's a native keyed hashing mode, BLAKE2 can, of course, be used
|
||||
in HMAC construction with :mod:`hmac` module::
|
||||
|
||||
>>> import hmac, hashlib
|
||||
>>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)
|
||||
>>> m.update(b'message')
|
||||
>>> m.hexdigest()
|
||||
'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'
|
||||
|
||||
|
||||
Randomized hashing
|
||||
""""""""""""""""""
|
||||
|
||||
By setting *salt* parameter users can introduce randomization to the hash
|
||||
function. Randomized hashing is useful for protecting against collision attacks
|
||||
on the hash function used in digital signatures.
|
||||
|
||||
Randomized hashing is designed for situations where one party, the message
|
||||
preparer, generates all or part of a message to be signed by a second
|
||||
party, the message signer. If the message preparer is able to find
|
||||
cryptographic hash function collisions (i.e., two messages producing the
|
||||
same hash value), then she might prepare meaningful versions of the message
|
||||
that would produce the same hash value and digital signature, but with
|
||||
different results (e.g., transferring $1,000,000 to an account, rather than
|
||||
$10). Cryptographic hash functions have been designed with collision
|
||||
resistance as a major goal, but the current concentration on attacking
|
||||
cryptographic hash functions may result in a given cryptographic hash
|
||||
function providing less collision resistance than expected. Randomized
|
||||
hashing offers the signer additional protection by reducing the likelihood
|
||||
that a preparer can generate two or more messages that ultimately yield the
|
||||
same hash value during the digital signature generation process --- even if
|
||||
it is practical to find collisions for the hash function. However, the use
|
||||
of randomized hashing may reduce the amount of security provided by a
|
||||
digital signature when all portions of the message are prepared
|
||||
by the signer.
|
||||
|
||||
(`NIST SP-800-106 "Randomized Hashing for Digital Signatures"
|
||||
<http://csrc.nist.gov/publications/nistpubs/800-106/NIST-SP-800-106.pdf>`_)
|
||||
|
||||
In BLAKE2 the salt is processed as a one-time input to the hash function during
|
||||
initialization, rather than as an input to each compression function.
|
||||
|
||||
.. warning::
|
||||
|
||||
*Salted hashing* (or just hashing) with BLAKE2 or any other general-purpose
|
||||
cryptographic hash function, such as SHA-256, is not suitable for hashing
|
||||
passwords. See `BLAKE2 FAQ <https://blake2.net/#qa>`_ for more
|
||||
information.
|
||||
..
|
||||
|
||||
>>> import os
|
||||
>>> from hashlib import blake2b
|
||||
>>> msg = b'some message'
|
||||
>>> # Calculate the first hash with a random salt.
|
||||
>>> salt1 = os.urandom(blake2b.SALT_SIZE)
|
||||
>>> h1 = blake2b(salt=salt1)
|
||||
>>> h1.update(msg)
|
||||
>>> # Calculate the second hash with a different random salt.
|
||||
>>> salt2 = os.urandom(blake2b.SALT_SIZE)
|
||||
>>> h2 = blake2b(salt=salt2)
|
||||
>>> h2.update(msg)
|
||||
>>> # The digests are different.
|
||||
>>> h1.digest() != h2.digest()
|
||||
True
|
||||
|
||||
|
||||
Personalization
|
||||
"""""""""""""""
|
||||
|
||||
Sometimes it is useful to force hash function to produce different digests for
|
||||
the same input for different purposes. Quoting the authors of the Skein hash
|
||||
function:
|
||||
|
||||
We recommend that all application designers seriously consider doing this;
|
||||
we have seen many protocols where a hash that is computed in one part of
|
||||
the protocol can be used in an entirely different part because two hash
|
||||
computations were done on similar or related data, and the attacker can
|
||||
force the application to make the hash inputs the same. Personalizing each
|
||||
hash function used in the protocol summarily stops this type of attack.
|
||||
|
||||
(`The Skein Hash Function Family
|
||||
<http://www.skein-hash.info/sites/default/files/skein1.3.pdf>`_,
|
||||
p. 21)
|
||||
|
||||
BLAKE2 can be personalized by passing bytes to the *person* argument::
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>> FILES_HASH_PERSON = b'MyApp Files Hash'
|
||||
>>> BLOCK_HASH_PERSON = b'MyApp Block Hash'
|
||||
>>> h = blake2b(digest_size=32, person=FILES_HASH_PERSON)
|
||||
>>> h.update(b'the same content')
|
||||
>>> h.hexdigest()
|
||||
'20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'
|
||||
>>> h = blake2b(digest_size=32, person=BLOCK_HASH_PERSON)
|
||||
>>> h.update(b'the same content')
|
||||
>>> h.hexdigest()
|
||||
'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'
|
||||
|
||||
Personalization together with the keyed mode can also be used to derive different
|
||||
keys from a single one.
|
||||
|
||||
>>> from hashlib import blake2s
|
||||
>>> from base64 import b64decode, b64encode
|
||||
>>> orig_key = b64decode(b'Rm5EPJai72qcK3RGBpW3vPNfZy5OZothY+kHY6h21KM=')
|
||||
>>> enc_key = blake2s(key=orig_key, person=b'kEncrypt').digest()
|
||||
>>> mac_key = blake2s(key=orig_key, person=b'kMAC').digest()
|
||||
>>> print(b64encode(enc_key).decode('utf-8'))
|
||||
rbPb15S/Z9t+agffno5wuhB77VbRi6F9Iv2qIxU7WHw=
|
||||
>>> print(b64encode(mac_key).decode('utf-8'))
|
||||
G9GtHFE1YluXY1zWPlYk1e/nWfu0WSEb0KRcjhDeP/o=
|
||||
|
||||
Tree mode
|
||||
"""""""""
|
||||
|
||||
Here's an example of hashing a minimal tree with two leaf nodes::
|
||||
|
||||
10
|
||||
/ \
|
||||
00 01
|
||||
|
||||
This example uses 64-byte internal digests, and returns the 32-byte final
|
||||
digest::
|
||||
|
||||
>>> from hashlib import blake2b
|
||||
>>>
|
||||
>>> FANOUT = 2
|
||||
>>> DEPTH = 2
|
||||
>>> LEAF_SIZE = 4096
|
||||
>>> INNER_SIZE = 64
|
||||
>>>
|
||||
>>> buf = bytearray(6000)
|
||||
>>>
|
||||
>>> # Left leaf
|
||||
... h00 = blake2b(buf[0:LEAF_SIZE], fanout=FANOUT, depth=DEPTH,
|
||||
... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
|
||||
... node_offset=0, node_depth=0, last_node=False)
|
||||
>>> # Right leaf
|
||||
... h01 = blake2b(buf[LEAF_SIZE:], fanout=FANOUT, depth=DEPTH,
|
||||
... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
|
||||
... node_offset=1, node_depth=0, last_node=True)
|
||||
>>> # Root node
|
||||
... h10 = blake2b(digest_size=32, fanout=FANOUT, depth=DEPTH,
|
||||
... leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
|
||||
... node_offset=0, node_depth=1, last_node=True)
|
||||
>>> h10.update(h00.digest())
|
||||
>>> h10.update(h01.digest())
|
||||
>>> h10.hexdigest()
|
||||
'3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa'
|
||||
|
||||
Credits
|
||||
^^^^^^^
|
||||
|
||||
BLAKE2_ was designed by *Jean-Philippe Aumasson*, *Samuel Neves*, *Zooko
|
||||
Wilcox-O'Hearn*, and *Christian Winnerlein* based on SHA-3_ finalist BLAKE_
|
||||
created by *Jean-Philippe Aumasson*, *Luca Henzen*, *Willi Meier*, and
|
||||
*Raphael C.-W. Phan*.
|
||||
|
||||
It uses core algorithm from ChaCha_ cipher designed by *Daniel J. Bernstein*.
|
||||
|
||||
The stdlib implementation is based on pyblake2_ module. It was written by
|
||||
*Dmitry Chestnykh* based on C implementation written by *Samuel Neves*. The
|
||||
documentation was copied from pyblake2_ and written by *Dmitry Chestnykh*.
|
||||
|
||||
The C code was partly rewritten for Python by *Christian Heimes*.
|
||||
|
||||
The following public domain dedication applies for both C hash function
|
||||
implementation, extension code, and this documentation:
|
||||
|
||||
To the extent possible under law, the author(s) have dedicated all copyright
|
||||
and related and neighboring rights to this software to the public domain
|
||||
worldwide. This software is distributed without any warranty.
|
||||
|
||||
You should have received a copy of the CC0 Public Domain Dedication along
|
||||
with this software. If not, see
|
||||
http://creativecommons.org/publicdomain/zero/1.0/.
|
||||
|
||||
The following people have helped with development or contributed their changes
|
||||
to the project and the public domain according to the Creative Commons Public
|
||||
Domain Dedication 1.0 Universal:
|
||||
|
||||
* *Alexandr Sokolovskiy*
|
||||
|
||||
.. _RFC-7693: https://tools.ietf.org/html/rfc7693
|
||||
.. _BLAKE2: https://blake2.net
|
||||
.. _HMAC: https://en.wikipedia.org/wiki/Hash-based_message_authentication_code
|
||||
.. _BLAKE: https://131002.net/blake/
|
||||
.. _SHA-3: https://en.wikipedia.org/wiki/NIST_hash_function_competition
|
||||
.. _ChaCha: https://cr.yp.to/chacha.html
|
||||
.. _pyblake2: https://pythonhosted.org/pyblake2/
|
||||
|
||||
|
||||
|
||||
.. seealso::
|
||||
|
|
@ -289,7 +720,8 @@ BLAKE2 takes additional arguments, see :ref:`hashlib-blake2`.
|
|||
Module :mod:`base64`
|
||||
Another way to encode binary hashes for non-binary environments.
|
||||
|
||||
See :ref:`hashlib-blake2`.
|
||||
https://blake2.net
|
||||
Official BLAKE2 website.
|
||||
|
||||
http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
|
||||
The FIPS 180-2 publication on Secure Hash Algorithms.
|
||||
|
|
|
|||
Loading…
Reference in New Issue