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

Исходный код: Lib/hmac.py

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

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

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

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

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

hmac.digest(key, msg, digest)¶

Возвращает дайджест msg для заданного секретного ключа и дайджест. Функция эквивалентна HMAC(key, msg, digest).digest(), но использует оптимизированную реализацию на языке Си или встроенную реализацию, которая работает быстрее для сообщений, которые помещаются в память. Параметры 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: Функция использует Openssl CRYPTO_memcmp() внутренне, когда это доступно.