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)

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

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