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 теперь обязателен. Передавайте его в качестве именованного аргумента, чтобы избежать неудобств, когда у вас нет начального 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.10: Функция использует внутренне CRYPTO_memcmp() OpenSSL, когда она доступна.