mirror of
https://github.com/php/doc-ru.git
synced 2025-07-22 18:26:31 +00:00
443 lines
18 KiB
XML
443 lines
18 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
||
<!-- $Revision$ -->
|
||
<!-- EN-Revision: 79c06cc0e7872f1401a4c37dc9298b0bedb0dde4 Maintainer: rjhdby Status: ready -->
|
||
<!-- Reviewed: yes -->
|
||
|
||
<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><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> создаёт хеш пароля используя сильный,
|
||
необратимый алгоритм хеширования.
|
||
Функция <function>password_hash</function> совместима с функцией
|
||
<function>crypt</function>.
|
||
Следовательно, хеши паролей, созданные <function>crypt</function> можно использовать
|
||
с <function>password_hash</function>.
|
||
</para>
|
||
<simpara>
|
||
В данный момент поддерживаются следующие алгоритмы:
|
||
</simpara>
|
||
<para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<simpara>
|
||
<constant>PASSWORD_DEFAULT</constant> - используется алгоритм bcrypt (по умолчанию с PHP 5.5.0).
|
||
Обратите внимание, что используемый алгоритм может со временем меняться на более
|
||
сильный, когда таковой добавляется в PHP. Соответственно и длина результата может со
|
||
временем меняться. В связи с этим рекомендуется выбирать длину поля для хранения
|
||
в базе данных более 60 символов (255 символов могло быть хорошим вариантом).
|
||
</simpara>
|
||
</listitem>
|
||
<listitem>
|
||
<simpara>
|
||
<constant>PASSWORD_BCRYPT</constant> - использует алгоритм
|
||
<constant>CRYPT_BLOWFISH</constant>. Генерирует стандартный хеш, совместимый
|
||
с генерированным функцией <function>crypt</function> с использованием
|
||
идентификатора "$2y$". В результате будет сгенерирована строка длиной 60 символов&return.falseforfailure;.
|
||
</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>
|
||
Эта опция объявлена устаревшей.
|
||
Рекомендуется использовать автоматически генерируемую соль.
|
||
Начиная с PHP 8.0.0 явно заданная соль игнорируется.
|
||
</para>
|
||
</warning>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<literal>cost</literal> (<type>int</type>) - задаёт необходимую алгоритмическую сложность.
|
||
Пример использования этого значения можно посмотреть на странице посвящённой
|
||
функции <function>crypt</function>.
|
||
</para>
|
||
<para>
|
||
Если не задано, то будет использовано значение по умолчанию <literal>10</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>
|
||
<para>
|
||
Если не задано, то будет использована стандартная стоимость и соль будет
|
||
генерироваться автоматически.
|
||
</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.0.0</entry>
|
||
<entry>
|
||
<function>password_hash</function> больше не возвращает &false; в случае возникновения ошибки.
|
||
</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>
|
||
Добавлена поддержка алгоритма хеширования паролей Argon2id с помощью <constant>PASSWORD_ARGON2ID</constant>.
|
||
</entry>
|
||
</row>
|
||
<row>
|
||
<entry>7.2.0</entry>
|
||
<entry>
|
||
Добавлена поддержка хеширующего алгоритма Argon2i с помощью <constant>PASSWORD_ARGON2I</constant>.
|
||
</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
|
||
/**
|
||
* Мы просто хотим захешировать свой пароль используя настройки по умолчанию.
|
||
* Значит будет использован BCRYPT и результат будет 60 символов длиной.
|
||
*
|
||
* Помните, что алгоритм по умолчанию может измениться в будущем, так что
|
||
* имеет смысл заранее позаботиться о том, чтобы система хранения хешей
|
||
* смогла хранить более 60 символов (255 в самый раз)
|
||
*/
|
||
echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
&example.outputs.similar;
|
||
<screen>
|
||
<![CDATA[
|
||
$2y$10$.vGA1O9wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a
|
||
]]>
|
||
</screen>
|
||
</example>
|
||
</para>
|
||
<para>
|
||
<example>
|
||
<title>Пример использования <function>password_hash</function> с ручным заданием стоимости</title>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
/**
|
||
* Тут мы увеличиваем алгоритмическую стоимость BCRYPT до 12.
|
||
* Но это никак не скажется на длине полученного результата, она останется 60 символов
|
||
*/
|
||
$options = [
|
||
'cost' => 12,
|
||
];
|
||
echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
&example.outputs.similar;
|
||
<screen>
|
||
<![CDATA[
|
||
$2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K
|
||
]]>
|
||
</screen>
|
||
</example>
|
||
</para>
|
||
|
||
<para>
|
||
<example>
|
||
<title>Пример поиска хорошего значения стоимости для <function>password_hash</function></title>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
/**
|
||
* Данный код замерит скорость выполнения операции хеширования для вашего сервера
|
||
* с разными значениями алгоритмической сложности для определения максимального
|
||
* его значения, не приводящего к деградации производительности. Хорошее базовое
|
||
* значение лежит в диапазоне 8-10, но если ваш сервер достаточно мощный, то можно
|
||
* задать и больше. Данный скрипт ищет максимальное значение, при котором
|
||
* хеширование уложится в 50 миллисекунд.
|
||
*/
|
||
$timeTarget = 0.05; // 50 миллисекунд.
|
||
|
||
$cost = 8;
|
||
do {
|
||
$cost++;
|
||
$start = microtime(true);
|
||
password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);
|
||
$end = microtime(true);
|
||
} while (($end - $start) < $timeTarget);
|
||
|
||
echo "Оптимальная стоимость: " . $cost;
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
&example.outputs.similar;
|
||
<screen>
|
||
<![CDATA[
|
||
Оптимальная стоимость: 10
|
||
]]>
|
||
</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>
|
||
Настоятельно рекомендуется использовать автоматическую генерацию соли.
|
||
Данная функция самостоятельно создаст хорошую соль, если вы не будете ей мешать
|
||
подсовывая свою.
|
||
</para>
|
||
<para>
|
||
Как было замечено выше, опция <literal>salt</literal> была объявлена
|
||
устаревшей в PHP 7.0 и будет вызывать соответствующее предупреждение.
|
||
Поддержка ручного задания соли может быть удалена в более новых версиях.
|
||
</para>
|
||
</caution>
|
||
<note>
|
||
<para>
|
||
Рекомендуется протестировать данную функцию на вашем железе для определения
|
||
оптимального значения алгоритмической сложности. Убедитесь, что с выбранной
|
||
сложностью функция выполняется быстрее 100 миллисекунд для интерактивных
|
||
систем. Скрипт показанный выше поможет вам выбрать подходящее значение.
|
||
</para>
|
||
</note>
|
||
<note>
|
||
<simpara>
|
||
Обновление поддерживаемых алгоритмов для этой функции (или изменение значения по
|
||
умолчанию) обязаны следовать правилам:
|
||
</simpara>
|
||
<para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<simpara>
|
||
Любой новый алгоритм должен присутствовать в ядре как минимум
|
||
1 полный релиз PHP для того, чтобы его можно было установить по умолчанию.
|
||
Таким образом, если, к примеру, новый алгоритм был добавлен в
|
||
7.5.5, то задать по умолчанию его можно будет только в 7.7 (7.6 будет тем самым
|
||
полным релизом, в течение которого он должен присутствовать, от 7.6.0 до 7.7.0). Но
|
||
если новый алгоритм добавлен в 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>crypt</function></member>
|
||
<member><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.password.compat;">Пользовательская реализация</link></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
|
||
-->
|