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» в этом списке, несмотря на то, что некоторые поставщики предлагают странную «FIPS-совместимую» сборку Python, которая его исключает.

В версии 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).

Изменено в версии 3.1: Блокировка интерпретатора Python (GIL) освобождается, чтобы позволить другим потокам выполняться во время обновления хеша для данных размером более 2047 байтов при использовании алгоритмов хеширования, предоставляемых OpenSSL.

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. Ответы на вопрос на stackexchange о итерациях pbkdf2 подробно объясняют это.

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'

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

Примечание

Быстрое реализация pbkdf2_hmac доступно с OpenSSL. Реализация Python использует встроенную версию hmac. Она примерно в три раза медленнее и не освобождает GIL.

Устаревшая с версии 3.10: Медленная реализация Python для pbkdf2_hmac устарела. В будущем функция будет доступна только при компиляции Python с OpenSSL.

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 ограничивает память (по умолчанию 32 МБ в OpenSSL 1.1.0). 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: начальный фрагмент данных для хеширования, который должен быть объектом типа bytes. Он может передаваться только как позиционный аргумент.
• 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.