hmac — Hash con clave para autenticación de mensajes

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.

Deprecated since version 3.4, removed in version 3.8: MD5 como resumen por defecto implícito para digestmod está obsoleto. Ahora se requiere el parámetro digestmod. Páselo como un argumento de palabra clave para evitar dificultades cuando no tiene un msg inicial.

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.

Nuevo en la versión 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.

Nuevo en la versión 3.4.

HMAC.name

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

Nuevo en la versión 3.4.

Obsoleto desde la versión 3.9: Los atributos no documentados HMAC.digest_cons, HMAC.inner y HMAC.outer son detalles de implementación interna y se eliminarán en Python 3.10.

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.

Nuevo en la versión 3.3.

Distinto en la versión 3.9: 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.