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.4, удалено в версии 3.8: MD5 как неявный по умолчанию digest для digestmod устарел. Параметр 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.

Объект 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()), либо объект, похожий на байты.

Примечание

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

Введено в версии 3.3.

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