--- /dev/null
- same hash value during the digital signature generation process – even if
+.. _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/
+
projects / python / commitdiff