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

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

Этот модуль реализует алгоритм HMAC, описанный в RFC 2104. Интерфейс позволяет использовать любую хеш-функцию с фиксированным размером дайджеста. В частности, функции с расширяемым выходом, такие как SHAKE-128 или SHAKE-256, нельзя использовать с HMAC.

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 теперь обязателен. Передавайте его как именованный аргумент, чтобы избежать неудобств, если начальное значение msg отсутствует.

hmac.digest(key, msg, digest)

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

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

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

class hmac.HMAC

Объект 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, включая нулевые байты.

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

При сравнении результата 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().