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

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

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

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

Например, чтобы получить дайджест байтовой строки 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.digest_size
32
>>> m.block_size
64

Более сжато:

>>> hashlib.sha224(b"Nobody inspects the spammish repetition").hexdigest()
'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'

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

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

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

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

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-like object. Повторные вызовы эквивалентны одному вызову с конкатенацией всех аргументов: m.update(a); m.update(b) эквивалентен m.update(a+b).

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

hash.digest()¶

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

hash.hexdigest()¶

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

hash.copy()¶

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

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

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

shake.digest(length)¶

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

shake.hexdigest(length)¶

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

Получение ключей¶

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

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().

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

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: Медленная реализация pbkdf2_hmac в Python устарела. В будущем функция будет доступна только в том случае, если Python скомпилирован с OpenSSL.

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

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

password и salt должны быть bytes-like objects. Приложения и библиотеки должны ограничивать 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: начальный кусок данных для хэширования, который должен быть bytes-like object. Он может быть передан только как позиционный аргумент.

• digest_size: размер выходного дайджеста в байтах.

• key: ключ для хэширования с ключом (до 64 байт для BLAKE2b, до 32 байт для BLAKE2s).

• salt: соль для рандомизированного хэширования (до 16 байт для BLAKE2b, до 8 байт для BLAKE2s).

• person: строка персонализации (до 16 байт для BLAKE2b, до 8 байт для BLAKE2s).

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

Хаш	размер дайджеста	len(key)	len(salt)	len(person)
BLAKE2b	64	64	16	16
BLAKE2s	32	32	8	8

Примечание

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

Эти размеры доступны в виде модуля constants, описанного ниже.

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

• 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 specification для всестороннего рассмотрения хэширования деревьев.

>>> from hashlib import blake2b
>>> h = blake2b()
>>> h.update(b'Hello world')
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

>>> from hashlib import blake2b
>>> blake2b(b'Hello world').hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

>>> from hashlib import blake2b
>>> items = [b'Hello', b' ', b'world']
>>> h = blake2b()
>>> for item in items:
...     h.update(item)
>>> h.hexdigest()
'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'

>>> from hashlib import blake2b
>>> h = blake2b(digest_size=20)
>>> h.update(b'Replacing SHA1 with the more secure function')
>>> h.hexdigest()
'd24f26cf8de66472d58d4e1b1774b4c9158b1f4c'
>>> h.digest_size
20
>>> len(h.digest())
20

>>> from hashlib import blake2b, blake2s
>>> blake2b(digest_size=10).hexdigest()
'6fa1d8fcfd719046d762'
>>> blake2b(digest_size=11).hexdigest()
'eb6ec15daf9546254f0809'
>>> blake2s(digest_size=10).hexdigest()
'1bf21a98c78a1c376ae9'
>>> blake2s(digest_size=11).hexdigest()
'567004bf96e4a25773ebf4'

>>> from hashlib import blake2b
>>> h = blake2b(key=b'pseudorandom key', digest_size=16)
>>> h.update(b'message data')
>>> h.hexdigest()
'3d363ff7401e02026f4a4687d4863ced'

>>> from hashlib import blake2b
>>> from hmac import compare_digest
>>>
>>> SECRET_KEY = b'pseudorandomly generated server secret key'
>>> AUTH_SIZE = 16
>>>
>>> def sign(cookie):
...     h = blake2b(digest_size=AUTH_SIZE, key=SECRET_KEY)
...     h.update(cookie)
...     return h.hexdigest().encode('utf-8')
>>>
>>> def verify(cookie, sig):
...     good_sig = sign(cookie)
...     return compare_digest(good_sig, sig)
>>>
>>> cookie = b'user-alice'
>>> sig = sign(cookie)
>>> print("{0},{1}".format(cookie.decode('utf-8'), sig))
user-alice,b'43b3c982cf697e0c5ab22172d1ca7421'
>>> verify(cookie, sig)
True
>>> verify(b'user-bob', sig)
False
>>> verify(cookie, b'0102030405060708090a0b0c0d0e0f00')
False

>>> import hmac, hashlib
>>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)
>>> m.update(b'message')
>>> m.hexdigest()
'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'

>>> import os
>>> from hashlib import blake2b
>>> msg = b'some message'
>>> # Calculate the first hash with a random salt.
>>> salt1 = os.urandom(blake2b.SALT_SIZE)
>>> h1 = blake2b(salt=salt1)
>>> h1.update(msg)
>>> # Calculate the second hash with a different random salt.
>>> salt2 = os.urandom(blake2b.SALT_SIZE)
>>> h2 = blake2b(salt=salt2)
>>> h2.update(msg)
>>> # The digests are different.
>>> h1.digest() != h2.digest()
True

>>> from hashlib import blake2b
>>> FILES_HASH_PERSON = b'MyApp Files Hash'
>>> BLOCK_HASH_PERSON = b'MyApp Block Hash'
>>> h = blake2b(digest_size=32, person=FILES_HASH_PERSON)
>>> h.update(b'the same content')
>>> h.hexdigest()
'20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'
>>> h = blake2b(digest_size=32, person=BLOCK_HASH_PERSON)
>>> h.update(b'the same content')
>>> h.hexdigest()
'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'

>>> from hashlib import blake2s
>>> from base64 import b64decode, b64encode
>>> orig_key = b64decode(b'Rm5EPJai72qcK3RGBpW3vPNfZy5OZothY+kHY6h21KM=')
>>> enc_key = blake2s(key=orig_key, person=b'kEncrypt').digest()
>>> mac_key = blake2s(key=orig_key, person=b'kMAC').digest()
>>> print(b64encode(enc_key).decode('utf-8'))
rbPb15S/Z9t+agffno5wuhB77VbRi6F9Iv2qIxU7WHw=
>>> print(b64encode(mac_key).decode('utf-8'))
G9GtHFE1YluXY1zWPlYk1e/nWfu0WSEb0KRcjhDeP/o=

  10
 /  \
00  01

>>> from hashlib import blake2b
>>>
>>> FANOUT = 2
>>> DEPTH = 2
>>> LEAF_SIZE = 4096
>>> INNER_SIZE = 64
>>>
>>> buf = bytearray(6000)
>>>
>>> # Left leaf
... h00 = blake2b(buf[0:LEAF_SIZE], fanout=FANOUT, depth=DEPTH,
...               leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
...               node_offset=0, node_depth=0, last_node=False)
>>> # Right leaf
... h01 = blake2b(buf[LEAF_SIZE:], fanout=FANOUT, depth=DEPTH,
...               leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
...               node_offset=1, node_depth=0, last_node=True)
>>> # Root node
... h10 = blake2b(digest_size=32, fanout=FANOUT, depth=DEPTH,
...               leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,
...               node_offset=0, node_depth=1, last_node=True)
>>> h10.update(h00.digest())
>>> h10.update(h01.digest())
>>> h10.hexdigest()
'3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa'