hashlib — Безопасные хэши и дайджесты сообщений

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

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

Для обеспечения возможности многопоточности, интерпретатор Python отпускает блокировку интерпретатора Python во время вычисления хэша, если в конструктор или метод .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)

Является универсальным конструктором, который принимает строку name желаемого алгоритма в качестве первого параметра. Он также позволяет получить доступ к перечисленным выше хэшам, а также к любым другим алгоритмам, которые может предложить ваша библиотека 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)

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

hash.digest()

Возвращает дайджест данных, переданных методу update() до сих пор. Это объект типа bytes размером 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() до сих пор. Это объект типа bytes размером 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 должен быть либо именем алгоритма хеширования в виде строки, либо конструктором хеширования, либо вызываемой функцией, возвращающей объект хеширования.

Пример:

>>> 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'

Функция доступна только при компиляции 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 должны быть объектами типа bytes. Приложения и библиотеки должны ограничивать password разумной длиной (например, 1024). salt должен составлять около 16 или более байтов из надёжного источника, например, os.urandom().

n — фактор стоимости CPU/памяти, 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 определяет постоянные длины для параметров соли и персонализации, однако для удобства эта реализация принимает байтовые строки любого размера до указанной длины. Если длина параметра меньше указанной, она заполняется нулями, таким образом, например, b'salt' и b'salt\x00' имеют одинаковое значение. (Это не относится к key.)

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

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

• fanout: 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 для более подробного обзора хеширования деревьев.