hmac — Хеширование ключей для аутентификации сообщений

Источник: Lib/hmac.py

Этот модуль реализует алгоритм HMAC, описанный в RFC 2104.

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

Возвращает новый объект hmac. key - объект в виде байта или байтового массива, задающий секретный ключ. Если присутствует msg, выполняется вызов метода update(msg). digestmod - имя дайджеста, конструктора дайджеста или модуля, который будет использоваться для объекта HMAC. Это может быть любое имя, подходящее для hashlib.new(). Несмотря на положение аргумента, он является обязательным.

Изменено в версии 3.4: Параметр key может быть объектом типа bytes или bytearray. Параметр msg может быть любого типа, поддерживаемого hashlib. Параметр digestmod может быть именем хэш-алгоритма.

Изменено в версии 3.8: Аргумент digestmod теперь является обязательным. Передавайте его как аргумент ключевого слова, чтобы избежать неловкости, когда у вас нет начального msg.

hmac.digest(key, msg, digest)

Возвращает дайджест msg для заданных секретного ключа и дайджеста. Функция эквивалентна HMAC(key, msg, digest).digest(), но использует оптимизированную реализацию на C или inline, что быстрее для сообщений, помещающихся в памяти. Параметры key, msg и digest имеют то же значение, что и в new().

Детали реализации CPython, оптимизированная реализация C используется только в том случае, если digest - это строка и имя алгоритма дайджеста, который поддерживается OpenSSL.

Added in version 3.7.

Объект HMAC имеет следующие методы:

HMAC.update(msg)

Обновление объекта hmac с помощью msg. Повторные вызовы эквивалентны одному вызову с конкатенацией всех аргументов: m.update(a); m.update(b) эквивалентен m.update(a + b).

Изменено в версии 3.4: Параметр msg может быть любого типа, поддерживаемого hashlib.

HMAC.digest()

Возвращает дайджест байтов, переданных в метод update() к настоящему моменту. Этот объект bytes будет той же длины, что и digest_size дайджеста, переданного конструктору. Он может содержать байты, отличные от ASCII, включая байты NUL.

Предупреждение

При сравнении вывода digest() с внешним дайджестом в ходе процедуры верификации рекомендуется использовать функцию compare_digest() вместо оператора ==, чтобы уменьшить уязвимость к атакам по времени.

HMAC.hexdigest()

Аналогично digest(), только дайджест возвращается в виде строки вдвое большей длины, содержащей только шестнадцатеричные цифры. Это можно использовать для безопасного обмена значениями в электронной почте или других недвоичных средах.

Предупреждение

При сравнении вывода hexdigest() с внешним дайджестом в ходе процедуры верификации рекомендуется использовать функцию compare_digest() вместо оператора ==, чтобы уменьшить уязвимость к атакам по времени.

HMAC.copy()

Возвращает копию («клон») объекта hmac. Это может быть использовано для эффективного вычисления дайджестов строк, имеющих общую начальную подстроку.

Объект хэша имеет следующие атрибуты:

HMAC.digest_size

Размер результирующего HMAC-дайджеста в байтах.

HMAC.block_size

Размер внутреннего блока хэш-алгоритма в байтах.

Added in version 3.4.

HMAC.name

Каноническое имя этого HMAC, всегда в нижнем регистре, например hmac-md5.

Added in version 3.4.

Изменено в версии 3.10: Удалены недокументированные атрибуты HMAC.digest_cons, HMAC.inner и HMAC.outer.

Этот модуль также предоставляет следующую вспомогательную функцию:

hmac.compare_digest(a, b)

Возврат a == b. В этой функции используется подход, направленный на предотвращение анализа временных интервалов путем исключения поведения замыкания на основе содержимого, что делает ее подходящей для криптографии. a и b должны быть одного типа: либо str (только ASCII, как, например, возвращает HMAC.hexdigest()), либо bytes-like object.

Примечание

Если a и b имеют разную длину или произошла ошибка, атака по времени теоретически может раскрыть информацию о типах и длинах a и b, но не об их значениях.

Added in version 3.3.

Изменено в версии 3.10: Функция использует внутренний CRYPTO_memcmp() OpenSSL, если он доступен.

См.также

Модуль hashlib

Модуль Python, обеспечивающий безопасные хэш-функции.