"hashlib" --- Algorithmes de hachage sécurisés et synthèse de messages
**********************************************************************

**Code source :** Lib/hashlib.py

======================================================================

This module implements a common interface to many different secure
hash and message digest algorithms.  Included are the FIPS secure hash
algorithms SHA1, SHA224, SHA256, SHA384, SHA512, (defined in the FIPS
180-4 standard), the SHA-3 series (defined in the FIPS 202 standard)
as well as RSA's MD5 algorithm (defined in internet **RFC 1321**).
The terms "secure hash" and "message digest" are interchangeable.
Older algorithms were called message digests.  The modern term is
secure hash.

Note:

  Si vous préférez utiliser les fonctions de hachage *adler32* ou
  *crc32*, elles sont disponibles dans le module "zlib".


Algorithmes de hachage
======================

There is one constructor method named for each type of *hash*.  All
return a hash object with the same simple interface. For example: use
"sha256()" to create a SHA-256 hash object. You can now feed this
object with *bytes-like objects* (normally "bytes") using the "update"
method.  At any point you can ask it for the *digest* of the
concatenation of the data fed to it so far using the "digest()" or
"hexdigest()" methods.

To allow multithreading, the Python *GIL* is released while computing
a hash supplied more than 2047 bytes of data at once in its
constructor or ".update" method.

Constructors for hash algorithms that are always present in this
module are "sha1()", "sha224()", "sha256()", "sha384()", "sha512()",
"sha3_224()", "sha3_256()", "sha3_384()", "sha3_512()", "shake_128()",
"shake_256()", "blake2b()", and "blake2s()". "md5()" is normally
available as well, though it may be missing or blocked if you are
using a rare "FIPS compliant" build of Python. These correspond to
"algorithms_guaranteed".

Additional algorithms may also be available if your Python
distribution's "hashlib" was linked against a build of OpenSSL that
provides others. Others *are not guaranteed available* on all
installations and will only be accessible by name via "new()".  See
"algorithms_available".

Avertissement:

  Some algorithms have known hash collision weaknesses (including MD5
  and SHA1). Refer to Attacks on cryptographic hash algorithms and the
  hashlib-seealso section at the end of this document.

Nouveau dans la version 3.6: SHA3 (Keccak) and SHAKE constructors
"sha3_224()", "sha3_256()", "sha3_384()", "sha3_512()", "shake_128()",
"shake_256()" were added. "blake2b()" and "blake2s()" were added.

Modifié dans la version 3.9: tous les constructeurs de *hashlib*
prennent un argument mot-clé uniquement *usedforsecurity* avec la
valeur par défaut "True". Une valeur fausse permet l'utilisation
d'algorithmes de hachage non sécurisés et bloqués dans des
environnements restreints. "False" indique que l'algorithme de hachage
ne sera pas utilisé dans un contexte de sécurité, par exemple en tant
que fonction de compression à sens unique non cryptographique.

Modifié dans la version 3.9: Hashlib now uses SHA3 and SHAKE from
OpenSSL if it provides it.


Usage
=====

To obtain the digest of the byte string "b"Nobody inspects the
spammish repetition"":

   >>> import hashlib
   >>> m = hashlib.sha256()
   >>> m.update(b"Nobody inspects")
   >>> m.update(b" the spammish repetition")
   >>> m.digest()
   b'\x03\x1e\xdd}Ae\x15\x93\xc5\xfe\\\x00o\xa5u+7\xfd\xdf\xf7\xbcN\x84:\xa6\xaf\x0c\x95\x0fK\x94\x06'
   >>> m.hexdigest()
   '031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'

En plus condensé :

>>> hashlib.sha256(b"Nobody inspects the spammish repetition").hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'


Constructors
============

hashlib.new(name, [data, ]*, usedforsecurity=True)

   Is a generic constructor that takes the string *name* of the
   desired algorithm as its first parameter.  It also exists to allow
   access to the above listed hashes as well as any other algorithms
   that your OpenSSL library may offer.

Using "new()" with an algorithm name:

>>> h = hashlib.new('sha256')
>>> h.update(b"Nobody inspects the spammish repetition")
>>> h.hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'

hashlib.md5([data, ]*, usedforsecurity=True)

hashlib.sha1([data, ]*, usedforsecurity=True)

hashlib.sha224([data, ]*, usedforsecurity=True)

hashlib.sha256([data, ]*, usedforsecurity=True)

hashlib.sha384([data, ]*, usedforsecurity=True)

hashlib.sha512([data, ]*, usedforsecurity=True)

hashlib.sha3_224([data, ]*, usedforsecurity=True)

hashlib.sha3_256([data, ]*, usedforsecurity=True)

hashlib.sha3_384([data, ]*, usedforsecurity=True)

hashlib.sha3_512([data, ]*, usedforsecurity=True)

Named constructors such as these are faster than passing an algorithm
name to "new()".


Attributes
==========

Hashlib provides the following constant module attributes:

hashlib.algorithms_guaranteed

   Ensemble contenant les noms des algorithmes de hachage garantis
   d'être implémentés par ce module sur toutes les plate-formes. Notez
   que *md5* est dans cette liste bien que certains éditeurs diffusent
   une implémentation Python dont la bibliothèque « compatible FIPS »
   le bloque.

   Nouveau dans la version 3.2.

hashlib.algorithms_available

   Ensemble contenant les noms des algorithmes de hachage disponibles
   dans l'interpréteur Python. Ces noms sont reconnus lorsqu'ils sont
   passés à la fonction "new()".  "algorithms_guaranteed" est toujours
   un sous-ensemble. Le même algorithme peut apparaître plusieurs fois
   dans cet ensemble sous un nom différent (grâce à OpenSSL).

   Nouveau dans la version 3.2.


Hash Objects
============

Les valeurs suivantes sont fournies en tant qu'attributs constants des
objets de calcul d'empreintes renvoyés par les constructeurs :

hash.digest_size

   La taille du *hash* résultant en octets.

hash.block_size

   La taille interne d'un bloc de l'algorithme de hachage en octets.

L'objet de hachage possède les attributs suivants :

hash.name

   Le nom canonique de cette fonction de hachage, toujours en
   minuscule et que vous pouvez toujours transmettre à la fonction
   "new()" pour créer un autre objet de calcul d'empreinte de ce type.

   Modifié dans la version 3.4: l'attribut *name* est présent dans
   CPython depuis sa création, mais n'était pas spécifié formellement
   jusqu'à Python 3.4, il peut ne pas exister sur certaines plate-
   formes.

L'objet de calcul d'empreinte possède les méthodes suivantes :

hash.update(data)

   Met à jour l'objet de hachage avec *bytes-like object*. Les appels
   répétés sont équivalents à un simple appel avec la concaténation de
   tous les arguments : "m.update(a); m.update(b)" est équivalent à
   "m.update(a+b)".

   Modifié dans la version 3.1: le GIL Python est relâché pour
   permettre aux autres fils d'exécution de tourner pendant que la
   fonction de hachage met à jour des données plus longues que 2047
   octets, lorsque les algorithmes fournis par OpenSSL sont utilisés.

hash.digest()

   Renvoie l'empreinte (le *hash*) des données passées à la méthode
   "update()". C'est un objet de type *bytes* de taille "digest_size"
   qui contient des octets dans l'intervalle 0 à 255.

hash.hexdigest()

   Comme la méthode "digest()" sauf que l'empreinte renvoyée est une
   chaîne de caractères dont la longueur est double, contenant
   seulement des chiffres hexadécimaux. Elle peut être utilisée pour
   échanger sans risque des valeurs dans les *e-mails* ou dans les
   environnements non binaires.

hash.copy()

   Renvoie une copie ("clone") de l'objet de calcul de hachage. Cela
   peut être utilisé pour calculer efficacement des empreintes de
   données qui commencent par la même sous-chaine.


Empreintes de messages de taille variable SHAKE
===============================================

hashlib.shake_128([data, ]*, usedforsecurity=True)

hashlib.shake_256([data, ]*, usedforsecurity=True)

Les algorithmes "shake_128()" et "shake_256()" produisent des
empreintes (ou condensats) de longueur variable avec des
"longueurs_en_bits // 2" jusqu'à 128 ou 256 bits. Leurs méthodes de
calcul d'empreinte requièrent une longueur. Les longueurs maximales ne
sont pas limitées par l'algorithme SHAKE.

shake.digest(length)

   Return the digest of the data passed to the "update()" method so
   far. This is a bytes object of size *length* which may contain
   bytes in the whole range from 0 to 255.

shake.hexdigest(length)

   Like "digest()" except the digest is returned as a string object of
   double length, containing only hexadecimal digits.  This may be
   used to exchange the value in email or other non-binary
   environments.

Example use:

>>> h = hashlib.shake_256(b'Nobody inspects the spammish repetition')
>>> h.hexdigest(20)
'44709d6fcb83d92a76dcb0b668c98e1b1d3dafe7'


Calcul d'empreinte (ou hachage) de fichiers
===========================================

Le module *hashlib* fournit une fonction utilitaire pour calculer
efficacement l'empreinte (aussi appelée condensat) d'un fichier ou
d'un objet fichier-compatible.

hashlib.file_digest(fileobj, digest, /)

   Renvoie un objet de calcul d'empreinte qui a été mis à jour avec le
   contenu de *fileobj*.

   *fileobj* doit être un objet fichier-compatible ouvert en lecture
   en mode binaire. Sont acceptés les instances d'objets fichiers
   produites par la fonction native  "open()", "BytesIO", les objets
   connecteurs produits par  "socket.socket.makefile()" et similaires.
   La fonction peut court-circuiter les entrées-sorties de Python et
   utiliser directement le descripteur de fichier de "fileno()". Vous
   devez supposer que *fileobj* est dans un état inconnu après le
   retour de cette fonction ou si elle a levé une exception. C'est à
   l'appelant de fermer *fileobj*.

   *digest* doit être un nom d'algorithme de hachage fourni en tant
   que *str*, un constructeur de hachage ou un appelable qui renvoie
   un objet de hachage.

   Exemple :

   >>> import io, hashlib, hmac
   >>> with open(hashlib.__file__, "rb") as f:
   ...     digest = hashlib.file_digest(f, "sha256")
   ...
   >>> digest.hexdigest()  
   '...'

   >>> buf = io.BytesIO(b"somedata")
   >>> mac1 = hmac.HMAC(b"key", digestmod=hashlib.sha512)
   >>> digest = hashlib.file_digest(buf, lambda: mac1)

   >>> digest is mac1
   True
   >>> mac2 = hmac.HMAC(b"key", b"somedata", digestmod=hashlib.sha512)
   >>> mac1.digest() == mac2.digest()
   True

   Nouveau dans la version 3.11.


Dérivation de clé
=================

Les algorithmes de dérivation de clés et d'étirement de clés sont
conçus pour le hachage sécurisé de mots de passe. Des algorithmes
naïfs comme "sha1(password)" ne sont pas résistants aux attaques par
force brute. Une bonne fonction de hachage doit être paramétrable,
lente et inclure un salage.

hashlib.pbkdf2_hmac(hash_name, password, salt, iterations, dklen=None)

   La fonction fournit une fonction de dérivation conforme à PKCS#5
   (*Public Key Cryptographic Standards #5 v2.0*). Elle utilise HMAC
   comme fonction de génération d'un pseudo-aléa.

   La chaîne de caractères *hash_name* est le nom de l'algorithme de
   hachage désiré pour le HMAC, par exemple ""sha1"" ou ""sha256"".
   *password* et *salt* sont interprétés comme des tampons d'octets.
   Les applications et bibliothèques doivent limiter *password* à une
   longueur raisonnable (comme "1024"). *salt* doit être de 16 octets
   ou plus et provenir d'une source correcte, e.g. "os.urandom()".

   Le nombre d'*itérations* doit être choisi en fonction de
   l'algorithme de hachage et de la puissance de calcul. À partir de
   2022, des centaines de milliers d'itérations de SHA-256 sont
   suggérées. Pour savoir pourquoi et comment choisir ce qui convient
   le mieux à votre application, lisez *l'annexe A.2.2* du NIST-
   SP-800-132 (ressource en anglais). Les réponses contenues dans la
   question sur le site *stackexchange* nombre d'itérations
   recommandées lorsqu'on utilise pbkdf2 (page en anglais) expliquent
   tout en détail.

   *dklen* est la longueur de la clé dérivée. Si *dklen* vaut "None"
   alors Python utilise la taille du condensat produit par
   l'algorithme de hachage *hash_name*, par exemple 64 pour SHA-512.

   >>> from hashlib import pbkdf2_hmac
   >>> our_app_iters = 500_000  # Application specific, read above.
   >>> dk = pbkdf2_hmac('sha256', b'password', b'bad salt'*2, our_app_iters)
   >>> dk.hex()
   '15530bba69924174860db778f2c6f8104d3aaf9d26241840c8c4a641c8d000a9'

   Nouveau dans la version 3.4.

   Note:

     une implémentation rapide de *pbkdf2_hmac* est disponible avec
     OpenSSL. L'implémentation Python utilise une version *inline* de
     "hmac". Elle est trois fois plus lente et ne libère pas le GIL.

   Obsolète depuis la version 3.10: l'implémentation en Python (lente)
   de *pbkdf2_hmac* est obsolète. À l'avenir, la fonction ne sera
   disponible que lorsque Python est compilé avec OpenSSL.

hashlib.scrypt(password, *, salt, n, r, p, maxmem=0, dklen=64)

   La fonction fournit la fonction de dérivation de clé *scrypt* comme
   définie dans la **RFC 7914**.

   *password* et *salt* doivent être des *objets octets-compatibles*.
   Les applications et bibliothèques doivent limiter *password* à une
   longueur raisonnable (par ex. 1024). *salt* doit être de 16 octets
   ou plus et provenir d'une source correcte, par ex. "os.urandom()".

   *n* est le facteur de coût CPU/Mémoire, *r* la taille de bloc, *p*
   le facteur de parallélisation et *maxmem* limite l'utilisation de
   la mémoire (OpenSSL 1.1.0 limite à 32 Mio par défaut). *dklen* est
   la longueur de la clé dérivée.

   Nouveau dans la version 3.6.


BLAKE2
======

BLAKE2 est une fonction de hachage cryptographique définie dans la
**RFC 7693** et disponible en deux versions :

* **BLAKE2b**, optimisée pour les plates-formes 64 bits et produisant
  des condensats de toutes tailles entre 1 et 64 octets,

* **BLAKE2s**, optimisée pour les plates-formes de 8 à 32 bits et
  produisant des empreintes de toutes tailles entre 1 et 32 octets.

BLAKE2 gère diverses fonctionnalités comme le **keyed mode** (plus
rapide et plus simple que HMAC), **salted hashing**,
**personalization** et le **tree hashing**.

Les objets de calcul d'empreinte de ce module suivent l'API des objets
du module "hashlib" de la bibliothèque standard.


Création d'objets de calcul d'empreinte
---------------------------------------

Les nouveaux objets de calcul d'empreinte sont créés en appelant les
constructeurs :

hashlib.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, usedforsecurity=True)

hashlib.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, usedforsecurity=True)

Ces fonctions produisent l'objet de calcul d'empreinte correspondant
aux algorithmes BLAKE2b ou BLAKE2s. Elles prennent ces paramètres
optionnels :

* *data* : morceau initial de données à hacher, qui doit être un
  *objet octets-compatible*. Il ne peut être passé que comme argument
  positionnel.

* *digest_size* : taille en octets de l'empreinte produite.

* *key* : clé pour les codes d'authentification de message *keyed
  hashing* (jusqu'à 64 octets pour BLAKE2b, jusqu'à 32 octets pour
  BLAKE2s).

* *salt* : sel pour le hachage randomisé *randomized hashing* (jusqu'à
  16 octets pour BLAKE2b, jusqu'à 8 octets pour BLAKE2s).

* *person* : chaîne de personnalisation (jusqu'à 16 octets pour
  BLAKE2b, jusqu'à 8 octets pour BLAKE2s).

Le tableau suivant présente les limites des paramètres généraux (en
octets) :

+---------+-------------+----------+-----------+-------------+
| Hash    | digest_size | len(key) | len(salt) | len(person) |
|=========|=============|==========|===========|=============|
| BLAKE2b | 64          | 64       | 16        | 16          |
+---------+-------------+----------+-----------+-------------+
| BLAKE2s | 32          | 32       | 8         | 8           |
+---------+-------------+----------+-----------+-------------+

Note:

  les spécifications de BLAKE2 définissent des longueurs constantes
  pour les sel et chaînes de personnalisation. Toutefois, par
  commodité, cette implémentation accepte des chaînes d'octets de
  n'importe quelle taille jusqu'à la longueur spécifiée. Si la
  longueur du paramètre est moindre par rapport à celle spécifiée, il
  est complété par des zéros. Ainsi, par exemple, "b'salt'" et
  "b'salt\x00'" sont la même valeur (ce n'est pas le cas pour *key*).

Ces tailles sont disponibles en tant que constantes du module et
décrites ci-dessous.

Les fonctions constructeurs acceptent aussi les paramètres suivants
pour le calcul d'empreintes en mode arbre :

* *fanout* : *étalement* (0 à 255, 0 si illimité, 1 correspond au mode
  séquentiel).

* *depth* : profondeur maximale de l'arbre (1 à 255, 255 si illimité,
  1 correspond au mode séquentiel).

* *leaf_size* : taille maximale en octets d'une feuille (0 à
  "2**32-1", 0 si illimité ou en mode séquentiel).

* *node_offset* : décalage du nœud (0 à "2**64-1" pour BLAKE2b, 0 à
  "2**48-1" pour BLAKE2s, 0 pour la première feuille la plus à gauche,
  ou en mode séquentiel).

* *node_depth* : profondeur du nœud (0 à 255, 0 pour les feuilles, ou
  en mode séquentiel).

* *inner_size* : taille de l'empreinte interne (0 à 64 pour BLAKE2b, 0
  à 32 pour BLAKE2s, 0 en mode séquentiel).

* *last_node* : booléen indiquant si le nœud traité est le dernier
  ("False" pour le mode séquentiel).

   [image: Explication des paramètres du mode arbre.][image]

See section 2.10 in BLAKE2 specification for comprehensive review of
tree hashing.


Constantes
----------

blake2b.SALT_SIZE

blake2s.SALT_SIZE

Longueur du sel (longueur maximale acceptée par les constructeurs).

blake2b.PERSON_SIZE

blake2s.PERSON_SIZE

Longueur de la chaîne de personnalisation (longueur maximale acceptée
par les constructeurs).

blake2b.MAX_KEY_SIZE

blake2s.MAX_KEY_SIZE

Taille maximale de clé.

blake2b.MAX_DIGEST_SIZE

blake2s.MAX_DIGEST_SIZE

Taille maximale du message que peut fournir la fonction de hachage.


Exemples
--------


Hachage simple
~~~~~~~~~~~~~~

To calculate hash of some data, you should first construct a hash
object by calling the appropriate constructor function ("blake2b()" or
"blake2s()"), then update it with the data by calling "update()" on
the object, and, finally, get the digest out of the object by calling
"digest()" (or "hexdigest()" for hex-encoded string).

>>> from hashlib import blake2b
>>> h = blake2b()
>>> h.update(b'Hello world')
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

En plus court, vous pouvez passer directement au constructeur, comme
argument positionnel, le premier morceau du message pour le mettre
directement à jour :

>>> from hashlib import blake2b
>>> blake2b(b'Hello world').hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

Vous pouvez appeler la méthode "hash.update()" autant de fois que
nécessaire pour mettre à jour l'empreinte de manière itérative :

>>> from hashlib import blake2b
>>> items = [b'Hello', b' ', b'world']
>>> h = blake2b()
>>> for item in items:
...     h.update(item)
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'


Production de tailles d'empreintes différentes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

BLAKE2 permet de configurer la taille des empreintes jusqu'à 64 octets
pour BLAKE2b et jusqu'à 32 octets pour BLAKE2s. Par exemple, pour
remplacer SHA-1 par BLAKE2b sans changer la taille de la sortie, nous
pouvons dire à BLAKE2b de produire une empreinte de 20 octets :

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

Les objets de calcul d'empreinte initialisés avec des tailles
d'empreintes différentes ont des sorties complètement différentes (les
condensats courts *ne sont pas* des préfixes de condensats plus longs)
; BLAKE2b et BLAKE2s produisent des sorties différentes même si les
longueurs de sortie sont les mêmes :

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


Hachage avec clé – Code d'authentification de message
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Le hachage avec clé (*keyed hashing* en anglais) est une alternative
plus simple et plus rapide à un code d’authentification de message de
hachage à clé (HMAC). BLAKE2 peut être utilisé de manière sécurisée
dans le mode préfixe MAC grâce à la propriété d'indifférentiabilité
héritée de BLAKE.

Cet exemple montre comment obtenir un code d'authentification de
message de 128 bits (en hexadécimal) pour un message "b'message data'"
avec la clé "b'pseudorandom key'" :

   >>> from hashlib import blake2b
   >>> h = blake2b(key=b'pseudorandom key', digest_size=16)
   >>> h.update(b'message data')
   >>> h.hexdigest()
   '3d363ff7401e02026f4a4687d4863ced'

Comme exemple pratique, une application web peut chiffrer
symétriquement les *cookies* envoyés aux utilisateurs et les vérifier
plus tard pour être certaine qu'ils n'ont pas été altérés :

   >>> 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(digest_size=AUTH_SIZE, key=SECRET_KEY)
   ...     h.update(cookie)
   ...     return h.hexdigest().encode('utf-8')
   >>>
   >>> def verify(cookie, sig):
   ...     good_sig = sign(cookie)
   ...     return compare_digest(good_sig, sig)
   >>>
   >>> cookie = b'user-alice'
   >>> sig = sign(cookie)
   >>> print("{0},{1}".format(cookie.decode('utf-8'), sig))
   user-alice,b'43b3c982cf697e0c5ab22172d1ca7421'
   >>> verify(cookie, sig)
   True
   >>> verify(b'user-bob', sig)
   False
   >>> verify(cookie, b'0102030405060708090a0b0c0d0e0f00')
   False

Même s'il possède en natif la création de code d'authentification de
message (MAC), BLAKE2 peut, bien sûr, être utilisé pour construire un
HMAC en combinaison avec le module "hmac" :

   >>> import hmac, hashlib
   >>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)
   >>> m.update(b'message')
   >>> m.hexdigest()
   'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'


Hachage randomisé
~~~~~~~~~~~~~~~~~

En définissant le paramètre *salt* les utilisateurs peuvent introduire
de l'aléatoire dans la fonction de hachage. Le hachage randomisé est
utile pour se protéger des attaques par collisions sur les fonctions
de hachage utilisées dans les signatures numériques.

   Le hachage aléatoire est conçu pour les situations où une partie,
   le préparateur du message, génère tout ou partie d'un message à
   signer par une seconde partie, le signataire du message. Si le
   préparateur du message est capable de trouver des collisions sur la
   fonction cryptographique de hachage (c.-à-d. deux messages
   produisant la même valeur une fois hachés), alors il peut préparer
   plusieurs versions du message, ayant un sens, qui produiront les
   mêmes empreintes et même signature mais avec des résultats
   différents (par exemple transférer 1 000 000 $ sur un compte plutôt
   que 10 $). Les fonctions cryptographiques de hachage ont été
   conçues avec comme but premier de résister aux collisions, mais la
   concentration actuelle d'attaques sur les fonctions de hachage peut
   avoir pour conséquence qu'une fonction de hachage donnée soit moins
   résistante qu'attendu. Le hachage aléatoire offre au signataire une
   protection supplémentaire en réduisant la probabilité que le
   préparateur puisse générer deux messages ou plus qui renverront la
   même empreinte lors du processus de génération de la signature —
   même s'il existe un moyen pratique de trouver des collisions sur la
   fonction de hachage. Toutefois, l'utilisation du hachage aléatoire
   peut réduire le niveau de sécurité fourni par une signature
   numérique si  tous les morceaux du message sont préparés par le
   signataire.

   (NIST SP-800-106 "Randomized Hashing for Digital Signatures")

Dans BLAKE2, le sel est passé une seule fois lors de l'initialisation
de la fonction de hachage, plutôt qu'à chaque appel de la fonction de
hachage.

Avertissement:

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


Personnalisation
~~~~~~~~~~~~~~~~

Parfois il est utile de forcer une fonction de hachage à produire
différentes empreintes de message d'une même entrée pour différentes
utilisations. Pour citer les auteurs de la fonction de hachage Skein :

   Nous recommandons que tous les développeurs d'application
   considèrent sérieusement de faire cela ; nous avons vu de nombreux
   protocoles où une empreinte était calculée à un endroit du
   protocole pour être utilisée à un autre endroit car deux calculs
   d'empreintes étaient réalisés sur des données similaires ou liées,
   et qu'un attaquant peut forcer une application à prendre en entrée
   la même empreinte. Personnaliser chaque fonction de hachage
   utilisée dans le protocole stoppe immédiatement ce genre d'attaque.

   (The Skein Hash Function Family, p. 21, article en anglais)

BLAKE2 peut être personnalisé en passant des *bytes* à l'argument
*person* :

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

La personnalisation et le *keyed mode* peuvent être utilisés ensemble
pour dériver différentes clés à partir d'une seule.

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


Mode Arbre
~~~~~~~~~~

L'exemple ci-dessous présente comment hacher un arbre minimal avec
deux nœuds terminaux :

     10
    /  \
   00  01

Cet exemple utilise en interne des empreintes de 64 octets, et produit
finalement des empreintes 32 octets :

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


Crédits
-------

BLAKE2 a été conçu par *Jean-Philippe Aumasson*, *Samuel Neves*,
*Zooko Wilcox-O'Hearn*, et *Christian Winnerlein*. Il est basé la
version BLAKE qui a participé à la finale de la compétition du NIST
SHA-3 créée par *Jean-Philippe Aumasson*, *Luca Henzen*, *Willi
Meier*, et *Raphael C.-W. Phan*.

Il utilise le cœur de l'algorithme de chiffrement de ChaCha conçu par
*Daniel J.  Bernstein*.

L'implémentation dans la bibliothèque standard est basée sur le module
pyblake2. Elle a été écrite par *Dmitry Chestnykh* et est basée sur
l'implémentation C écrite par *Samuel Neves*. La documentation a été
copiée depuis pyblake2 et écrite par *Dmitry Chestnykh*.

Le code C a été partiellement réécrit pour Python par *Christian
Heimes*.

Le transfert dans le domaine public s'applique pour l'implémentation C
de la fonction de hachage, ses extensions et cette documentation :

   Tout en restant dans les limites de la loi, le(s) auteur(s) a (ont)
   donné tous les droits d’auteur et droits connexes et voisins de ce
   logiciel au domaine public dans le monde entier. Ce logiciel est
   distribué sans aucune garantie.

   Vous devriez recevoir avec ce logiciel une copie de la licence *CC0
   Public Domain Dedication*. Sinon, voir
   https://creativecommons.org/publicdomain/zero/1.0/.

Les personnes suivantes ont aidé au développement ou contribué aux
modifications du projet et au domaine public selon la licence Creative
Commons Public Domain Dedication 1.0 Universal :

* *Alexandr Sokolovskiy*

Voir aussi:

  Module "hmac"
     Un module pour générer des codes d'authentification utilisant des
     *hash*.

  Module "base64"
     Un autre moyen d'encoder des *hash* binaires dans des
     environnements non binaires.

  https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.180-4.pdf
     The FIPS 180-4 publication on Secure Hash Algorithms.

  https://csrc.nist.gov/publications/detail/fips/202/final
     The FIPS 202 publication on the SHA-3 Standard.

  https://www.blake2.net/
     Site officiel de BLAKE2.

  https://en.wikipedia.org/wiki/Cryptographic_hash_function
     Article Wikipedia contenant les informations relatives aux
     algorithmes ayant des problèmes et leur interprétation au regard
     de leur utilisation.

  https://www.ietf.org/rfc/rfc8018.txt
     PKCS #5 : Password-Based Cryptography Specification Version 2.1

  https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication8
  00-132.pdf
     Recommandations du NIST pour la dérivation de clé à partir de mot
     de passe (ressource en anglais).
