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

Исходный код: Lib/hashlib.py

Этот модуль реализует общий интерфейс для многих различных алгоритмов защищённых хэшей и дайджестов сообщений. Включает в себя алгоритмы FIPS защищённых хэшей SHA1, SHA224, SHA256, SHA384 и SHA512 (определённые в FIPS 180-2), а также алгоритм MD5 RSA (определённый в RFC 1321).

Термины «защищённый хэш» и «дайджест сообщения» взаимозаменяемы. Более старые алгоритмы назывались дайджестами сообщений. Современный термин — защищённый хэш.

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

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

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

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

>>> h = hashlib.new('ripemd160')
>>> h.update(b"Nobody inspects the spammish repetition")
>>> h.hexdigest()
'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'

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

hash.digest()

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

hash.hexdigest()

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

hash.copy()

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

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

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

shake.digest(length)

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

shake.hexdigest(length)

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

Вывод ключей

Алгоритмы вывода ключей и расширения ключей предназначены для безопасного хэширования паролей. Примитивные алгоритмы, такие как 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 должно быть выбрано на основе алгоритма хэширования и вычислительной мощности. По состоянию на 2013 год рекомендуется не менее 100 000 итераций SHA-256.

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

>>> import hashlib, binascii
>>> dk = hashlib.pbkdf2_hmac('sha256', b'password', b'salt', 100000)
>>> binascii.hexlify(dk)
b'0394a2ede332c9a13eb82e9b24631604c31df978b4e2f0fbd2c549944f9d79a5'

Новое в версии 3.4.

Примечание

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

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 — длина выведенного ключа.

Доступность: OpenSSL 1.1+.

Новое в версии 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)

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)

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

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

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

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

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

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

Константы

blake2b.SALT_SIZE

blake2s.SALT_SIZE

Длина соли (максимальная длина, принимаемая конструкторами).

blake2b.PERSON_SIZE

blake2s.PERSON_SIZE

Длина строки персонализации (максимальная длина, принимаемая конструкторами).

blake2b.MAX_KEY_SIZE

blake2s.MAX_KEY_SIZE

Максимальный размер ключа.

blake2b.MAX_DIGEST_SIZE

blake2s.MAX_DIGEST_SIZE

Максимальный размер дайджеста, который может вывести функция хеширования.

Примеры

Простое хэширование

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

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

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

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

Вы можете вызвать hash.update() столько раз, сколько нужно, для итеративного обновления хэша:

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

Использование различных размеров дайджестов

BLAKE2 имеет настраиваемый размер дайджестов до 64 байт для BLAKE2b и до 32 байт для BLAKE2s. Например, чтобы заменить SHA-1 на BLAKE2b без изменения размера вывода, можно указать BLAKE2b на создание дайджестов размером 20 байт:

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

Объекты хешей с различными размерами дайджестов имеют совершенно разные результаты (короткие хеши не являются префиксами длинных хешей); BLAKE2b и BLAKE2s дают разные результаты даже если длина результата одинаковая:

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

Ключевое хэширование

Ключевое хэширование может использоваться для аутентификации как более быстрый и простой заменитель Hash-based message authentication code (HMAC). BLAKE2 может безопасно использоваться в режиме prefix-MAC благодаря свойству индифферентности, унаследованному от BLAKE.

Этот пример показывает, как получить (шестнадцатеричное) 128-битное аутентификационное сообщение для сообщения b'message data' с ключом b'pseudorandom key':

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

Несмотря на то, что есть собственный режим ключевого хэширования, BLAKE2, конечно, может использоваться в построении HMAC с модулем hmac:

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

Случайное хэширование

Устанавливая параметр salt, пользователи могут ввести случайность в функцию хэширования. Случайное хэширование полезно для защиты от атак на столкновения с функцией хэширования, используемой в цифровых подписях.

Случайное хэширование предназначено для ситуаций, когда одна сторона, создатель сообщения, генерирует все или часть сообщения, которое должно быть подписано второй стороной, подписывающей сообщение. Если создатель сообщения может найти коллизии криптографической хеш-функции (т. е., два сообщения, порождающие одно и то же значение хэша), то он может подготовить осмысленные версии сообщения, которые будут давать одинаковое значение хэша и цифровую подпись, но с разными результатами (например, перевод 1 000 000 долл. на счёт, а не 10 долл.). Криптографические хеш-функции были разработаны с устойчивостью к коллизиям как основной целью, но нынешнее внимание к атакам на криптографические хеш-функции может привести к тому, что данная криптографическая хеш-функция обеспечит меньшую устойчивость к коллизиям, чем ожидалось. Случайное хэширование предоставляет подписывающей стороне дополнительную защиту, уменьшая вероятность того, что создатель сможет сгенерировать два или более сообщений, которые в конечном итоге дадут одинаковое значение хэша во время процесса генерации цифровой подписи — даже если практически возможно найти коллизии для хеш-функции. Однако использование случайного хэширования может уменьшить количество предоставляемой цифровой подписью защиты, когда все части сообщения подготовлены подписывающей стороной.

(NIST SP-800-106 «Случайное хэширование для цифровых подписей»)

В BLAKE2 соль обрабатывается как одноразовый вход в хеш-функцию во время инициализации, а не как вход в каждую функцию сжатия.

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

Персонализация

Иногда полезно заставить хеш-функцию генерировать разные дайджесты для одного и того же входного значения для разных целей. Цитата авторов хеш-функции Skein:

Мы рекомендуем всем разработчикам приложений серьезно рассмотреть этот вопрос; мы видели много протоколов, в которых хеш, вычисленный в одной части протокола, может быть использован в совершенно другой части, потому что два вычисления хеша были выполнены на похожих или связанных данных, и злоумышленник может заставить приложение сделать входные данные хеша одинаковыми. Персонализация каждой хеш-функции, используемой в протоколе, в целом останавливает этот тип атаки.

(Семейство хеш-функций Skein, стр. 21)

BLAKE2 можно персонализировать, передав байты в аргумент person:

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

В этом примере используются внутренние дайджесты размером 64 байта, а возвращается конечный дайджест размером 32 байта:

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

Авторы

BLAKE2 был разработан Жан-Пьером Омассоном, Самуэлем Невесом, Зуко Уилкоксом-О'Хирном и Кристианом Виннерлейном на основе финалиста конкурса NIST по хэш-функциям SHA-3 BLAKE, созданного Жан-Пьером Омассоном, Лукой Хенценом, Вилли Майером и Рафаэлем Ч.-В. Фаном.

Он использует ядро алгоритма из шифра ChaCha, разработанного Дэниелом Дж. Бернштейном.

Реализация в стандартной библиотеке основана на модуле pyblake2. Она была написана Дмитрием Честныхом на основе реализации на C, написанной Самуэлем Невесом. Документация была скопирована из pyblake2 и написана Дмитрием Честныхом.

Код на языке C был частично переписан для Python Кристианом Хаймсом.

Следующее посвящение в общественное достояние применяется к реализации криптографической хеш-функции на C, расширенному коду и этой документации:

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

Вы должны были получить копию посвящения в общественное достояние CC0 вместе с этим программным обеспечением. Если нет, обратитесь к https://creativecommons.org/publicdomain/zero/1.0/.

Следующие люди помогли в разработке или внесли свои изменения в проект и общественное достояние в соответствии с универсальной лицензией Creative Commons Public Domain Dedication 1.0:

• Александром Соколовским