Обновление до английской версии (#526)

Co-authored-by: Sergey Panteleev <sergey@php.net>

reference/password/functions/password-hash.xml

@@ -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).
+      <constant>PASSWORD_DEFAULT</constant> — будет выбран алгоритм bcrypt (по умолчанию с PHP 5.5.0).
-      Обратите внимание, что используемый алгоритм может со временем меняться на более
+      Обратите внимание, алгоритм может измениться на более
-      сильный, когда таковой добавляется в PHP. Соответственно и длина результата может со
+      сильный, когда такой добавится в PHP. При изменении алгоритма и длина результата
-      временем меняться. В связи с этим рекомендуется выбирать длину поля для хранения
+      также может измениться. Поэтому длину поля для хранения
-      в базе данных более 60 символов (255 символов могло быть хорошим вариантом).
+      в базе данных лучше устанавливать более 60 символов (255 символов будет хорошим значением).
      </simpara>
     </listitem>
     <listitem>
      <simpara>
-      <constant>PASSWORD_BCRYPT</constant> - использует алгоритм
+      <constant>PASSWORD_BCRYPT</constant> — будет выбран алгоритм
-      <constant>CRYPT_BLOWFISH</constant>. Генерирует стандартный хеш, совместимый
+      <constant>CRYPT_BLOWFISH</constant>. Генерирует стандартный хеш с идентификатором "$2y$",
-      с генерированным функцией <function>crypt</function> с использованием
+      совместимый с тем, который генерирует функция <function>crypt</function>.
-      идентификатора "$2y$". В результате будет сгенерирована строка длиной 60 символов&return.falseforfailure;.
+      В результате будет сгенерирована строка длиной 60 символов&return.falseforfailure;.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
-      <constant>PASSWORD_ARGON2I</constant> - Использовать алгоритм хеширования Argon2i.
+      <constant>PASSWORD_ARGON2I</constant> — будет выбран алгоритм хеширования Argon2i.
-      Этот алгоритм доступен только если PHP собран с поддержкой Argon2.
+      Этот алгоритм будет доступен, только если PHP собран с поддержкой Argon2.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
-      <constant>PASSWORD_ARGON2ID</constant> - Использовать алгоритм хеширования Argon2id.
+      <constant>PASSWORD_ARGON2ID</constant> — будет выбран алгоритм хеширования Argon2id.
-      Этот алгоритм доступен только если PHP собран с поддержкой Argon2.
+      Этот алгоритм будет доступен, только если 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>) - Максимальный размер
+      <literal>memory_cost</literal> (<type>int</type>) — максимальный размер
-      памяти (в килобайтах), которую можно использовать для вычисления хеша Argon2.
+      памяти (в килобайтах), которая будет использована для вычисления хеша Argon2.
-      По умолчанию <constant>PASSWORD_ARGON2_DEFAULT_MEMORY_COST</constant>.
+      По умолчанию будет выбрано значение константы <constant>PASSWORD_ARGON2_DEFAULT_MEMORY_COST</constant>.
      </para>
     </listitem>
     <listitem>
      <para>
-      <literal>time_cost</literal> (<type>int</type>) - Максимально возможное время,
+      <literal>time_cost</literal> (<type>int</type>) — максимально возможное время,
-      которое можно потратить для вычисления хеша Argon2.
+      которое можно потратить на вычисление хеша Argon2.
-      По умолчанию <constant>PASSWORD_ARGON2_DEFAULT_TIME_COST</constant>.
+      По умолчанию будет выбрано значение константы <constant>PASSWORD_ARGON2_DEFAULT_TIME_COST</constant>.
      </para>
     </listitem>
     <listitem>
      <para>
-      <literal>threads</literal> (<type>int</type>) - Количество потоков, которые
+      <literal>threads</literal> (<type>int</type>) — количество потоков, которые
-      можно использовать для вычисления хеша Argon2.
+      можно задействовать для вычисления хеша Argon2.
-      По умолчанию <constant>PASSWORD_ARGON2_DEFAULT_THREADS</constant>.
+      По умолчанию будет выбрано значение константы <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; в случае возникновения ошибки,
+        <function>password_hash</function> больше не возвращает значение &false; в случае возникновения ошибки.
-        вместо этого будет выброшено исключение <classname>ValueError</classname>,
+        Вместо этого будет выброшено исключение <classname>ValueError</classname>,
-        если алгоритм хеширования пароля недействителен или <classname>Error</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>

reference/password/functions/password-needs-rehash.xml

@@ -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';
 
-// Параметр стоимости может изменяться в связи со сменой оборудования
+$algorithm = PASSWORD_BCRYPT;
-$options = array('cost' => 11);
+// Значение bcrypt-стоимости может измениться по мере роста производительности оборудования
+$options = ['cost' => 12];
 
-// Проверка сохранённого хеша с помощью пароля
+// Сравниваем сохранённый хеш с открытым паролем
 if (password_verify($password, $hash)) {
-    // Проверяем, не нужно ли использовать более новый алгоритм
+    // Проверяем, не изменился ли алгоритм или параметры
-    // или другую алгоритмическую стоимость
+    if (password_needs_rehash($hash, $algorithm, $options)) {
-    if (password_needs_rehash($hash, PASSWORD_DEFAULT, $options)) {
+        // Если были изменения, перехешируем и заменяем старый хеш новым
-        // Если таки да, перехешируем и сохраняем новый хеш
+        $newHash = password_hash($password, $algorithm, $options);
-        $newHash = password_hash($password, PASSWORD_DEFAULT, $options);
+
+        // Обновляем запись пользователя новым $newHash
     }
 
     // Авторизуем пользователя