# `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 hash algorithms. Included are the FIPS secure hash algorithms SHA224, SHA256, SHA384, SHA512, (defined in the FIPS 180-4 standard), the SHA-3 series (defined in the FIPS 202 standard) as well as the legacy algorithms SHA1 (formerly part of FIPS) and the MD5 algorithm (defined in internet RFC 1321).

Note

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

## Algorithmes de hachage

Il y a un constructeur nommé selon chaque type de calcul d'empreinte (hash). Tous renvoient un objet haché avec la même interface. Par exemple : utilisez `sha256()` pour créer un objet de calcul d'empreinte avec l'algorithme SHA-256. Vous pouvez maintenant utiliser cet objet avec des objets octets-compatibles (normalement des `bytes`) en utilisant la méthode `update`. À tout moment vous pouvez demander l'empreinte (aussi appelée le digest ou le condensat) de la concaténation des données fournies en utilisant les méthodes `digest()` ou `hexdigest()`.

pour de meilleures performances avec de multiples fils d'exécution, le GIL Python est relâché pour des données dont la taille est supérieure à 2047 octets lors de leur création ou leur mise à jour (méthode `.update`.).

Les constructeurs pour les algorithmes de hachage qui sont toujours présents dans ce module sont `sha1()`, `sha224()`, `sha256()`, `sha384()`, `sha512()`, `sha3_224()`, `sha3_256()`, `sha3_384()`, `sha3_512()`, `shake_128()`, `shake_256()`, `blake2b()`, et `blake2s()`. `md5()` est normalement disponible aussi, mais il peut être manquant ou bloqué si vous utilisez une forme rare de Python « conforme FIPS ». Cette liste correspond au résultat de la fonction `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

Certains algorithmes ont des faiblesses connues relatives à la collision (MD5 et SHA1 inclus). Se référer à Fonction de hachage cryptographique et à la section Voir aussi à la fin du document.

Ajouté dans la version 3.6: les constructeurs SHA3 (Keccak) et SHAKE `sha3_224()`, `sha3_256()`, `sha3_384()`, `sha3_512()`, `shake_128()`, `shake_256()` ont été ajoutés. `blake2b()` et `blake2s()` ont été ajoutés.

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 utilise désormais SHA3 et SHAKE d'OpenSSL s'il les fournit.

Modifié dans la version 3.12: For any of the MD5, SHA1, SHA2, or SHA3 algorithms that the linked OpenSSL does not provide we fall back to a verified implementation from the HACL* project.

## Utilisation

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'

## Constructeurs

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 fournit les constantes de module suivantes :

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.

  Ajouté 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).

  Ajouté dans la version 3.2.

## Objets de calcul d'empreinte

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

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)

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

shake.hexdigest(length)

  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.

Exemple :

    >>> 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 must be a file-like object opened for reading in binary mode. It accepts file objects from builtin `open()`, `BytesIO` instances, SocketIO objects from `socket.socket.makefile()`, and similar. fileobj must be opened in blocking mode, otherwise a `BlockingIOError` may be raised.

  The function may bypass Python's I/O and use the file descriptor from `fileno()` directly. fileobj must be assumed to be in an unknown state after this function returns or raises. It is up to the caller to close 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("library/hashlib.rst", "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

  Ajouté dans la version 3.11.

  Modifié dans la version 3.13.4: Now raises a `BlockingIOError` if the file is opened in blocking mode. Previously, spurious null bytes were added to the digest.

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

  Function only available when Python is compiled with OpenSSL.

  Ajouté dans la version 3.4.

  Modifié dans la version 3.12: Function now only available when Python is built with OpenSSL. The slow pure Python implementation has been removed.

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

  Ajouté 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).

Voir la section 2.10 dans BLAKE2 specification pour une approche globale du hachage en mode arbre.

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

Pour calculer l'empreinte (ou hash) d'une quantité de données, vous devez d'abord construire un objet de calcul d'empreinte en appelant la fonction constructeur appropriée (`blake2b()` or `blake2s()`), ensuite le mettre à jour avec les données en appelant la méthode `update()` sur l'objet, et, pour finir, récupérer l'empreinte du message en appelant la méthode `digest()` (ou `hexdigest()` pour les chaînes hexadécimales).

    >>> 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", article en anglais)

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 (ou un hachage simple) avec BLAKE2 ou toute autre fonction de hachage générique, comme SHA-256, ne convient pas pour obscurcir des mots de passe. Voir la FAQ BLAKE2 (page en anglais) pour plus d'informations.

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

  La publication FIPS 180-4 sur les algorithmes de hachage sécurisés.

https://csrc.nist.gov/pubs/fips/202/final

  La publication FIPS 202 sur le standard SHA-3.

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/nistspecialpublication800-132.pdf

  Recommandations du NIST pour la dérivation de clé à partir de mot de passe (ressource en anglais).