"hmac" --- Keyed-Hashing for Message Authentication
***************************************************

**Código fuente:** Lib/hmac.py

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

Este módulo implementa el algoritmo HMAC como se describe en la **RFC
2104**.

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

   Retorna un nuevo objeto hmac. *key* es un objeto *bytes* o
   *bytearray* que proporciona la clave secreta. Si *msg* está
   presente, se realiza la llamada al método "update(msg)".
   *digestmod* es el nombre del resumen, constructor o módulo del
   resumen para el objeto HMAC que se va a usar. Puede ser cualquier
   nombre adecuado para "hashlib.new()". Se requiere este argumento a
   pesar de su posición.

   Distinto en la versión 3.4: El parámetro *key* puede ser un objeto
   *bytes* o *bytearray*. El parámetro *msg* puede ser de cualquier
   tipo soportado por "hashlib". El parámetro *digestmod* puede ser el
   nombre del algoritmo de *hash*.

   Distinto en la versión 3.8: The *digestmod* argument is now
   required.  Pass it as a keyword argument to avoid awkwardness when
   you do not have an initial *msg*.

hmac.digest(key, msg, digest)

   Retorna el resumen de *msg* para una clave *key* secreta y un
   resumen *digest* dados. La función es equivalente a "HMAC(key, msg,
   digest).digest()", pero utiliza una implementación optimizada en C
   o *inline*, que es más rápida para mensajes que caben en memoria.
   Los parámetros *key*, *msg* y *digest* tienen el mismo significado
   que en "new()".

   Un detalle de la implementación de CPython: la implementación
   optimizada en C solo se usa cuando *digest* es una cadena de
   caracteres y el nombre de un algoritmo de resumen, que está
   soportado por OpenSSL.

   Added in version 3.7.

Un objeto HMAC tiene los siguientes métodos:

HMAC.update(msg)

   Actualiza el objeto hmac con *msg*. Las llamadas repetidas
   equivalen a una sola llamada con la concatenación de todos los
   argumentos: "m.update(a); m.update(b)" es equivalente a "m.update(a
   + b)".

   Distinto en la versión 3.4: El parámetro *msg* puede ser de
   cualquier tipo soportado por "hashlib".

HMAC.digest()

   Retorna el resumen de los *bytes* que se pasaron al método
   "update()" hasta el momento. Este objeto *bytes* será de la misma
   longitud que el *digest_size* del resumen que se pasa al
   constructor. Puede contener *bytes* no ASCII, incluyendo *bytes*
   NUL.

   Advertencia:

     Cuando se compara la salida de "digest()" a un resumen provisto
     externamente durante una rutina de verificación, se recomienda
     utilizar la función "compare_digest()" en lugar del operador "=="
     para reducir la vulnerabilidad a ataques de temporización.

HMAC.hexdigest()

   Como "digest()" excepto que el resumen se retorna como una cadena
   de caracteres de dos veces la longitud conteniendo solo dígitos
   hexadecimales. Esto se puede utilizar para intercambiar el valor de
   forma segura en email u otros entornos no binarios.

   Advertencia:

     Cuando se compara la salida de "hexdigest()" a un resumen
     provisto externamente durante una rutina de verificación, se
     recomienda utilizar la función "compare_digest()" en lugar del
     operador "==" para reducir la vulnerabilidad a ataques de
     temporización.

HMAC.copy()

   Retorna una copia ("clon") del objeto hmac. Esto se puede utilizar
   para calcular de forma eficiente los resúmenes de las cadenas de
   caracteres que comparten una subcadena de caracteres inicial común.

Un objeto *hash* tiene los siguientes atributos:

HMAC.digest_size

   El tamaño del resumen HMAC resultante en *bytes*.

HMAC.block_size

   El tamaño de bloque interno del algoritmo de *hash* en *bytes*.

   Added in version 3.4.

HMAC.name

   El nombre canónico de este HMAC, siempre en minúsculas, por ejemplo
   "hmac-md5".

   Added in version 3.4.

Distinto en la versión 3.10: Removed the undocumented attributes
"HMAC.digest_cons", "HMAC.inner", and "HMAC.outer".

Este módulo también provee las siguiente funciones auxiliares:

hmac.compare_digest(a, b)

   Retorna "a == b". Esta función utiliza un enfoque diseñado para
   prevenir el análisis de temporización evitando el comportamiento de
   cortocircuito basado en contenido, haciéndolo adecuado para
   criptografía. *a* y *b* deben ser del mismo tipo: ya sea "str"
   (solo ASCII, como por ejemplo retornado por "HMAC.hexdigest()"), o
   un *objeto tipo binario*.

   Nota:

     Si *a* y *b* son de diferente longitud, o si ocurre un error, un
     ataque de temporización teóricamente podría revelar información
     sobre los tipos y longitudes de *a* y *b*—pero no sus valores.

   Added in version 3.3.

   Distinto en la versión 3.10: La función utiliza "CRYPTO_memcmp()"
   de OpenSSL internamente cuando está disponible.

Ver también:

  Módulo "hashlib"
     El módulo de Python que provee funciones de *hash* seguras.
