`hashlib.md`

624 строк · 47.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.16/library/hashlib.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `hashlib` – безопасные хеши и дайджесты сообщений89**Исходный код:** [Lib/hashlib.py](https://python-all.ru/src/main/Lib/hashlib.py)1011---1213This module implements a common interface to many different hash algorithms. Included are the FIPS secure hash algorithms SHA224, SHA256, SHA384, SHA512, (defined in [the FIPS 180-4 standard](https://python-all.ru/3.16/library/hashlib.html)), the SHA-3 series (defined in [the FIPS 202 standard](https://python-all.ru/3.16/library/hashlib.html)) as well as the legacy algorithms SHA1 ([formerly part of FIPS](https://python-all.ru/3.16/library/hashlib.html)) and the MD5 algorithm (defined in internet [**RFC 1321**](https://python-all.ru/3.16/library/hashlib.html)).1415> **Примечание**16>17> Если вам нужны хеш-функции adler32 или crc32, они доступны в модуле [`zlib`](https://python-all.ru/3.16/library/zlib.html#module-zlib).1819## Алгоритмы хеширования2021There is one constructor method named for each type of *hash*. All return a hash object with the same simple interface. For example: use [`sha256()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.sha256) to create a SHA-256 hash object. You can now feed this object with [bytes-like objects](https://python-all.ru/3.16/glossary.html#term-bytes-like-object) (normally [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes)) using the [`update`](https://python-all.ru/3.16/library/hashlib.html#hashlib.hash.update) method. At any point you can ask it for the *digest* of the concatenation of the data fed to it so far using the [`digest()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.hash.digest) or [`hexdigest()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.hash.hexdigest) methods.2223To allow multithreading, the Python [GIL](https://python-all.ru/3.16/glossary.html#term-GIL) is released while computing a hash supplied more than 2047 bytes of data at once in its constructor or [`.update`](https://python-all.ru/3.16/library/hashlib.html#hashlib.hash.update) method.2425Конструкторы хеш-алгоритмов, которые всегда присутствуют в этом модуле: [`md5()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.md5), [`sha1()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.sha1), [`sha224()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.sha224), [`sha256()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.sha256), [`sha384()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.sha384), [`sha512()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.sha512), [`sha3_224()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.sha3_224), [`sha3_256()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.sha3_256), [`sha3_384()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.sha3_384), [`sha3_512()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.sha3_512), [`shake_128()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.shake_128), [`shake_256()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.shake_256), [`blake2b()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.blake2b) и [`blake2s()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.blake2s). Они соответствуют [`algorithms_guaranteed`](https://python-all.ru/3.16/library/hashlib.html#hashlib.algorithms_guaranteed).2627Тем не менее любой из них может отсутствовать или быть заблокирован в необычных средах, например в редкой «FIPS-совместимой» сборке Python или когда «режим FIPS» OpenSSL настроен на исключение некоторых алгоритмов из поставщика по умолчанию. Вызов конструктора недоступного алгоритма вызывает [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError).2829Additional algorithms may also be available if your Python distribution’s `hashlib` was linked against a build of OpenSSL that provides others. Others *are not guaranteed available* on all installations and will only be accessible by name via [`new()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.new). See [`algorithms_available`](https://python-all.ru/3.16/library/hashlib.html#hashlib.algorithms_available).3031> **Предупреждение**32>33> Some algorithms have known hash collision weaknesses (including MD5 and SHA1). Refer to [Attacks on cryptographic hash algorithms](https://python-all.ru/3.16/library/hashlib.html) and the [hashlib-seealso](https://python-all.ru/3.16/library/hashlib.html#hashlib-seealso) section at the end of this document.3435Added in version 3.6: SHA3 (Keccak) and SHAKE constructors [`sha3_224()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.sha3_224), [`sha3_256()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.sha3_256), [`sha3_384()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.sha3_384), [`sha3_512()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.sha3_512), [`shake_128()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.shake_128), [`shake_256()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.shake_256) were added. [`blake2b()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.blake2b) and [`blake2s()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.blake2s) were added.3637Changed in version 3.9: All hashlib constructors take a keyword-only argument *usedforsecurity* with default value `True`. A false value allows the use of insecure and blocked hashing algorithms in restricted environments. `False` indicates that the hashing algorithm is not used in a security context, e.g. as a non-cryptographic one-way compression function.3839Changed in version 3.9: Hashlib now uses SHA3 and SHAKE from OpenSSL if it provides it.4041Changed in version 3.12: For any of the MD5, SHA1, SHA2, or SHA3 algorithms that the linked OpenSSL does not provide we fall back to a verified implementation from the [HACL\* project](https://python-all.ru/3.16/library/hashlib.html).4243Устарело с версии 3.15, будет удалено в версии 3.19: Недокументированный именованный параметр `string` в `_hashlib.new()` и конструкторах, названных по хешу, таких как `_md5.md5()`, устарел. Рекомендуется передавать начальные данные как позиционный аргумент для максимальной обратной совместимости.4445## Использование4647Чтобы получить дайджест байтовой строки `b"Nobody inspects the spammish repetition"`:4849```python50>>> import hashlib51>>> m = hashlib.sha256()52>>> m.update(b"Nobody inspects")53>>> m.update(b" the spammish repetition")54>>> m.digest()55b'\x03\x1e\xdd}Ae\x15\x93\xc5\xfe\\\x00o\xa5u+7\xfd\xdf\xf7\xbcN\x84:\xa6\xaf\x0c\x95\x0fK\x94\x06'56>>> m.hexdigest()57'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'58```5960Более компактно:6162```python63>>> hashlib.sha256(b"Nobody inspects the spammish repetition").hexdigest()64'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'65```6667## Конструкторы6869#### `hashlib.new(name, [data, ]*, usedforsecurity=True)`7071Is a generic constructor that takes the string *name* of the desired algorithm as its first parameter. It also exists to allow access to the above listed hashes as well as any other algorithms that your OpenSSL library may offer.7273Использование [`new()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.new) с именем алгоритма:7475```python76>>> h = hashlib.new('sha256')77>>> h.update(b"Nobody inspects the spammish repetition")78>>> h.hexdigest()79'031edd7d41651593c5fe5c006fa5752b37fddff7bc4e843aa6af0c950f4b9406'80```8182#### `hashlib.md5([data, ]*, usedforsecurity=True)`8384#### `hashlib.sha1([data, ]*, usedforsecurity=True)`8586#### `hashlib.sha224([data, ]*, usedforsecurity=True)`8788#### `hashlib.sha256([data, ]*, usedforsecurity=True)`8990#### `hashlib.sha384([data, ]*, usedforsecurity=True)`9192#### `hashlib.sha512([data, ]*, usedforsecurity=True)`9394#### `hashlib.sha3_224([data, ]*, usedforsecurity=True)`9596#### `hashlib.sha3_256([data, ]*, usedforsecurity=True)`9798#### `hashlib.sha3_384([data, ]*, usedforsecurity=True)`99100#### `hashlib.sha3_512([data, ]*, usedforsecurity=True)`101102Именованные конструкторы такого рода быстрее, чем передача имени алгоритма в [`new()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.new).103104## Атрибуты105106Модуль hashlib предоставляет следующие константные атрибуты:107108#### `hashlib.algorithms_guaranteed`109110Множество, содержащее имена хеш-алгоритмов, которые гарантированно поддерживаются этим модулем на всех платформах. Обратите внимание, что «md5» присутствует в этом списке, несмотря на то, что некоторые вышестоящие поставщики предлагают странную сборку Python «с поддержкой FIPS», которая его исключает.111112Добавлено в версии 3.2.113114#### `hashlib.algorithms_available`115116Множество, содержащее имена хеш-алгоритмов, доступных в работающем интерпретаторе Python. Эти имена будут распознаны при передаче в [`new()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.new). [`algorithms_guaranteed`](https://python-all.ru/3.16/library/hashlib.html#hashlib.algorithms_guaranteed) всегда будет подмножеством. Один и тот же алгоритм может появляться в этом множестве несколько раз под разными именами (благодаря OpenSSL).117118Добавлено в версии 3.2.119120## Хеш-объекты121122Следующие значения предоставляются в качестве константных атрибутов хеш-объектов, возвращаемых конструкторами:123124#### `hash.digest_size`125126Размер результирующего хеша в байтах.127128#### `hash.block_size`129130Внутренний размер блока хэш-алгоритма в байтах.131132Хэш-объект имеет следующие атрибуты:133134#### `hash.name`135136Каноническое имя этого хеша, всегда в нижнем регистре и всегда подходящее в качестве параметра для [`new()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.new), чтобы создать другой хеш того же типа.137138Изменено в версии 3.4: Атрибут name присутствует в CPython с самого начала, но до Python 3.4 не был формально определён, поэтому может отсутствовать на некоторых платформах.139140Хеш-объект имеет следующие методы:141142#### `hash.update(data)`143144Обновляет хеш-объект с помощью [байтоподобного объекта](https://python-all.ru/3.16/glossary.html#term-bytes-like-object). Многократные вызовы эквивалентны одному вызову с конкатенацией всех аргументов: `m.update(a); m.update(b)` эквивалентно `m.update(a+b)`.145146#### `hash.digest()`147148Возвращает дайджест данных, переданных методу [`update()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.hash.update) на данный момент. Это байтовый объект размером [`digest_size`](https://python-all.ru/3.16/library/hashlib.html#hashlib.hash.digest_size), который может содержать байты во всём диапазоне от 0 до 255.149150#### `hash.hexdigest()`151152Как [`digest()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.hash.digest), за исключением того, что дайджест возвращается в виде строкового объекта двойной длины, содержащего только шестнадцатеричные цифры. Это можно использовать для безопасного обмена значением в электронной почте или других недвоичных средах.153154#### `hash.copy()`155156Возвращает копию («клон») хеш-объекта. Это можно использовать для эффективного вычисления дайджестов данных, имеющих общую начальную подстроку.157158## Дайджесты переменной длины SHAKE159160#### `hashlib.shake_128([data, ]*, usedforsecurity=True)`161162#### `hashlib.shake_256([data, ]*, usedforsecurity=True)`163164Алгоритмы [`shake_128()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.shake_128) и [`shake_256()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.shake_256) предоставляют дайджесты переменной длины с length\_in\_bits//2 до 128 или 256 бит безопасности. Поэтому их методы дайджеста требуют указания длины. Максимальная длина не ограничена алгоритмом SHAKE.165166#### `shake.digest(length)`167168Возвращает дайджест данных, переданных методу [`update()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.hash.update) на текущий момент. Это объект bytes размером *length*, который может содержать байты во всём диапазоне от 0 до 255.169170#### `shake.hexdigest(length)`171172Как и [`digest()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.shake.digest), но дайджест возвращается в виде строкового объекта двойной длины, содержащего только шестнадцатеричные цифры. Это может использоваться для обмена значениями в электронной почте или других небинарных средах.173174Пример использования:175176```python177>>> h = hashlib.shake_256(b'Nobody inspects the spammish repetition')178>>> h.hexdigest(20)179'44709d6fcb83d92a76dcb0b668c98e1b1d3dafe7'180```181182## Хэширование файлов183184Модуль hashlib предоставляет вспомогательную функцию для эффективного хэширования файла или файлоподобного объекта.185186#### `hashlib.file_digest(fileobj, digest, /)`187188Возвращает объект дайджеста, обновлённый содержимым файлового объекта.189190*fileobj* должен быть файлоподобным объектом, открытым для чтения в двоичном режиме. Он принимает файловые объекты от встроенных [`open()`](https://python-all.ru/3.16/library/functions.html#open), экземпляров [`BytesIO`](https://python-all.ru/3.16/library/io.html#io.BytesIO), объектов SocketIO из [`socket.socket.makefile()`](https://python-all.ru/3.16/library/socket.html#socket.socket.makefile) и т.п. *fileobj* должен быть открыт в блокирующем режиме, иначе может быть возбуждено [`BlockingIOError`](https://python-all.ru/3.16/library/exceptions.html#BlockingIOError).191192Функция может обходить ввод-вывод Python и использовать файловый дескриптор из [`fileno()`](https://python-all.ru/3.16/library/io.html#io.IOBase.fileno) напрямую. Следует считать, что *fileobj* находится в неизвестном состоянии после возврата или возбуждения исключения этой функцией. Закрытие *fileobj* остаётся на усмотрении вызывающего кода.193194*digest* должен быть либо именем алгоритма хэширования в виде *str*, конструктором хэша, либо вызываемым объектом, возвращающим хэш-объект.195196Пример:197198```python199>>> import io, hashlib, hmac200>>> with open("library/hashlib.rst", "rb") as f:201...     digest = hashlib.file_digest(f, "sha256")202...203>>> digest.hexdigest()204'...'205```206207```python208>>> buf = io.BytesIO(b"somedata")209>>> mac1 = hmac.HMAC(b"key", digestmod=hashlib.sha512)210>>> digest = hashlib.file_digest(buf, lambda: mac1)211```212213```python214>>> digest is mac1215True216>>> mac2 = hmac.HMAC(b"key", b"somedata", digestmod=hashlib.sha512)217>>> mac1.digest() == mac2.digest()218True219```220221Добавлено в версии 3.12.222223Изменено в версии 3.14: Теперь возбуждает [`BlockingIOError`](https://python-all.ru/3.16/library/exceptions.html#BlockingIOError), если файл открыт в неблокирующем режиме. Ранее в дайджест добавлялись ложные нулевые байты.224225## Вывод ключей226227Алгоритмы вывода ключей и растяжения ключей предназначены для безопасного хэширования паролей. Простые алгоритмы, такие как `sha1(password)`, не устойчивы к атакам полным перебором. Хорошая функция хэширования паролей должна быть настраиваемой, медленной и включать [соль](https://python-all.ru/3.16/library/hashlib.html).228229#### `hashlib.pbkdf2_hmac(hash_name, password, salt, iterations, dklen=None)`230231Функция реализует функцию вывода ключей на основе пароля PKCS#5 версии 2. Она использует HMAC в качестве псевдослучайной функции.232233Строка *hash\_name* – это желаемое имя алгоритма хэширования для HMAC, например 'sha1' или 'sha256'. *password* и *salt* интерпретируются как буферы байтов. Приложениям и библиотекам следует ограничивать *password* разумной длиной (например, 1024). *salt* должна содержать около 16 или более байтов из надёжного источника, например [`os.urandom()`](https://python-all.ru/3.16/library/os.html#os.urandom).234235Количество *итераций* следует выбирать на основе алгоритма хэширования и вычислительной мощности. По состоянию на 2022 год рекомендуются сотни тысяч итераций SHA-256. Обоснование того, почему и как выбрать оптимальное значение для вашего приложения, см. в *Приложении A.2.2* к [NIST-SP-800-132](https://python-all.ru/3.16/library/hashlib.html). Ответы на [вопрос stackexchange об итерациях pbkdf2](https://python-all.ru/3.16/library/hashlib.html) подробно это объясняют.236237*dklen* – это длина производного ключа в байтах. Если *dklen* равно `None`, то используется размер дайджеста алгоритма хэширования *hash\_name*, например 64 для SHA-512.238239```python240>>> from hashlib import pbkdf2_hmac241>>> our_app_iters = 500_000  # Зависит от приложения, см. выше.242>>> dk = pbkdf2_hmac('sha256', b'password', b'bad salt' * 2, our_app_iters)243>>> dk.hex()244'15530bba69924174860db778f2c6f8104d3aaf9d26241840c8c4a641c8d000a9'245```246247Функция доступна только при сборке Python с OpenSSL.248249Добавлено в версии 3.4.250251Изменено в версии 3.12: Теперь функция доступна только при сборке Python с OpenSSL. Медленная реализация на чистом Python удалена.252253#### `hashlib.scrypt(password, *, salt, n, r, p, maxmem=0, dklen=64)`254255Функция реализует функцию вывода ключей на основе пароля scrypt, как определено в [**RFC 7914**](https://python-all.ru/3.16/library/hashlib.html).256257*password* и *salt* должны быть [байтоподобными объектами](https://python-all.ru/3.16/glossary.html#term-bytes-like-object). Приложениям и библиотекам следует ограничивать *password* разумной длиной (например, 1024). *salt* должна содержать около 16 или более байтов из надёжного источника, например [`os.urandom()`](https://python-all.ru/3.16/library/os.html#os.urandom).258259*n* – это фактор стоимости CPU/памяти, *r* – размер блока, *p* – фактор параллелизации, а *maxmem* ограничивает память (по умолчанию 32 МиБ в OpenSSL 1.1.0). *dklen* – длина производного ключа в байтах.260261Добавлено в версии 3.6.262263## BLAKE2264265[BLAKE2](https://python-all.ru/3.16/library/hashlib.html) – это криптографическая хэш-функция, определённая в [**RFC 7693**](https://python-all.ru/3.16/library/hashlib.html), которая существует в двух вариантах:266267- **BLAKE2b**, оптимизированная для 64-битных платформ и создающая дайджесты любого размера от 1 до 64 байтов,268- **BLAKE2s**, оптимизированная для 8- и 32-битных платформ и создающая дайджесты любого размера от 1 до 32 байтов.269270BLAKE2 поддерживает **ключевой режим** (более быструю и простую замену [HMAC](https://python-all.ru/3.16/library/hashlib.html)), **хэширование с солью**, **персонализацию** и **древовидное хэширование**.271272Хэш-объекты этого модуля следуют API объектов стандартной библиотеки `hashlib`.273274### Создание хеш-объектов275276Новые хеш-объекты создаются вызовом функций-конструкторов:277278#### `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)`279280#### `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)`281282Эти функции возвращают соответствующие хеш-объекты для вычисления BLAKE2b или BLAKE2s. Они опционально принимают следующие общие параметры:283284- *data*: начальный фрагмент данных для хеширования, который должен быть [байтоподобный объект](https://python-all.ru/3.16/glossary.html#term-bytes-like-object). Его можно передавать только как позиционный аргумент.285- *digest\_size*: размер выходного дайджеста в байтах.286- *key*: ключ для хеширования с ключом (до 64 байт для BLAKE2b, до 32 байт для BLAKE2s).287- *salt*: соль для рандомизированного хеширования (до 16 байт для BLAKE2b, до 8 байт для BLAKE2s).288- *person*: строка персонализации (до 16 байт для BLAKE2b, до 8 байт для BLAKE2s).289290Следующая таблица показывает ограничения для общих параметров (в байтах):291292| Хеш | digest\_size | len(key) | len(salt) | len(person) |293| --- | --- | --- | --- | --- |294| BLAKE2b | 64 | 64 | 16 | 16 |295| BLAKE2s | 32 | 32 | 8 | 8 |296297> **Примечание**298>299> Спецификация BLAKE2 определяет постоянные длины для параметров соли и персонализации, однако для удобства данная реализация принимает байтовые строки любой длины вплоть до указанной. Если длина параметра меньше указанной, он дополняется нулями, так что, например, `b'salt'` и `b'salt\x00'` – одно и то же значение. (Это не относится к *key*.)300301Эти размеры доступны в виде [констант](https://python-all.ru/3.16/library/hashlib.html#constants) модуля, описанных ниже.302303Функции-конструкторы также принимают следующие параметры хеширования деревьев:304305- *fanout*: fanout (от 0 до 255, 0 – если без ограничения, 1 в последовательном режиме).306- *depth*: максимальная глубина дерева (от 1 до 255, 255 – если без ограничения, 1 в последовательном режиме).307- *leaf\_size*: максимальная длина листа в байтах (от 0 до `2**32-1`, 0 – если без ограничения или в последовательном режиме).308- *node\_offset*: смещение узла (от 0 до `2**64-1` для BLAKE2b, от 0 до `2**48-1` для BLAKE2s, 0 для первого, самого левого листа или в последовательном режиме).309- *node\_depth*: глубина узла (от 0 до 255, 0 для листьев или в последовательном режиме).310- *inner\_size*: размер внутреннего дайджеста (от 0 до 64 для BLAKE2b, от 0 до 32 для BLAKE2s, 0 в последовательном режиме).311- *last\_node*: логическое значение, указывающее, является ли обрабатываемый узел последним (`False` для последовательного режима).312313![Пояснение параметров режима дерева.](https://python-all.ru/3.16/_images/hashlib-blake2-tree.png)314315См. раздел 2.10 в [спецификации BLAKE2](https://python-all.ru/3.16/library/hashlib.html) для всестороннего обзора хеширования деревьев.316317### Константы318319#### `blake2b.SALT_SIZE`320321#### `blake2s.SALT_SIZE`322323Длина соли (максимальная длина, принимаемая конструкторами).324325#### `blake2b.PERSON_SIZE`326327#### `blake2s.PERSON_SIZE`328329Длина строки персонализации (максимальная длина, принимаемая конструкторами).330331#### `blake2b.MAX_KEY_SIZE`332333#### `blake2s.MAX_KEY_SIZE`334335Максимальный размер ключа.336337#### `blake2b.MAX_DIGEST_SIZE`338339#### `blake2s.MAX_DIGEST_SIZE`340341Максимальный размер дайджеста, который может выдать хеш-функция.342343### Примеры344345#### Простое хеширование346347Чтобы вычислить хеш некоторых данных, сначала необходимо создать объект хеша, вызвав соответствующую функцию-конструктор ([`blake2b()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.blake2b) или [`blake2s()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.blake2s)), затем обновить его данными, вызвав [`update()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.hash.update) для этого объекта, и, наконец, получить дайджест из объекта, вызвав [`digest()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.hash.digest) (или [`hexdigest()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.hash.hexdigest) для строки в шестнадцатеричной кодировке).348349```python350>>> from hashlib import blake2b351>>> h = blake2b()352>>> h.update(b'Hello world')353>>> h.hexdigest()354'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'355```356357Для сокращения можно передать первый фрагмент данных для обновления непосредственно конструктору в качестве позиционного аргумента:358359```python360>>> from hashlib import blake2b361>>> blake2b(b'Hello world').hexdigest()362'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'363```364365[`hash.update()`](https://python-all.ru/3.16/library/hashlib.html#hashlib.hash.update) можно вызывать сколько угодно раз для итеративного обновления хеша:366367```python368>>> from hashlib import blake2b369>>> items = [b'Hello', b' ', b'world']370>>> h = blake2b()371>>> for item in items:372...     h.update(item)373...374>>> h.hexdigest()375'6ff843ba685842aa82031d3f53c48b66326df7639a63d128974c5c14f31a0f33343a8c65551134ed1ae0f2b0dd2bb495dc81039e3eeb0aa1bb0388bbeac29183'376```377378#### Использование разных размеров дайджеста379380BLAKE2 имеет настраиваемый размер дайджестов: до 64 байт для BLAKE2b и до 32 байт для BLAKE2s. Например, чтобы заменить SHA-1 на BLAKE2b без изменения размера вывода, можно указать BLAKE2b создавать 20-байтовые дайджесты:381382```python383>>> from hashlib import blake2b384>>> h = blake2b(digest_size=20)385>>> h.update(b'Replacing SHA1 with the more secure function')386>>> h.hexdigest()387'd24f26cf8de66472d58d4e1b1774b4c9158b1f4c'388>>> h.digest_size38920390>>> len(h.digest())39120392```393394Объекты хешей с разными размерами дайджеста имеют совершенно разные выходные данные (короткие хеши *не* являются префиксами более длинных); BLAKE2b и BLAKE2s выдают разные результаты, даже если длина вывода одинакова:395396```python397>>> from hashlib import blake2b, blake2s398>>> blake2b(digest_size=10).hexdigest()399'6fa1d8fcfd719046d762'400>>> blake2b(digest_size=11).hexdigest()401'eb6ec15daf9546254f0809'402>>> blake2s(digest_size=10).hexdigest()403'1bf21a98c78a1c376ae9'404>>> blake2s(digest_size=11).hexdigest()405'567004bf96e4a25773ebf4'406```407408#### Хеширование с ключом409410Хеширование с ключом может использоваться для аутентификации как более быстрая и простая замена [коду аутентификации сообщений на основе хеша](https://python-all.ru/3.16/library/hashlib.html) (HMAC). BLAKE2 можно безопасно использовать в режиме prefix-MAC благодаря свойству неразличимости, унаследованному от BLAKE.411412Этот пример показывает, как получить (в шестнадцатеричной кодировке) 128-битный код аутентификации для сообщения `b'message data'` с ключом `b'pseudorandom key'`:413414```python415>>> from hashlib import blake2b416>>> h = blake2b(key=b'pseudorandom key', digest_size=16)417>>> h.update(b'message data')418>>> h.hexdigest()419'3d363ff7401e02026f4a4687d4863ced'420```421422В качестве практического примера: веб-приложение может симметрично подписывать куки, отправляемые пользователям, и впоследствии проверять их, чтобы убедиться, что они не были изменены:423424```python425>>> from hashlib import blake2b426>>> from hmac import compare_digest427>>>428>>> SECRET_KEY = b'pseudorandomly generated server secret key'429>>> AUTH_SIZE = 16430>>>431>>> def sign(cookie):432...     h = blake2b(digest_size=AUTH_SIZE, key=SECRET_KEY)433...     h.update(cookie)434...     return h.hexdigest().encode('utf-8')435>>>436>>> def verify(cookie, sig):437...     good_sig = sign(cookie)438...     return compare_digest(good_sig, sig)439>>>440>>> cookie = b'user-alice'441>>> sig = sign(cookie)442>>> print("{0},{1}".format(cookie.decode('utf-8'), sig))443user-alice,b'43b3c982cf697e0c5ab22172d1ca7421'444>>> verify(cookie, sig)445True446>>> verify(b'user-bob', sig)447False448>>> verify(cookie, b'0102030405060708090a0b0c0d0e0f00')449False450```451452Несмотря на наличие встроенного режима хеширования с ключом, BLAKE2, конечно, может использоваться в конструкции HMAC с модулем [`hmac`](https://python-all.ru/3.16/library/hmac.html#module-hmac):453454```python455>>> import hmac, hashlib456>>> m = hmac.new(b'secret key', digestmod=hashlib.blake2s)457>>> m.update(b'message')458>>> m.hexdigest()459'e3c8102868d28b5ff85fc35dda07329970d1a01e273c37481326fe0c861c8142'460```461462#### Рандомизированное хеширование463464Устанавливая параметр *salt* (соль), можно внести рандомизацию в хеш-функцию. Рандомизированное хеширование полезно для защиты от атак на коллизии хеш-функции, используемой в цифровых подписях.465466> Рандомизированное хеширование предназначено для ситуаций, когда одна сторона – подготовитель сообщения – создаёт всё сообщение или его часть для подписания второй стороной – подписантом. Если подготовитель способен найти коллизии криптографической хеш-функции (то есть два сообщения, дающих одно и то же хеш-значение), то он может подготовить осмысленные варианты сообщения, которые будут давать одинаковые хеш-значение и цифровую подпись, но с разными результатами (например, перевод $1 000 000 на счёт вместо $10). Криптографические хеш-функции изначально проектировались с устойчивостью к коллизиям как главной целью, но современная сосредоточенность на атаках на криптографические хеш-функции может привести к тому, что конкретная криптографическая хеш-функция будет обеспечивать меньшую устойчивость к коллизиям, чем ожидалось. Рандомизированное хеширование предоставляет подписанту дополнительную защиту, снижая вероятность того, что подготовитель сможет сгенерировать два или более сообщений, которые в конечном итоге дадут одно и то же хеш-значение в процессе генерации цифровой подписи – даже если на практике можно найти коллизии для данной хеш-функции. Однако использование рандомизированного хеширования может снизить уровень безопасности, обеспечиваемой цифровой подписью, когда все части сообщения подготовлены подписантом.467>468> ([NIST SP-800-106 «Рандомизированное хеширование для цифровых подписей»](https://python-all.ru/3.16/library/hashlib.html))469470В BLAKE2 соль обрабатывается как одноразовый вход хеш-функции во время инициализации, а не как вход каждой функции сжатия.471472> **Предупреждение**473>474> *Хеширование с солью* (или просто хеширование) с помощью BLAKE2 или любой другой криптографической хеш-функции общего назначения, такой как SHA-256, не подходит для хеширования паролей. См. [BLAKE2 FAQ](https://python-all.ru/3.16/library/hashlib.html) для получения дополнительной информации.475476```python477>>> import os478>>> from hashlib import blake2b479>>> msg = b'some message'480>>> # Вычислить первый хеш со случайной солью.481>>> salt1 = os.urandom(blake2b.SALT_SIZE)482>>> h1 = blake2b(salt=salt1)483>>> h1.update(msg)484>>> # Вычислить второй хеш с другой случайной солью.485>>> salt2 = os.urandom(blake2b.SALT_SIZE)486>>> h2 = blake2b(salt=salt2)487>>> h2.update(msg)488>>> # Дайджесты различаются.489>>> h1.digest() != h2.digest()490True491```492493#### Персонализация494495Иногда бывает полезно заставить хеш-функцию выдавать разные дайджесты для одного и того же входного значения для разных целей. Цитируя авторов хеш-функции Skein:496497> Мы рекомендуем всем разработчикам приложений серьезно рассмотреть эту возможность; мы видели много протоколов, где хеш, вычисленный в одной части протокола, может быть использован в совершенно другой части, потому что два хеш-вычисления были выполнены над похожими или связанными данными, и атакующий может заставить приложение сделать входные данные для хешей одинаковыми. Персонализация каждой хеш-функции, используемой в протоколе, однозначно предотвращает такой тип атаки.498>499> ([The Skein Hash Function Family](https://python-all.ru/3.16/library/hashlib.html), p. 21)500501BLAKE2 можно персонализировать, передав байты аргументу *person*:502503```python504>>> from hashlib import blake2b505>>> FILES_HASH_PERSON = b'MyApp Files Hash'506>>> BLOCK_HASH_PERSON = b'MyApp Block Hash'507>>> h = blake2b(digest_size=32, person=FILES_HASH_PERSON)508>>> h.update(b'the same content')509>>> h.hexdigest()510'20d9cd024d4fb086aae819a1432dd2466de12947831b75c5a30cf2676095d3b4'511>>> h = blake2b(digest_size=32, person=BLOCK_HASH_PERSON)512>>> h.update(b'the same content')513>>> h.hexdigest()514'cf68fb5761b9c44e7878bfb2c4c9aea52264a80b75005e65619778de59f383a3'515```516517Персонализация вместе с ключевым режимом также может использоваться для получения разных ключей из одного.518519```python520>>> from hashlib import blake2s521>>> from base64 import b64decode, b64encode522>>> orig_key = b64decode(b'Rm5EPJai72qcK3RGBpW3vPNfZy5OZothY+kHY6h21KM=')523>>> enc_key = blake2s(key=orig_key, person=b'kEncrypt').digest()524>>> mac_key = blake2s(key=orig_key, person=b'kMAC').digest()525>>> print(b64encode(enc_key).decode('utf-8'))526rbPb15S/Z9t+agffno5wuhB77VbRi6F9Iv2qIxU7WHw=527>>> print(b64encode(mac_key).decode('utf-8'))528G9GtHFE1YluXY1zWPlYk1e/nWfu0WSEb0KRcjhDeP/o=529```530531#### Древовидный режим532533Пример хеширования минимального дерева с двумя листовыми узлами:534535```python536  10537 /  \53800  01539```540541Этот пример использует 64-байтовые внутренние дайджесты и возвращает 32-байтовый конечный дайджест:542543```python544>>> from hashlib import blake2b545>>>546>>> FANOUT = 2547>>> DEPTH = 2548>>> LEAF_SIZE = 4096549>>> INNER_SIZE = 64550>>>551>>> buf = bytearray(6000)552>>>553>>> # Левый лист554... h00 = blake2b(buf[0:LEAF_SIZE], fanout=FANOUT, depth=DEPTH,555...               leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,556...               node_offset=0, node_depth=0, last_node=False)557>>> # Правый лист558... h01 = blake2b(buf[LEAF_SIZE:], fanout=FANOUT, depth=DEPTH,559...               leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,560...               node_offset=1, node_depth=0, last_node=True)561>>> # Корневой узел562... h10 = blake2b(digest_size=32, fanout=FANOUT, depth=DEPTH,563...               leaf_size=LEAF_SIZE, inner_size=INNER_SIZE,564...               node_offset=0, node_depth=1, last_node=True)565>>> h10.update(h00.digest())566>>> h10.update(h01.digest())567>>> h10.hexdigest()568'3ad2a9b37c6070e374c7a8c508fe20ca86b6ed54e286e93a0318e95e881db5aa'569```570571### Авторы572573[BLAKE2](https://python-all.ru/3.16/library/hashlib.html) был разработан *Jean-Philippe Aumasson*, *Samuel Neves*, *Zooko Wilcox-O’Hearn* и *Christian Winnerlein* на основе [SHA-3](https://python-all.ru/3.16/library/hashlib.html), финалистом которого был [BLAKE](https://python-all.ru/3.16/library/hashlib.html) созданный *Jean-Philippe Aumasson*, *Luca Henzen*, *Willi Meier* и *Raphael C.-W. Phan*.574575В нём используется основной алгоритм из шифра [ChaCha](https://python-all.ru/3.16/library/hashlib.html), разработанного *Daniel J. Bernstein*.576577Реализация в стандартной библиотеке основана на модуле [pyblake2](https://python-all.ru/3.16/library/hashlib.html). Её написал *Dmitry Chestnykh* на основе реализации на C, написанной *Samuel Neves*. Документация скопирована из [pyblake2](https://python-all.ru/3.16/library/hashlib.html) и написана *Dmitry Chestnykh*.578579Код на C был частично переписан для Python *Christian Heimes*.580581Следующее заявление о передаче в общественное достояние применимо как к реализации хеш-функции на C, так и к коду расширения и данной документации:582583> Насколько это возможно по закону, автор(ы) передали все авторские и смежные права на это программное обеспечение в общественное достояние по всему миру. Это программное обеспечение распространяется без каких-либо гарантий.584>585> Копия заявления CC0 о передаче в общественное достояние должна прилагаться к этому программному обеспечению. Если она отсутствует, см. [https://creativecommons.org/publicdomain/zero/1.0/](https://python-all.ru/3.16/library/hashlib.html).586587Следующие люди участвовали в разработке или вносили свои изменения в проект, передавая их в общественное достояние в соответствии с Creative Commons Public Domain Dedication 1.0 Universal:588589- *Alexandr Sokolovskiy*590591> **См. также**592>593> **Модуль [`hmac`](https://python-all.ru/3.16/library/hmac.html#module-hmac)**594>595> Модуль для генерации кодов аутентификации сообщений с использованием хешей.596>597> **Модуль [`base64`](https://python-all.ru/3.16/library/base64.html#module-base64)**598>599> Другой способ кодирования двоичных хешей для сред, не предназначенных для работы с двоичными данными.600>601> **[https://nvlpubs.nist.gov/nistpubs/fips/nist.fips.180-4.pdf](https://python-all.ru/3.16/library/hashlib.html)**602>603> Публикация FIPS 180-4 о безопасных хеш-алгоритмах.604>605> **[https://csrc.nist.gov/pubs/fips/202/final](https://python-all.ru/3.16/library/hashlib.html)**606>607> Публикация FIPS 202 о стандарте SHA-3.608>609> **[https://www.blake2.net/](https://python-all.ru/3.16/library/hashlib.html)**610>611> Официальный сайт BLAKE2.612>613> **[https://en.wikipedia.org/wiki/Cryptographic\_hash\_function](https://python-all.ru/3.16/library/hashlib.html)**614>615> Статья в Википедии с информацией о том, какие алгоритмы имеют известные проблемы и что это означает для их использования.616>617> **[https://www.ietf.org/rfc/rfc8018.txt](https://python-all.ru/3.16/library/hashlib.html)**618>619> PKCS #5: Спецификация криптографии на основе пароля версии 2.1620>621> **[https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf](https://python-all.ru/3.16/library/hashlib.html)**622>623> Рекомендация NIST по выработке ключей на основе пароля.624