hmac — Keyed-Hashing for Message Authentication

Código-fonte: Lib/hmac.py

Este módulo implementa o algoritmo HMAC, abreviação de hash-based message authentication code, conforme descrito por RFC 2104.

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

Retorna um novo objeto hmac. key é um objeto bytes ou bytearray que fornece a chave secreta. Se msg estiver presente, a chamada de método update(msg) é feita. digestmod é o nome do resumo, construtor do resumo ou módulo para o objeto HMAC usar. Pode ser qualquer nome adequado para hashlib.new(). Apesar da posição do argumento, é obrigatório.

Alterado na versão 3.4: O parâmetro key pode ser um objeto bytes ou bytearray. O parâmetro msg pode ser de qualquer tipo suportado por hashlib. O parâmetro digestmod pode ser o nome de um algoritmo hash.

Deprecated since version 3.4, removed in version 3.8: MD5 as implicit default digest for digestmod is deprecated. The digestmod parameter 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 o resumo de msg para o segredo key e digest fornecidos. A função equivale a HMAC(key, msg, digest).digest(), mas usa uma implementação C otimizada ou inline, que é mais rápida para mensagens que cabem na memória. Os parâmetros key, msg e digest têm o mesmo significado que em new().

Detalhe da implementação do CPython: a implementação otimizada do C é usada somente quando digest é uma string e o nome de um algoritmo de resumo, que é suportado pelo OpenSSL.

Novo na versão 3.7.

Um objeto HMAC tem os seguintes métodos:

HMAC.update(msg)

Atualiza o objeto hmac com msg. Chamadas repetidas são equivalentes a uma única chamada com a concatenação de todos os argumentos: m.update(a); m.update(b) equivale a m.update(a + b).

Alterado na versão 3.4: O parâmetro msg pode ser de qualquer tipo suportado por hashlib.

HMAC.digest()

Retorna o resumo dos bytes passados para o método update() até o momento. Este objeto bytes terá o mesmo comprimento que o digest_size do resumo dado ao construtor. Ele pode conter bytes não-ASCII, incluindo bytes NUL.

Aviso

Ao comparar a saída de digest() com um resumo fornecido externamente durante uma rotina de verificação, é recomendável usar a função compare_digest() em vez do operador == para reduzir a vulnerabilidade a ataques de temporização.

HMAC.hexdigest()

Como digest() exceto que o resumo é retornado como uma string com o dobro do comprimento contendo apenas dígitos hexadecimais. Isso pode ser usado para trocar o valor com segurança em e-mail ou outros ambientes não binários.

Aviso

Ao comparar a saída de hexdigest() com um resumo fornecido externamente durante uma rotina de verificação, é recomendável usar a função compare_digest() em vez do operador == para reduzir a vulnerabilidade a ataques de temporização.

HMAC.copy()

Retorna uma cópia (“clone”) do objeto hmac. Isso pode ser usado para calcular eficientemente os resumos de strings que compartilham uma substring inicial comum.

Um objeto hash tem os seguintes atributos:

HMAC.digest_size

O tamanho do resumo HMAC resultante em bytes.

HMAC.block_size

O tamanho do bloco interna do algoritmo de hash em bytes.

Novo na versão 3.4.

HMAC.name

O nome canônico deste HMAC, sempre em letras minúsculas, por exemplo, hmac-md5.

Novo na versão 3.4.

Obsoleto desde a versão 3.9: The undocumented attributes HMAC.digest_cons, HMAC.inner, and HMAC.outer are internal implementation details and will be removed in Python 3.10.

Este módulo também fornece a seguinte função auxiliar:

hmac.compare_digest(a, b)

Retorna a == b. Esta função usa uma abordagem projetada para evitar análise de tempo evitando comportamento de curto-circuito baseado em conteúdo, tornando-a apropriada para criptografia. a e b devem ser ambos do mesmo tipo: str (somente ASCII, como, por exemplo, retornado por HMAC.hexdigest()), ou um objeto byte ou similar.

Nota

Se a e b tiverem comprimentos diferentes, ou se ocorrer um erro, um ataque de temporização poderia teoricamente revelar informações sobre os tipos e comprimentos de a e b, mas não seus valores.

Novo na versão 3.3.

Alterado na versão 3.10: A função usa CRYPTO_memcmp() do OpenSSL internamente quando disponível.

Ver também

Módulo hashlib

O módulo Python que fornece funções hash seguras.