hmac — Authentification de messages par hachage en combinaison avec une clé secrète

Code source : Lib/hmac.py

Ce module implémente l'algorithme HMAC tel que décrit par la RFC 2104.

hmac.new(key, msg=None, digestmod=None)

Return a new hmac object. key is a bytes or bytearray object giving the secret key. If msg is present, the method call update(msg) is made. digestmod is the digest name, digest constructor or module for the HMAC object to use. It supports any name suitable to hashlib.new() and defaults to the hashlib.md5 constructor.

Modifié dans la version 3.4: Le paramètre key peut être un byte ou un objet bytearray. Le paramètre msg peut être de n'importe quel type pris en charge par hashlib. Le paramètre digestmod peut être le nom d'un algorithme de hachage.

Deprecated since version 3.4, will be removed in version 3.8: MD5 as implicit default digest for digestmod is deprecated.

hmac.digest(key, msg, digest)

Renvoie le code d'authentification de msg, pour la clé secrète key et à l'algorithme digest donné. La fonction est équivalente à HMAC(key, msg, digest).digest(), mais elle utilise une implémentation optimisée en C ou inline, qui est plus rapide pour les messages dont la taille leur permet de tenir en mémoire vive. Les paramètres key, msg et digest ont la même signification que pour new().

Détail d'implémentation CPython, l'implémentation C optimisée n'est utilisée que lorsque le digest est une chaîne de caractères et le nom d'un algorithme de hachage implémenté dans OpenSSL.

Nouveau dans la version 3.7.

Un objet HMAC a les méthodes suivantes :

HMAC.update(msg)

Met à jour l'objet HMAC avec msg. Des appels répétés sont équivalents à un seul 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.4: Le paramètre msg peut être de n'importe quel type géré par hashlib.

HMAC.digest()

Renvoie le condensat des octets passés à la méthode update() jusque là. L'objet bytes renvoyé sera de la même longueur que la digest_size de la fonction de hachage donnée au constructeur. Il peut contenir des octets qui ne sont pas dans la table ASCII, y compris des octets NUL.

Avertissement

Si vous devez vérifier la sortie de digest() avec un condensat obtenu par ailleurs par un service extérieur durant une routine de vérification, il est recommandé d'utiliser la fonction compare_digest() au lieu de l'opérateur == afin de réduire la vulnérabilité aux attaques temporelles.

HMAC.hexdigest()

Comme digest() sauf que ce condensat est renvoyé en tant que chaîne de caractères de taille doublée contenant seulement des chiffres hexadécimaux. Cela permet d’échanger le résultat sans problèmes par e-mail ou dans d'autres environnements ne gérant pas les données binaires.

Avertissement

Si l'on compare la sortie de hexdigest() avec celle d'un condensat connu obtenu par un service extérieur durant une routine de vérification, il est recommandé d'utiliser la fonction compare_digest() au lieu de l'opérateur == afin de réduire la vulnérabilité aux attaques basées sur les temps de réponse.

HMAC.copy()

Renvoie une copie (un clone) de l'objet HMAC. C'est utile pour calculer de manière efficace les empreintes cryptographiques de chaînes de caractères qui ont en commun une sous-chaîne initiale.

Un objet code d'authentification de message (HMAC) possède les attributs suivants :

HMAC.digest_size

La taille du code d'authentification (c-à-d de l'empreinte cryptographique) en octets.

HMAC.block_size

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

Nouveau dans la version 3.4.

HMAC.name

Le nom canonique de ce HMAC, toujours en lettres minuscules, par exemple hmac-md5.

Nouveau dans la version 3.4.

Ce module fournit également la fonction utilitaire suivante :

hmac.compare_digest(a, b)

Renvoie a == b. Cette fonction a été conçue pour prévenir les attaques temporelles en évitant l'implémentation de courts-circuits basés sur le contenu, ce qui la rend appropriée pour de la cryptographie. a et b doivent être du même type : soit str (caractères ASCII seulement, comme retourné par HMAC.hexdigest() par exemple), ou bytes-like object.

Note

Si a et b sont de longueurs différentes ou si une erreur se produit, une attaque temporelle pourrait en théorie obtenir des informations sur les types et longueurs de a et de b, mais pas sur leurs valeurs.

Nouveau dans la version 3.3.

Voir aussi

Module hashlib

Le module Python fournissant des fonctions de hachage sécurisé.