mirror of
https://github.com/php/doc-ru.git
synced 2025-07-22 18:26:31 +00:00
Обновление до английской версии (#526)
Co-authored-by: Sergey Panteleev <sergey@php.net>
This commit is contained in:
Mikhail Alferov
@ -16,41 +16,40 @@
|
||||
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
<function>password_hash</function> создаёт хеш пароля используя сильный,
|
||||
необратимый алгоритм хеширования.
|
||||
Функция <function>password_hash</function> создаёт хеш пароля, используя сильный необратимый алгоритм хеширования.
|
||||
</para>
|
||||
<simpara>
|
||||
В данный момент поддерживаются следующие алгоритмы:
|
||||
Поддерживаются следующие алгоритмы:
|
||||
</simpara>
|
||||
<para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<simpara>
|
||||
<constant>PASSWORD_DEFAULT</constant> - используется алгоритм bcrypt (по умолчанию с PHP 5.5.0).
|
||||
Обратите внимание, что используемый алгоритм может со временем меняться на более
|
||||
сильный, когда таковой добавляется в PHP. Соответственно и длина результата может со
|
||||
временем меняться. В связи с этим рекомендуется выбирать длину поля для хранения
|
||||
в базе данных более 60 символов (255 символов могло быть хорошим вариантом).
|
||||
<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;.
|
||||
<constant>PASSWORD_BCRYPT</constant> — будет выбран алгоритм
|
||||
<constant>CRYPT_BLOWFISH</constant>. Генерирует стандартный хеш с идентификатором "$2y$",
|
||||
совместимый с тем, который генерирует функция <function>crypt</function>.
|
||||
В результате будет сгенерирована строка длиной 60 символов&return.falseforfailure;.
|
||||
</simpara>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<simpara>
|
||||
<constant>PASSWORD_ARGON2I</constant> - Использовать алгоритм хеширования Argon2i.
|
||||
Этот алгоритм доступен только если PHP собран с поддержкой Argon2.
|
||||
<constant>PASSWORD_ARGON2I</constant> — будет выбран алгоритм хеширования Argon2i.
|
||||
Этот алгоритм будет доступен, только если PHP собран с поддержкой Argon2.
|
||||
</simpara>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<simpara>
|
||||
<constant>PASSWORD_ARGON2ID</constant> - Использовать алгоритм хеширования Argon2id.
|
||||
Этот алгоритм доступен только если PHP собран с поддержкой Argon2.
|
||||
<constant>PASSWORD_ARGON2ID</constant> — будет выбран алгоритм хеширования Argon2id.
|
||||
Этот алгоритм будет доступен, только если PHP собран с поддержкой Argon2.
|
||||
</simpara>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
@ -62,12 +61,12 @@
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>salt</literal> (<type>string</type>) - для самостоятельного задания соли для хеширования.
|
||||
Обратите внимание, что это приведёт к переопределению и предотвращению
|
||||
автоматического создания соли.
|
||||
<literal>salt</literal> (<type>string</type>) — для самостоятельного задания соли для хеширования.
|
||||
Обратите внимание, что это приведёт к переопределению и предотвратит
|
||||
автоматическое создание соли.
|
||||
</para>
|
||||
<para>
|
||||
Если не задано, то <function>password_hash</function> будет генерировать
|
||||
Если не задано, то функция <function>password_hash</function> будет генерировать
|
||||
случайную соль для каждого хешируемого пароля. Это предпочтительный
|
||||
режим работы.
|
||||
</para>
|
||||
@ -81,14 +80,14 @@
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>cost</literal> (<type>int</type>) - задаёт необходимую алгоритмическую сложность.
|
||||
Пример использования этого значения можно посмотреть на странице посвящённой
|
||||
<literal>cost</literal> (<type>int</type>) — задаёт алгоритмическую сложность.
|
||||
Пример с этой опцией можно посмотреть на странице, посвящённой
|
||||
функции <function>crypt</function>.
|
||||
</para>
|
||||
<para>
|
||||
Если не задано, то будет использовано значение по умолчанию <literal>10</literal>.
|
||||
Это хорошая базовая стоимость, но вы можете её увеличить в зависимости
|
||||
от возможностей своего оборудования.
|
||||
Если не задано, то будет выбрано значение по умолчанию: <literal>10</literal>.
|
||||
Это хорошая базовая стоимость, но можно увеличить её,
|
||||
если позволяет производительность оборудования.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
@ -101,27 +100,27 @@
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>memory_cost</literal> (<type>int</type>) - Максимальный размер
|
||||
памяти (в килобайтах), которую можно использовать для вычисления хеша Argon2.
|
||||
По умолчанию <constant>PASSWORD_ARGON2_DEFAULT_MEMORY_COST</constant>.
|
||||
<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>.
|
||||
<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>.
|
||||
<literal>threads</literal> (<type>int</type>) — количество потоков, которые
|
||||
можно задействовать для вычисления хеша Argon2.
|
||||
По умолчанию будет выбрано значение константы <constant>PASSWORD_ARGON2_DEFAULT_THREADS</constant>.
|
||||
</para>
|
||||
<warning>
|
||||
<para>
|
||||
Доступно только тогда, когда PHP использует libargon2, но не при реализации libsodium.
|
||||
Доступно только тогда, когда в PHP доступен модуль libargon2, но не при реализации libsodium.
|
||||
</para>
|
||||
</warning>
|
||||
</listitem>
|
||||
@ -141,7 +140,7 @@
|
||||
<caution>
|
||||
<para>
|
||||
Использование алгоритма <constant>PASSWORD_BCRYPT</constant> приведёт
|
||||
к обрезанию поля <parameter>password</parameter> до максимальной длины 72 байта.
|
||||
к обрезанию поля <parameter>password</parameter> до максимальной длины — 72 байта.
|
||||
</para>
|
||||
</caution>
|
||||
</listitem>
|
||||
@ -161,8 +160,8 @@
|
||||
&password.parameter.options;
|
||||
</para>
|
||||
<para>
|
||||
Если не задано, то будет использована стандартная стоимость и соль будет
|
||||
генерироваться автоматически.
|
||||
Если не задано, то будет использована стандартная стоимость, и соль будет
|
||||
сгенерирована автоматически.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
@ -175,10 +174,10 @@
|
||||
Возвращает хешированный пароль.
|
||||
</para>
|
||||
<para>
|
||||
Использованный алгоритм, стоимость и соль будут возвращены как часть хеша.
|
||||
Таким образом, информация, необходимая для проверки хеша будет в него
|
||||
Выбранный алгоритм, стоимость и соль будут возвращены как часть хеша.
|
||||
Таким образом, информация, необходимая для проверки хеша, будет в него
|
||||
включена. Это позволит функции <function>password_verify</function> проверять
|
||||
хеш без необходимости отдельного хранения информации о соли и алгоритме.
|
||||
хеш без отдельного хранения информации о соли и алгоритме.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
@ -197,9 +196,9 @@
|
||||
<row>
|
||||
<entry>8.0.0</entry>
|
||||
<entry>
|
||||
<function>password_hash</function> больше не возвращает значение &false; в случае возникновения ошибки,
|
||||
вместо этого будет выброшено исключение <classname>ValueError</classname>,
|
||||
если алгоритм хеширования пароля недействителен или <classname>Error</classname>,
|
||||
<function>password_hash</function> больше не возвращает значение &false; в случае возникновения ошибки.
|
||||
Вместо этого будет выброшено исключение <classname>ValueError</classname>,
|
||||
если алгоритм хеширования пароля недействителен, или <classname>Error</classname>,
|
||||
если хеширование пароля не удалось из-за неизвестной ошибки.
|
||||
</entry>
|
||||
</row>
|
||||
@ -212,7 +211,7 @@
|
||||
<row>
|
||||
<entry>7.4.0</entry>
|
||||
<entry>
|
||||
Параметр <parameter>algo</parameter> сейчас ожидает строку (&string;), но всё ещё принимает
|
||||
Параметр <parameter>algo</parameter> теперь ожидает строку (&string;), но всё ещё принимает
|
||||
число (&integer;) для обратной совместимости.
|
||||
</entry>
|
||||
</row>
|
||||
@ -249,12 +248,12 @@
|
||||
<![CDATA[
|
||||
<?php
|
||||
/**
|
||||
* Мы просто хотим захешировать свой пароль используя настройки по умолчанию.
|
||||
* Значит будет использован BCRYPT и результат будет 60 символов длиной.
|
||||
* Мы просто хотим захешировать пароль с настройками по умолчанию.
|
||||
* Значит, будет выбран алгоритм BCRYPT и результат будет длиной 60 символов.
|
||||
*
|
||||
* Помните, что алгоритм по умолчанию может измениться в будущем, так что
|
||||
* имеет смысл заранее позаботиться о том, чтобы система хранения хешей
|
||||
* смогла хранить более 60 символов (255 в самый раз)
|
||||
* смогла хранить более 60 символов (а лучше 255)
|
||||
*/
|
||||
echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
|
||||
?>
|
||||
@ -296,19 +295,20 @@ $2y$12$QjSH496pcT5CEbzjD/vtVeH03tfHKFy36d4J0Ltp3lRtee9HDxY3K
|
||||
|
||||
<para>
|
||||
<example>
|
||||
<title>Пример поиска хорошего значения стоимости для <function>password_hash</function></title>
|
||||
<title>Пример поиска хорошего значения стоимости для функции <function>password_hash</function></title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
/**
|
||||
* Данный код замерит скорость выполнения операции хеширования для вашего сервера
|
||||
* с разными значениями алгоритмической сложности для определения максимального
|
||||
* его значения, не приводящего к деградации производительности. Хорошее базовое
|
||||
* значение лежит в диапазоне 8-10, но если ваш сервер достаточно мощный, то можно
|
||||
* Данный код замерит скорость выполнения операции с разными значениями алгоритмической сложности хеширования
|
||||
* на вашем сервере и определит
|
||||
* его максимальное значение, не приводящее к деградации производительности. Хорошее базовое
|
||||
* значение — 10, но если ваш сервер достаточно мощный, то можно
|
||||
* задать и больше. Данный скрипт ищет максимальное значение, при котором
|
||||
* хеширование уложится в 50 миллисекунд.
|
||||
* хеширование уложится в значение ≤ 350 миллисекундам, что считается приемлемой задержкой
|
||||
* для систем, которые обрабатывают интерактивные входы.
|
||||
*/
|
||||
$timeTarget = 0.05; // 50 миллисекунд.
|
||||
$timeTarget = 0.350; // 350 миллисекунд.
|
||||
|
||||
$cost = 8;
|
||||
do {
|
||||
@ -325,14 +325,14 @@ echo "Оптимальная стоимость: " . $cost;
|
||||
&example.outputs.similar;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
Оптимальная стоимость: 10
|
||||
Оптимальная стоимость: 12
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
<example>
|
||||
<title>Пример использования <function>password_hash</function> с Argon2i</title>
|
||||
<title>Пример использования функции <function>password_hash</function> с Argon2i</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
@ -361,15 +361,15 @@ echo 'Хеш Argon2i: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);
|
||||
<para>
|
||||
Как было замечено выше, опция <literal>salt</literal> была объявлена
|
||||
устаревшей в PHP 7.0 и будет вызывать соответствующее предупреждение.
|
||||
Поддержка ручного задания соли может быть удалена в более новых версиях.
|
||||
Поддержка ручного задания соли была удалена в PHP 8.0.
|
||||
</para>
|
||||
</caution>
|
||||
<note>
|
||||
<para>
|
||||
Рекомендуется протестировать данную функцию на вашем железе для определения
|
||||
Рекомендуется протестировать данную функцию на вашем оборудовании для определения
|
||||
оптимального значения алгоритмической сложности. Убедитесь, что с выбранной
|
||||
сложностью функция выполняется быстрее 100 миллисекунд для интерактивных
|
||||
систем. Скрипт показанный выше поможет вам выбрать подходящее значение.
|
||||
сложностью функция выполняется быстрее 350 миллисекунд для интерактивных
|
||||
систем. Скрипт в приведённом выше примере поможет выбрать оптимальное значение.
|
||||
</para>
|
||||
</note>
|
||||
<note>
|
||||
@ -387,14 +387,14 @@ echo 'Хеш Argon2i: ' . password_hash('rasmuslerdorf', PASSWORD_ARGON2I);
|
||||
7.5.5, то задать по умолчанию его можно будет только в 7.7 (7.6 будет тем самым
|
||||
полным релизом, в течение которого он должен присутствовать, от 7.6.0 до 7.7.0). Но
|
||||
если новый алгоритм добавлен в 7.6.0, то его также можно будет задать по умолчанию
|
||||
в 7.7.0.
|
||||
в версии 7.7.0.
|
||||
</simpara>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<simpara>
|
||||
Алгоритм по умолчанию может быть изменён только в полном релизе
|
||||
(7.3.0, 8.0.0, и т.д.), но не в промежуточных. Единственное исключение - это
|
||||
если в текущем алгоритме найдена критическая уязвимость.
|
||||
(7.3.0, 8.0.0 и т. д.), но не в промежуточных. Единственное исключение —
|
||||
это критическая уязвимость, найденная в текущем алгоритме.
|
||||
</simpara>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- EN-Revision: 39148ec514f3868668483448015e8b97b3265953 Maintainer: rjhdby Status: ready -->
|
||||
<!-- EN-Revision: ff492e168a557e4dd17574023b7c3cb21b14df3b Maintainer: rjhdby Status: ready -->
|
||||
<!-- Reviewed: no -->
|
||||
<refentry xml:id="function.password-needs-rehash" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<refnamediv>
|
||||
@ -75,7 +75,7 @@
|
||||
<row>
|
||||
<entry>7.4.0</entry>
|
||||
<entry>
|
||||
Параметр <parameter>algo</parameter> сейчас ожидает строку (&string;), но всё ещё принимает
|
||||
Параметр <parameter>algo</parameter> теперь ожидает строку (&string;), но всё ещё принимает
|
||||
число (&integer;) для обратной совместимости.
|
||||
</entry>
|
||||
</row>
|
||||
@ -97,16 +97,18 @@
|
||||
$password = 'rasmuslerdorf';
|
||||
$hash = '$2y$10$YCFsG6elYca568hBi2pZ0.3LDL5wjgxct1N8w/oLR/jfHsiQwCqTS';
|
||||
|
||||
// Параметр стоимости может изменяться в связи со сменой оборудования
|
||||
$options = array('cost' => 11);
|
||||
$algorithm = PASSWORD_BCRYPT;
|
||||
// Значение bcrypt-стоимости может измениться по мере роста производительности оборудования
|
||||
$options = ['cost' => 12];
|
||||
|
||||
// Проверка сохранённого хеша с помощью пароля
|
||||
// Сравниваем сохранённый хеш с открытым паролем
|
||||
if (password_verify($password, $hash)) {
|
||||
// Проверяем, не нужно ли использовать более новый алгоритм
|
||||
// или другую алгоритмическую стоимость
|
||||
if (password_needs_rehash($hash, PASSWORD_DEFAULT, $options)) {
|
||||
// Если таки да, перехешируем и сохраняем новый хеш
|
||||
$newHash = password_hash($password, PASSWORD_DEFAULT, $options);
|
||||
// Проверяем, не изменился ли алгоритм или параметры
|
||||
if (password_needs_rehash($hash, $algorithm, $options)) {
|
||||
// Если были изменения, перехешируем и заменяем старый хеш новым
|
||||
$newHash = password_hash($password, $algorithm, $options);
|
||||
|
||||
// Обновляем запись пользователя новым $newHash
|
||||
}
|
||||
|
||||
// Авторизуем пользователя
|
||||
|
||||
Reference in New Issue
Block a user