[reference/password] sync with en

Author: mumumu

reference/password/constants.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: c6532951edb85836f2d49a3c81f8f5e1e41d3554 Maintainer: takagi Status: ready -->
+<!-- EN-Revision: 66aff414be91c5a0446be585aa6ac78121de1e67 Maintainer: takagi Status: ready -->
 <!-- Credits: mumumu -->
 
 <appendix xml:id="password.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
@@ -44,7 +44,7 @@
         値の例については <function>crypt</function> のページを参照ください。
        </para>
        <para>
-        省略した場合のデフォルトは <literal>10</literal> です。この値でもかまいませんが、
+        省略した場合のデフォルトは <literal>12</literal> です。この値でもかまいませんが、
         ハードウェアの性能が許すならもう少し高くすることもできます。
        </para>
       </listitem>
@@ -183,7 +183,7 @@
    <varlistentry xml:id="constant.password-default">
     <term>
      <constant>PASSWORD_DEFAULT</constant>
-     (<type>mixed</type>)
+     (<type>string</type>)
     </term>
     <listitem>
      <para>
@@ -192,22 +192,15 @@
       その時点でより強力なハッシュアルゴリズムに対応していればデフォルトが変わる可能性があります。
      </para>
      <para>
-      この定数の値は、今後変わる可能性がある (きっと変わる) ことに注意しましょう。
+      この定数の値は、今後変わる可能性があることに注意しましょう。
       つまり、生成されるハッシュの長さも変わる可能性があるということです。
       したがって、<constant>PASSWORD_DEFAULT</constant> を使う場合は、
-      ハッシュの格納先は 60 文字以上でも格納できるようにしておく必要があります
-      (255 文字程度にしておくことをおすすめします)。
-     </para>
-     <para>
-      この定数の値
+      ハッシュの格納先は任意の長さのハッシュを格納できるようにしておく必要があります。
+      お勧めの長さは <literal>255</literal> バイトです。
      </para>
-     <itemizedlist>
-      <listitem>
-       <simpara>
-        PHP 5.5.0 - <constant>PASSWORD_BCRYPT</constant>
-       </simpara>
-      </listitem>
-     </itemizedlist>
+     <simpara>
+      現状は、<constant>PASSWORD_BCRYPT</constant> のエイリアスです。
+     </simpara>
     </listitem>
    </varlistentry>
   </variablelist>

reference/password/functions/password-hash.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: e302f07943465892db7f72469e2ce9b42c4f763f Maintainer: takagi Status: ready -->
+<!-- EN-Revision: 5003a6ea92eb50ac92121782eedfc5ad3fe9d061 Maintainer: takagi Status: ready -->
 <!-- Credits: mumumu -->
 <refentry xml:id="function.password-hash" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -33,16 +33,15 @@
       この定数もそれにあわせて変わっていきます。
       そのため、これを指定したときの結果の長さは、変わる可能性があります。
       したがって、結果をデータベースに格納するときにはカラム幅を
-      60 文字以上にできるようなカラムを使うことをお勧めします
-      (255 文字くらいが適切でしょう)。
+      60 バイト以上にできるようなカラムを使うことをお勧めします
+      (255 バイトくらいが適切でしょう)。
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <constant>PASSWORD_BCRYPT</constant> - bcrypt アルゴリズムを使ってハッシュを作ります。
       これは標準の <function>crypt</function>
       互換のハッシュで、識別子 <literal>$2y$</literal> を使った場合の結果を作ります。
-      その結果は、常に 60 文字の文字列になります。&return.falseforfailure;。
      </simpara>
     </listitem>
     <listitem>
@@ -91,7 +90,7 @@
 
      <para>
       省略した場合のデフォルトは <literal>12</literal> です。この値でもかまいませんが、
-      ハードウェアの性能に応じて調整することもできます。
+      ハードウェアの性能に応じて調整すべきです。
      </para>
     </listitem>
    </itemizedlist>
@@ -265,13 +264,6 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-/**
- * デフォルトのアルゴリズムを使ってパスワードをハッシュします。
- * 現時点でのデフォルトは BCRYPT で、その結果は 60 文字になります。
- *
- * デフォルトは、今後変わる可能性があることに注意しましょう。結果が
- * 60 文字以上になっても対応できるようにしておきましょう (255 あたりが適切です)
- */
 echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
 ?>
 ]]>
@@ -290,10 +282,8 @@ $2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.
     <programlisting role="php">
 <![CDATA[
 <?php
-/**
- * この例では、bcrypt のコストを上げて、13 にします。
- */
 $options = [
+    // bcrypt のコストを 12 から 13 に増やします
     'cost' => 13,
 ];
 echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
@@ -311,16 +301,21 @@ $2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi
   <para>
    <example>
     <title><function>password_hash</function> で、適切なコストを探す例</title>
+    <simpara>
+     このコードは、サーバーをベンチマークして、
+     ユーザー体験を悪化させることなく、
+     どの程度のコストに耐えられるかを判断します。
+     サーバーに負荷をかけすぎない範囲で、
+     できるだけ高めのコストを設定することをお勧めします。
+     基準として 11 程度からはじめ、サーバーが十分に高速なら、
+     できるだけ上げていきましょう。
+     以下のコードでは、
+     ストレッチングの時間を 350 ミリ秒以内にすることを狙っています。
+     対話形式のログインを扱う際の許容時間としては、このあたりが適切でしょう。
+    </simpara>
     <programlisting role="php">
 <![CDATA[
 <?php
-/**
- * このコードは、サーバーをベンチマークして、どの程度のコストに耐えられるかを判断します。
- * サーバーに負荷をかけすぎない範囲で、できるだけ高めのコストを設定したいものです。
- * 基準として 11 程度からはじめ、サーバーが十分に高速なら、できるだけ上げていきましょう。
- * 以下のコードでは、ストレッチングの時間を 350 ミリ秒以内にすることを狙っています。
- * 対話形式のログインを扱う際の許容時間としては、このあたりが適切でしょう。
- */
 $timeTarget = 0.350; // 350 ミリ秒
 
 $cost = 11;
@@ -331,7 +326,7 @@ do {
     $end = microtime(true);
 } while (($end - $start) < $timeTarget);
 
-echo "Appropriate Cost Found: " . $cost;
+echo "Appropriate Cost Found: " . $cost - 1;
 ?>
 ]]>
     </programlisting>
@@ -378,8 +373,8 @@ Argon2i hash: $argon2i$v=19$m=1024,t=2,p=2$YzJBSzV4TUhkMzc3d3laeg$zqU/1IN0/AogfP
   <note>
    <para>
     実際にサーバー上でこの関数をテストして、コストパラメータの適切な設定値を調整することをお勧めします。
-    対話型のシステムなら、関数の実行時間が 350 ミリ秒くらいに収まるくらいが適切です。
-    先ほどの例のスクリプトは、自分のハードウェア上での適切なコストを判断するための助けとなるでしょう。
+    対話型のログインを行わせる場合、関数の実行時間が 350 ミリ秒くらいに収まるくらいが適切です。
+    先ほどの例のスクリプトは、自分のハードウェア上での適切な bcrypt のコストを判断するための助けとなるでしょう。
    </para>
   </note>
   <note>

reference/password/functions/password-verify.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: e302f07943465892db7f72469e2ce9b42c4f763f Maintainer: takagi Status: ready -->
+<!-- EN-Revision: 5baba54a67be43d689970983cfc6d24debad1ce0 Maintainer: takagi Status: ready -->
 <refentry xml:id="function.password-verify" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>password_verify</refname>
@@ -100,7 +100,6 @@ Password is valid!
    <simplelist>
     <member><function>password_needs_rehash</function></member>
     <member><function>password_hash</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_verify</function></member>
    </simplelist>
   </para>

reference/password/setup.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 39b10b2e994f5a39f5face56c5e86ea8507a45a3 Maintainer: takagi Status: ready -->
+<!-- EN-Revision: 2417d61a29a32b4d495e0df7c25c026e0035a428 Maintainer: takagi Status: ready -->
 
 <chapter xml:id="password.setup" xmlns:xlink="http://www.w3.org/1999/xlink">
  &reftitle.setup;
@@ -24,7 +24,8 @@
    <option role="configure">--with-password-argon2</option> オプションを使用し
    libargon2 のサポートを有効にして PHP をビルドする必要があります。
    PHP 8.4.0 以降で libargon2 の代わりに OpenSSL を使う場合、
-   <option role="configure">--with-openssl</option> オプションを使用し
+   <option role="configure">--with-openssl</option> と
+   <option role="configure">--with-openssl-argon2</option> オプションを使用し
    OpenSSL を有効にして PHP をビルドする必要があります。
   </para>
   <para>