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

hmac.digest(key, msg, digest)

Возвращает дайджест msg для заданного секретного ключ и 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.