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: MD5 как неявное значение по умолчанию для digestmod устарело.

Объект 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.