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.