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

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

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

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

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

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

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

hmac.digest(key, msg, digest)

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

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

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

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

HMAC.update(msg)

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

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

HMAC.digest()

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

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

При сравнении результата 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-подобный.

Примечание

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

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

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