"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é.
