<?xml version="1.0" encoding="utf-8"?>

<!-- EN-Revision: 5003a6ea92eb50ac92121782eedfc5ad3fe9d061 Maintainer: rjhdby Status: ready -->

<!-- Reviewed: no -->

<refentry xml:id="function.password-hash" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

<refnamediv>

<refname>password_hash</refname>

<refpurpose>Создаёт хеш пароля</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>string</type><methodname>password_hash</methodname>

<methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>password</parameter></methodparam>

<methodparam><type class="union"><type>string</type><type>int</type><type>null</type></type><parameter>algo</parameter></methodparam>

<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>

</methodsynopsis>

<para>

Функция <function>password_hash</function> создаёт хеш пароля через сильный необратимый алгоритм хеширования.

</para>

<simpara>

Поддерживаются следующие алгоритмы:

</simpara>

<para>

<itemizedlist>

<listitem>

<simpara>

<constant>PASSWORD_DEFAULT</constant> — алгоритм хеширования bcrypt. С PHP 5.5.0 bcrypt стал алгоритмом по умолчанию.

По мере добавления в PHP новых усиленных алгоритмов значение константы изменяется и задаёт новый идентификатор алгоритма.

При изменении алгоритма длина результата изменяется, часто увеличивается.

Поэтому сохранять результат в базе данных лучше в столбце длиной больше 60 байтов. Длину поля устанавливают равной 255 байтам, чтобы сократить риск ошибок.

</simpara>

</listitem>

<listitem>

<simpara>

<constant>PASSWORD_BCRYPT</constant> — алгоритм хеширования bcrypt.

С этой константой функция генерирует стандартный хеш с идентификатором <literal>$2y$</literal>,

совместимый с хешем, который создаёт функция <function>crypt</function>.

</simpara>

</listitem>

<listitem>

<simpara>

<constant>PASSWORD_ARGON2I</constant> — алгоритм хеширования Argon2i.

Алгоритм доступен, только если PHP скомпилировали с поддержкой Argon2.

</simpara>

</listitem>

<listitem>

<simpara>

<constant>PASSWORD_ARGON2ID</constant> — алгоритм хеширования Argon2id.

Алгоритм доступен, только если PHP скомпилировали с поддержкой Argon2.

</simpara>

</listitem>

</itemizedlist>

</para>

<simpara>

Алгоритм <constant>PASSWORD_BCRYPT</constant> поддерживает следующие опции:

</simpara>

<para>

<itemizedlist>

<listitem>

<para>

<literal>salt</literal> (<type>string</type>) — пользовательская соль для хеширования пароля.

Ручная установка соли переопределит поведение функции — предотвратит

автоматическую генерацию соли.

</para>

<para>

При пропуске параметра функция <function>password_hash</function> сгенерирует

случайную соль для каждого хешируемого пароля. Это предпочтительный

режим работы.

</para>

<warning>

<para>

Опция salt устарела в пользу соли по умолчанию,

которую функция генерирует автоматически.

Начиная с PHP 8.0.0 функция игнорирует пользовательскую соль.

</para>

</warning>

</listitem>

<listitem>

<para>

<literal>cost</literal> (<type>int</type>) — алгоритмическая сложность.

Пример работы с опцией доступен на странице

с описанием функции <function>crypt</function>.

</para>

<para>

При пропуске параметра функция выберет значение по умолчанию: <literal>12</literal>.

Со значением по умолчанию функция генерирует стойкий хеш, но конкретное значение

подстраивают под конкретное оборудование.

</para>

</listitem>

</itemizedlist>

</para>

<simpara>

Алгоритмы <constant>PASSWORD_ARGON2I</constant> и <constant>PASSWORD_ARGON2ID</constant>

поддерживают следующие опции:

</simpara>

<para>

<itemizedlist>

<listitem>

<para>

<literal>memory_cost</literal> (<type>int</type>) — максимальный размер

памяти в килобайтах для вычисления хеша Argon2.

По умолчанию функция выбирает значение константы <constant>PASSWORD_ARGON2_DEFAULT_MEMORY_COST</constant>.

</para>

</listitem>

<listitem>

<para>

<literal>time_cost</literal> (<type>int</type>) — предельное количество раундов,

которые выполняет алгоритм Argon2 для вычисления хеша.

Значение по умолчанию: <constant>PASSWORD_ARGON2_DEFAULT_TIME_COST</constant>.

</para>

</listitem>

<listitem>

<para>

<literal>threads</literal> (<type>int</type>) — количество потоков

для вычисления хеша алгоритмом Argon2.

Значение по умолчанию: <constant>PASSWORD_ARGON2_DEFAULT_THREADS</constant>.

</para>

<warning>

<para>

Опция доступна, только если PHP собрали с библиотекой libargon2, а не с libsodium.

</para>

</warning>

</listitem>

</itemizedlist>

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<variablelist>

<varlistentry>

<term><parameter>password</parameter></term>

<listitem>

<para>

&password.parameter.password;

</para>

<caution>

<para>

При хешировании пароля алгоритмом <constant>PASSWORD_BCRYPT</constant>

значение аргумента <parameter>password</parameter> усекается до предельной длины — 72 байтов.

</para>

</caution>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>algo</parameter></term>

<listitem>

<para>

&password.parameter.algo;

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>options</parameter></term>

<listitem>

<para>

&password.parameter.options;

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Функция возвращает хешированный пароль.

</para>

<para>

Идентификатор алгоритма, показатель вычислительной сложности и соль возвращаются в составе хеша,

поэтому не требуется хранить информацию об алгоритме и соли отдельно,

а для проверки пароля достаточно передать хеш в функцию <function>password_verify</function>.

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<para>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.4.0</entry>

<entry>

Значение по умолчанию для опции <literal>cost</literal> алгоритма

<constant>PASSWORD_BCRYPT</constant> увеличили

с <literal>10</literal> до <literal>12</literal>.

</entry>

</row>

<row>

<entry>8.3.0</entry>

<entry>

Функция <function>password_hash</function> теперь устанавливает базовое исключение

<exceptionname>Random\RandomException</exceptionname> в качестве значения свойства <property>Exception::$previous</property>,

если выбрасывается ошибка <exceptionname>ValueError</exceptionname> из-за сбоя во время генерации соли.

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

Функция <function>password_hash</function> больше не возвращает значение &false;, если возникла ошибка.

Вместо этого функция выбросит ошибку <classname>ValueError</classname>,

если алгоритм хеширования пароля недействителен, или ошибку <classname>Error</classname>,

если не получилось захешировать пароль из-за неизвестной ошибки.

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

Параметр <parameter>algo</parameter> теперь принимает значение &null;.

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

Параметр <parameter>algo</parameter> теперь ожидает строку (&string;), но всё ещё принимает

целое число (&integer;) для обратной совместимости.

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

Модуль sodium обеспечивает альтернативную реализацию паролей Argon2.

</entry>

</row>

<row>

<entry>7.3.0</entry>

<entry>

Ввели константу <constant>PASSWORD_ARGON2ID</constant>, которая добавила поддержку алгоритма хеширования паролей алгоритмом Argon2id.

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

Ввели константу <constant>PASSWORD_ARGON2I</constant>, которая добавила поддержку хеширования паролей алгоритмом Argon2i.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Пример хеширования пароля функцией <function>password_hash</function></title>

<programlisting role="php">

<![CDATA[

<?php

echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

$2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.

]]>

</screen>

</example>

</para>

<para>

<example>

<title>

Пример генерации хеша функцией <function>password_hash</function> установкой алгоритмической сложности вручную

</title>

<programlisting role="php">

<![CDATA[

<?php

$options = [

// Увеличиваем алгоритмическую сложность алгоритма bcrypt с 12 до 13

'cost' => 13,

];

echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

$2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi

]]>

</screen>

</example>

</para>

<para>

<example>

<title>Пример поиска оптимума показателя алгоритмической сложности для функции <function>password_hash</function></title>

<simpara>

Код протестирует машину и определит показатель вычислительной сложности,

с которым функция сгенерирует стойкий хеш, но не испортит пользовательский опыт

и не замедлит другие операции, которые выполняет машина.

Тестирование начинают с базового значения 11 и увеличивают показатель,

если машина не замедляет работу под нагрузкой. Код ищет максимум, при котором

хеширование не превышает 350 миллисекунд — допустимая задержка

для систем авторизации пользователей.

</simpara>

<programlisting role="php">

<![CDATA[

<?php

$timeTarget = 0.350; // 350 миллисекунд

$cost = 11;

do {

$cost++;

$start = microtime(true);

password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);

$end = microtime(true);

} while (($end - $start) < $timeTarget);

echo "Оптимальная стоимость: " . $cost - 1;

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

Оптимальная стоимость: 13

]]>

</screen>

</example>

</para>

<para>

<example>

<title>

Пример генерации хеша функцией <function>password_hash</function> алгоритмом Argon2i

</title>

<programlisting role="php">

<![CDATA[

<?php

echo 'Хеш Argon2i: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

Хеш Argon2i: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP4cmSJI1vc8lpXRW9/S0sYY2i2jHT0

]]>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<caution>

<para>

Функция автоматически создаст безопасную соль,

поэтому разработчики PHP настоятельно рекомендуют не указывать опцию salt вручную.

</para>

<para>

В PHP 7.0.0 установка значения опции <literal>salt</literal> вручную

сгенерирует предупреждение об устаревании. В PHP 8.0.0 установку пользовательской соли удалили.

</para>

</caution>

<note>

<para>

Работу функции тестируют на конкретной машине

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

с которыми при авторизации пользователей функция выполняется не дольше 350 миллисекунд.

Скрипт в предыдущем примере помогает определить оптимум алгоритмической сложности

для алгоритма bcrypt.

</para>

</note>

<note>

<simpara>

Обновление алгоритмов, которые поддерживает функция, или изменение

алгоритма по умолчанию подчиняется следующим правилам:

</simpara>

<para>

<itemizedlist>

<listitem>

<simpara>

С момента включения нового алгоритма в ядро до установки по умолчанию

прошёл 1 полный выпуск PHP.

Алгоритм, который ввели в версии 7.5.5, получит право стать алгоритмом по умолчанию

только в версии 7.7, поскольку версия 7.6 станет первым полным выпуском.

Но и другой алгоритм, который добавили бы в версии 7.6.0, тоже получил бы право стать алгоритмом

по умолчанию в версии 7.7.0.

</simpara>

</listitem>

<listitem>

<simpara>

Алгоритм по умолчанию изменяется только в полном выпуске,

например, 7.3.0 или 8.0.0, но не в промежуточных. Единственное исключение —

критическая уязвимость безопасности, которую обнаружили в текущем алгоритме по умолчанию.

</simpara>

</listitem>

</itemizedlist>

</para>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>password_verify</function></member>

<member><function>password_needs_rehash</function></member>

<member><function>crypt</function></member>

<member><function>sodium_crypto_pwhash_str</function></member>

</simplelist>

</para>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->