hashlib — Защищённые хэши и дайджесты сообщений

Алгоритмы хэширования

Для каждого типа хэша существует один конструктор. Все возвращают объект хэша с одинаковым простым интерфейсом. Например, используйте sha256() для создания объекта хэша SHA-256. Теперь вы можете передавать этому объекту объекты, подобные байтам (обычно bytes) с помощью метода update. В любой момент вы можете запросить дайджест конкатенации данных, переданных ему до сих пор, с помощью методов digest() или hexdigest().

Для поддержки многопоточности интерпретатор Python GIL освобождается при вычислении хэша, если в конструктор или метод .update передано более 2047 байт данных за раз.

Конструкторы алгоритмов хэширования, которые всегда присутствуют в этом модуле, — это sha1(), sha224(), sha256(), sha384(), sha512(), sha3_224(), sha3_256(), sha3_384(), sha3_512(), shake_128(), shake_256(), blake2b() и blake2s(). md5() обычно также доступен, хотя он может отсутствовать или быть заблокирован, если вы используете редкую «совместимую с FIPS» сборку Python. Они соответствуют algorithms_guaranteed.

Дополнительные алгоритмы могут быть доступны, если дистрибутив Python был скомпилирован с OpenSSL, который предоставляет другие. Другие не гарантируются на всех установках и будут доступны только по имени через new(). См. algorithms_available.

Использование

Чтобы получить дайджест байтовой строки b"Nobody inspects the spammish repetition":

>>> import hashlib
>>> m = hashlib.sha256()
>>> m.update(b"Nobody inspects")
>>> m.update(b" the spammish repetition")
>>> m.digest()
b'\x03\x1e\xdd}Ae\x15\x93\xc5\xfe\\\x00o\xa5u+7\xfd\xdf\xf7\xbcN\x84:\xa6\xaf\x0c\x95\x0fK\x94\x06'
>>> m.hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'

Более компактный вариант:

>>> hashlib.sha256(b"Nobody inspects the spammish repetition").hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'

Конструкторы

hashlib.new(name, [data, ]*, usedforsecurity=True)

Является универсальным конструктором, который принимает строку имени желаемого алгоритма в качестве первого параметра. Он также используется для доступа к вышеперечисленным хэшам, а также к любым другим алгоритмам, которые может предложить ваша библиотека OpenSSL.

Использование new() с именем алгоритма:

>>> h = hashlib.new('sha256')
>>> h.update(b"Nobody inspects the spammish repetition")
>>> h.hexdigest()
'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'

hashlib.md5([data, ]*, usedforsecurity=True)

hashlib.sha1([data, ]*, usedforsecurity=True)

hashlib.sha224([data, ]*, usedforsecurity=True)

hashlib.sha256([data, ]*, usedforsecurity=True)

hashlib.sha384([data, ]*, usedforsecurity=True)

hashlib.sha512([data, ]*, usedforsecurity=True)

hashlib.sha3_224([data, ]*, usedforsecurity=True)

hashlib.sha3_256([data, ]*, usedforsecurity=True)

hashlib.sha3_384([data, ]*, usedforsecurity=True)

hashlib.sha3_512([data, ]*, usedforsecurity=True)

Именованные конструкторы, такие как эти, быстрее, чем передача имени алгоритма в new().

Атрибуты

Hashlib предоставляет следующие постоянные атрибуты модуля:

hashlib.algorithms_guaranteed

Множество, содержащее имена алгоритмов хэширования, гарантированно поддерживаемых этим модулем на всех платформах. Обратите внимание, что «md5» находится в этом списке, несмотря на то, что некоторые поставщики предлагают странную сборку Python «совместимую с FIPS», в которой он отсутствует.

Добавлен в версии 3.2.

hashlib.algorithms_available

Множество, содержащее имена алгоритмов хэширования, доступных в работающей интерпретации Python. Эти имена будут распознаваться при передаче в new(). algorithms_guaranteed всегда будет подмножеством. Один и тот же алгоритм может появляться в этом множестве несколько раз под разными именами (благодаря OpenSSL).

Добавлен в версии 3.2.

Объекты хеширования

Следующие значения предоставляются в качестве постоянных атрибутов объектов хеширования, возвращаемых конструкторами:

hash.digest_size

Размер результирующего хеша в байтах.

hash.block_size

Внутренний размер блока алгоритма хеширования в байтах.

Объект хеширования имеет следующие атрибуты:

hash.name

Каноническое имя этого хеша, всегда в нижнем регистре и всегда подходящее в качестве параметра для new() для создания другого хеша этого типа.

Изменено в версии 3.4: Атрибут name присутствует в CPython с момента его создания, но до Python 3.4 не был формально специфицирован, поэтому может отсутствовать на некоторых платформах.

Объект хеширования имеет следующие методы:

hash.update(data)

Обновить объект хеширования с помощью объекта типа байты. Повторные вызовы эквивалентны одному вызову с конкатенацией всех аргументов: m.update(a); m.update(b) эквивалентно m.update(a+b).

hash.digest()

Возвращает дайджест данных, переданных методу update() до сих пор. Это объект типа байты размером digest_size, который может содержать байты в диапазоне от 0 до 255.

hash.hexdigest()

Аналогично digest(), за исключением того, что дайджест возвращается как строковый объект двойной длины, содержащий только шестнадцатеричные цифры. Это можно использовать для безопасного обмена значениями по электронной почте или в других небинарных средах.

hash.copy()

Возвращает копию («клонирование») объекта хеширования. Это можно использовать для эффективного вычисления дайджестов данных, разделяющих общую начальную подстроку.

SHAKE переменной длины дайджесты

hashlib.shake_128([data, ]*, usedforsecurity=True)

hashlib.shake_256([data, ]*, usedforsecurity=True)

Алгоритмы shake_128() и shake_256() обеспечивают дайджесты переменной длины длиной length_in_bits//2 до 128 или 256 битов безопасности. Таким образом, их методы дайджеста требуют длины. Максимальная длина не ограничена алгоритмом SHAKE.

shake.digest(length)

Возвращает дайджест данных, переданных методу update() до сих пор. Это объект типа байты размером length, который может содержать байты в диапазоне от 0 до 255.

shake.hexdigest(length)

Аналогично digest(), за исключением того, что дайджест возвращается как строковый объект двойной длины, содержащий только шестнадцатеричные цифры. Это можно использовать для обмена значениями по электронной почте или в других небинарных средах.

Пример использования:

>>> h = hashlib.shake_256(b'Nobody inspects the spammish repetition')
>>> h.hexdigest(20)
'44709d6fcb83d92a76dcb0b668c98e1b1d3dafe7'

Хеширование файлов

Модуль hashlib предоставляет вспомогательную функцию для эффективного хеширования файла или объекта типа файл.

hashlib.file_digest(fileobj, digest, /)

Возвращает объект дайджеста, который был обновлён содержимым объекта файла.

fileobj должен быть объектом типа файл, открытым для чтения в двоичном режиме. Он принимает объекты файлов из встроенной функции open(), экземпляров BytesIO, объектов SocketIO из socket.socket.makefile(), и аналогичных. Функция может обойти механизм ввода-вывода Python и использовать дескриптор файла непосредственно из fileno(). fileobj должен предполагаться в неизвестном состоянии после возврата этой функции или повышения исключения. От пользователя зависит закрытие fileobj.

digest должен быть либо именем алгоритма хеширования в виде str, либо конструктором хеширования, либо вызываемым объектом, возвращающим объект хеширования.

Пример:

>>> import io, hashlib, hmac
>>> with open(hashlib.__file__, "rb") as f:
...     digest = hashlib.file_digest(f, "sha256")
...
>>> digest.hexdigest()  
'...'

>>> buf = io.BytesIO(b"somedata")
>>> mac1 = hmac.HMAC(b"key", digestmod=hashlib.sha512)
>>> digest = hashlib.file_digest(buf, lambda: mac1)

>>> digest is mac1
True
>>> mac2 = hmac.HMAC(b"key", b"somedata", digestmod=hashlib.sha512)
>>> mac1.digest() == mac2.digest()
True

Добавлена в версии 3.11.

Вычисление ключей

Алгоритмы вычисления ключей и расширения ключей предназначены для безопасного хеширования паролей. Примитивные алгоритмы, такие как sha1(password) не устойчивы к атакам грубой силы. Хорошая функция хеширования паролей должна быть настраиваемой, медленной и включать соль.

hashlib.pbkdf2_hmac(hash_name, password, salt, iterations, dklen=None)

Функция предоставляет функцию вывода ключей на основе пароля PKCS#5 2. Она использует HMAC в качестве псевдослучайной функции.

Строка hash_name — это желаемое имя алгоритма хеширования дайджеста для HMAC, например, ‘sha1’ или ‘sha256’. password и salt интерпретируются как буферы байтов. Приложения и библиотеки должны ограничивать password разумной длиной (например, 1024). salt должен быть примерно 16 или более байтами из надёжного источника, например, os.urandom().

Число iterations должно выбираться на основе алгоритма хеширования и вычислительной мощности. По состоянию на 2022 год рекомендуется использовать сотни тысяч итераций SHA-256. Для обоснования того, почему и как выбрать то, что лучше всего подходит для вашего приложения, прочитайте приложение A.2.2 в NIST-SP-800-132. Ответы на вопрос о итерациях pbkdf2 на stackexchange подробно объясняют это.

dklen — это длина выведенного ключа в байтах. Если dklen None то используется размер дайджеста алгоритма хеширования hash_name, например, 64 для SHA-512.

>>> from hashlib import pbkdf2_hmac
>>> our_app_iters = 500_000  # Application specific, read above.
>>> dk = pbkdf2_hmac('sha256', b'password', b'bad salt' * 2, our_app_iters)
>>> dk.hex()
'15530bba69924174860db778f2c6f8104d3aaf9d26241840c8c4a641c8d000a9'

Функция доступна только при компиляции Python с OpenSSL.

Добавлена в версии 3.4.

Изменено в версии 3.12: Функция теперь доступна только при компиляции Python с OpenSSL. Медленная реализация на чистом Python была удалена.

hashlib.scrypt(password, *, salt, n, r, p, maxmem=0, dklen=64)

Функция предоставляет функцию вывода ключей scrypt, как определено в RFC 7914.

password и salt должны быть объектами типа байты. Приложения и библиотеки должны ограничивать password разумной длиной (например, 1024). salt должен быть примерно 16 или более байтами из надёжного источника, например, os.urandom().

n — фактор стоимости ЦП/памяти, r — размер блока, p — фактор распараллеливания, а maxmem — ограничение памяти (по умолчанию OpenSSL 1.1.0 составляет 32 МБ). dklen — это длина выведенного ключа в байтах.

Добавлена в версии 3.6.

BLAKE2

BLAKE2 — это криптографическая хеш-функция, определённая в RFC 7693, которая представлена в двух вариантах:

• BLAKE2b, оптимизированная для 64-битных платформ и генерирующая дайджесты любого размера от 1 до 64 байт,
• BLAKE2s, оптимизированная для 8- до 32-битных платформ и генерирующая дайджесты любого размера от 1 до 32 байт.

BLAKE2 поддерживает режим с ключом (более быстрая и простая замена для HMAC), солёное хеширование, персонализацию и хеширование дерева.

Объекты хешей из этого модуля следуют API объектов стандартной библиотеки hashlib.

Создание объектов хеша

Новые объекты хешей создаются путём вызова конструкторских функций:

hashlib.blake2b(data=b'', *, digest_size=64, key=b'', salt=b'', person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, node_depth=0, inner_size=0, last_node=False, usedforsecurity=True)

hashlib.blake2s(data=b'', *, digest_size=32, key=b'', salt=b'', person=b'', fanout=1, depth=1, leaf_size=0, node_offset=0, node_depth=0, inner_size=0, last_node=False, usedforsecurity=True)

Эти функции возвращают соответствующие объекты хешей для вычисления BLAKE2b или BLAKE2s. Они необязательно принимают следующие общие параметры:

• data: начальный фрагмент данных для хеширования, который должен быть объектом типа байты. Он может передаваться только как позиционный аргумент.
• digest_size: размер дайджеста на выходе в байтах.
• key: ключ для хеширования с ключом (до 64 байт для BLAKE2b, до 32 байт для BLAKE2s).
• salt: соль для случайного хеширования (до 16 байт для BLAKE2b, до 8 байт для BLAKE2s).
• person: строка персонализации (до 16 байт для BLAKE2b, до 8 байт для BLAKE2s).

В следующей таблице показаны ограничения для общих параметров (в байтах):

Хеш	digest_size	len(key)	len(salt)	len(person)
BLAKE2b	64	64	16	16
BLAKE2s	32	32	8	8

Примечание

Спецификация BLAKE2 определяет постоянные длины для параметров salt и personalization, однако, для удобства, эта реализация принимает байтовые строки любого размера до указанной длины. Если длина параметра меньше указанной, она заполняется нулями, таким образом, например, b'salt' и b'salt\x00' имеют одинаковое значение. (Это не относится к key.)

Эти размеры доступны как модульные константы, описанные ниже.

Функции-конструкторы также принимают следующие параметры хеширования дерева:

• fanout: фаноут (от 0 до 255, 0 если без ограничений, 1 в последовательном режиме).
• depth: максимальная глубина дерева (от 1 до 255, 255 если без ограничений, 1 в последовательном режиме).
• leaf_size: максимальная длина листа в байтах (от 0 до 2**32-1, 0 если без ограничений или в последовательном режиме).
• node_offset: смещение узла (от 0 до 2**64-1 для BLAKE2b, от 0 до 2**48-1 для BLAKE2s, 0 для первого, крайнего левого, листа или в последовательном режиме).
• node_depth: глубина узла (от 0 до 255, 0 для листьев или в последовательном режиме).
• inner_size: размер внутреннего дайджеста (от 0 до 64 для BLAKE2b, от 0 до 32 для BLAKE2s, 0 в последовательном режиме).
• last_node: булево значение, указывающее, является ли обработанный узел последним (False для последовательного режима).

См. раздел 2.10 в спецификации BLAKE2 для подробного обзора хеширования дерева.