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

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

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

15.1.1. Алгоритмы хеширования

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

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

hash.digest()

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

hash.hexdigest()

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

hash.copy()

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

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

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

shake.digest(length)

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

shake.hexdigest(length)

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

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

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

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

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

Новая в версии 3.6.

15.1.4. BLAKE2

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

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

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

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

15.1.4.1. Создание объектов хэширования

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

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

15.1.4.2. Константы

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

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

15.1.4.3. Примеры

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

Для вычисления хэша некоторых данных сначала нужно создать объект хэша, вызвав соответствующую конструкторскую функцию (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'

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

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'

15.1.4.3.3. Хэширование с ключом

Хэширование с ключом можно использовать для аутентификации как более быструю и простую замену для Hash-based message authentication code (HMAC). BLAKE2 может быть безопасно использован в режиме префикс-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'

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

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

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

Установив параметр 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

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

Иногда полезно заставить хеш-функцию генерировать разные дайджесты для одного и того же входного значения для разных целей. Цитируя авторов хеш-функции 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=

15.1.4.3.6. Режим дерева

Вот пример хэширования минимального дерева с двумя узлами листа:

  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'

15.1.4.4. Авторы

BLAKE2 был разработан Jean-Philippe Aumasson, Samuel Neves, Zooko Wilcox-O’Hearn и Christian Winnerlein на основе финалиста конкурса SHA-3 BLAKE, созданного Jean-Philippe Aumasson, Luca Henzen, Willi Meier и Raphael C.-W. Phan.

Он использует ядро алгоритма из шифра ChaCha, разработанного Daniel J. Bernstein.

Реализация stdlib основана на модуле pyblake2. Она была написана Dmitry Chestnykh на основе реализации на C, написанной Samuel Neves. Документация была скопирована с pyblake2 и написана Dmitry Chestnykh.

Код на C был частично переписан для Python Christian Heimes.

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

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

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

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

• Alexandr Sokolovskiy