# `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='')

  Renvoie un nouvel objet HMAC. key est un objet byte ou bytearray représentant la clé secrète. Si msg est présent, un appel à `update(msg)` est effectué. digestmod permet de choisir l’algorithme à utiliser par l’objet HMAC, il accepte un nom de fonction de hachage (peut être tout ce qui convient à `hashlib.new()`), un constructeur de fonction de hachage ou un module implémentant la PEP 247. Bien qu’il soit après msg, digestmod est un paramètre obligatoire.

  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, removed in version 3.8: MD5 en tant qu’algorithme cryptographique par défaut implicite pour digestmod est obsolète. Le paramètre digestmod est maintenant requis. Passez-le en argument nommé pour éviter la bizarrerie que ça donnerait quand vous n'avez pas un msg initial.

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

Obsolète depuis la version 3.9: Les attributs `HMAC.digest_cons`, `HMAC.inner` et `HMAC.outer` (non documentés) sont des détails d'implémentation internes et seront supprimés en Python 3.10.

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.

  Modifié dans la version 3.9: Cette fonction utilise la fonction `CRYPTO_memcmp()` de OpenSSL quand celle-ci est disponible.

Voir aussi

Module `hashlib`

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