hmac — Código de autenticação de mensagem com chave hash

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.

Alterado na versão 3.8: O argumento digestmod agora é obrigatório. Passe-o como um argumento nomeado para evitar constrangimentos quando você não tiver uma msg inicial.

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.

Adicionado 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.

Adicionado na versão 3.4.

HMAC.name

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

Adicionado na versão 3.4.

Alterado na versão 3.10: Foram removidos os atributos não documentados HMAC.digest_cons, HMAC.inner e HMAC.outer.

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.

Adicionado 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.