hmac – хэширование с ключом для аутентификации сообщений¶hmac – Keyed-Hashing for Message Authentication

Исходный код: 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 для заданных секретного ключа и дайджеста. Эта функция эквивалентна 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 байты, включая нулевые байты.

Предупреждение

При сравнении вывода 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 при наличии.