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 может быть именем алгоритма хэширования.

Deprecated since version 3.4, removed in version 3.8: MD5 как неявный дайджест по умолчанию для digestmod устарел. Теперь параметр digestmod является обязательным. Передавайте его как аргумент ключевого слова, чтобы избежать неловкости, когда у вас нет начального msg.

hmac.digest(key, msg, digest)¶

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

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

Добавлено в версии 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¶

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

Добавлено в версии 3.4.

HMAC.name¶

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

Добавлено в версии 3.4.

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

hmac.compare_digest(a, b)¶

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

Примечание

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

Добавлено в версии 3.3.

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