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

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

Этот модуль реализует алгоритм HMAC, как описано в RFC 2104.

hmac.new(key, msg=None, digestmod=None)

Возвращает новый объект hmac. key — это объект bytes или bytearray, содержащий секретный ключ. Если msg присутствует, выполняется вызов update(msg). digestmod — это имя дайджеста, конструктор дайджеста или модуль для объекта HMAC. Он поддерживает любые имена, подходящие для hashlib.new(), и по умолчанию использует конструктор hashlib.md5.

Изменено в версии 3.4: Параметр key может быть объектом bytes или bytearray. Параметр msg может быть любого типа, поддерживаемого hashlib. Параметр digestmod может быть именем алгоритма хеширования.

Устарело начиная с версии 3.4, будет удалено в версии 3.8: MD5 как неявный по умолчанию дайджест для digestmod устарел.

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.