doc-enの差分を反映(4) (#142)

zonuexe · KentarouTakeda · web-flow · commit 89b09cd4c205 · 2024-11-11T08:27:26.000+09:00
* Stop chunking the Introduction, add titleabbrev+title, write-through to remove 'you' php/doc-en@77f5f3b * add Zip::ER_TRUNCATED_ZIP php/doc-en@8afee82 * Update recommendations for openssl_pbkdf2 php/doc-en@5136ca8 * Add caution about openssl_pkey_derive key_length parameter * Add caution about openssl_pkey_derive key_length parameter * Fix typo in reference/openssl/functions/openssl-pkey-derive.xml php/doc-en@7fd8e59 * Add caution about using the same DH params in openssl_dh_compute_key php/doc-en@296d45d * Clarify passphrase for openssl_encrypt and openssl_decrypt php/doc-en@e5ab293 php/doc-en@7a01610 * Update and fix docs for openssl_open and openssl_seal php/doc-en@110ac43 php/doc-en@730fd5c * Update chapters/intro.xml Co-authored-by: KentarouTakeda <takeda@youmind.jp> * Update chapters/intro.xml Co-authored-by: KentarouTakeda <takeda@youmind.jp> * Update reference/openssl/functions/openssl-open.xml Co-authored-by: KentarouTakeda <takeda@youmind.jp> * Update reference/openssl/functions/openssl-seal.xml Co-authored-by: KentarouTakeda <takeda@youmind.jp> * Update reference/openssl/functions/openssl-seal.xml Co-authored-by: KentarouTakeda <takeda@youmind.jp> * fixup! Update and fix docs for openssl_open and openssl_seal --------- Co-authored-by: KentarouTakeda <takeda@youmind.jp>
diff --git a/chapters/intro.xml b/chapters/intro.xml
@@ -1,11 +1,14 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 132cf39aedc8655f451233f15034bbfe39302936 Maintainer: hirokawa Status: ready -->
+<!-- EN-Revision: 77f5f3b3a8bbe1ad7727201c7603d1419dd7840f Maintainer: hirokawa Status: ready -->
 <!-- CREDITS: shimooka,takagi -->
  <chapter xml:id="introduction" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
-  <title>入門</title>
+  <info>
+   <titleabbrev>入門</titleabbrev>
+   <title>PHP は何ができるものですか?</title>
+  </info>
 
-  <section xml:id="intro-whatis">
+  <section xml:id="intro-whatis" annotations="chunk:false">
    <title>PHP とはなんでしょう?</title>
    <simpara>
     <acronym>PHP</acronym> (<emphasis>PHP: Hypertext Preprocessor</emphasis>
@@ -40,28 +43,28 @@
    </para>
    <para>
     HTMLを出力するために多くのコマンドを記述する (C や Perl のように)
-    代わりに、PHP のページは "何か"
+    代わりに、PHP のページは <replaceable>何か</replaceable>
     (この例では、<computeroutput>Hi, I'm a PHP script!</computeroutput> と出力)
     を行うコードを HTML に埋め込むことになります。
     PHP のコードは特別な <link
     linkend="language.basic-syntax.phpmode">開始および終了の処理命令
     <code>&lt;?php</code> と <code>?&gt;</code></link>
-    で囲まれており、これによって "PHP モード" の切り替えを行います。
+    で囲まれており、これによって <quote>PHP モード</quote> の切り替えを行います。
    </para>
    <para>
     PHP がクライアントサイド JavaScript のようなものと異なっている点は、
     コードがサーバーで実行され、その結果がクライアントに送信されるということです。
     クライアントは、スクリプトを実行した結果を受け取りますが、
     その出力を作成したコードがどんなものなのかを知ることはできません。
     全てのHTMLファイルをPHPで処理するようにWebサーバー
-    を設定することさえ可能で、この場合、ユーザーが袖の内に何があるかを
-    見分けることは不可能になることでしょう。
+    を設定することさえ可能で、この場合、ユーザーはPHPが動いていることすら
+    知ることができません。
    </para>
    <para>
     PHPを使用する上で最も優れている点は、初心者に対しては非常に分かり
-    易いと同時に、プロフェッショナルのプログラマに対しては多くの進んだ
+    やすいと同時に、プロフェッショナルのプログラマに対しては多くの進んだ
     機能を提供している点です。PHPの機能を羅列した長い一覧表を読まなけ
-    ればならないのかと心配する必要はありません。PHPはすぐに始められま
+    ればならないのかと心配する必要はありません。PHPは誰でもすぐに始められま
     すし、時間を掛けずに簡単なスクリプトが書けるようになります。
    </para>
    <para>
@@ -73,7 +76,7 @@
    </para>
   </section>
 
-  <section xml:id="intro-whatcando">
+  <section xml:id="intro-whatcando" annotations="chunk:false">
    <title>PHPにできることは?</title>
    <para>
     あらゆることができます。PHPでは主にサーバーサイドでの活用に焦点が
@@ -87,14 +90,12 @@
     <itemizedlist>
      <listitem>
       <simpara>
-       サーバーサイドでのスクリプティング。これは最も古くからあり
+       サーバーサイドでのスクリプティング。これは幅広く使われていて
        PHPの中心となる分野です。ここでPHPを動作させるには
        3つのものが必要です。PHPパーサ(CGIもしくはサーバーモジュール)、
-       ウェブサーバー、そしてブラウザです。ウェブサーバーは
-       インストールされたPHPと連結して起動されなければなりません。
-       ブラウザでウェブサーバーにアクセスし、PHPページを閲覧することで
-       PHPプログラムの出力を得ることが出来ます。<link
-       linkend="install">インストール手順</link>の章に詳しい
+       ウェブサーバー、そしてブラウザです。これらはいずれもローカルマシンで
+       実行して PHP プログラミングを試すことができます。
+       <link linkend="install">インストール手順</link>の章に詳しい
        情報があります。
       </simpara>
      </listitem>
@@ -103,8 +104,8 @@
        コマンドラインでのスクリプティング。PHPスクリプトは
        サーバーもブラウザも無しで動作させるようにすることも出来ます。
        この場合、PHPパーサだけが必要となります。このタイプは
-       cron(Windowsではタスクスケジューラ)を使用して一定間隔で
-       スクリプトを実行したい場合や、ちょっとした文書処理を
+       <command>cron</command>(Unix および macOS) やタスクスケジューラ(Windows)を使用して
+       一定間隔で スクリプトを実行したい場合や、ちょっとした文書処理を
        行うのに最適な方法です。<link linkend="features.commandline">
        コマンドラインでPHPを使う</link>の章に詳しい情報があります。
       </simpara>
@@ -122,8 +123,8 @@
     CGI としても動作します。
    </para>
    <para>
-    つまりPHPを使用する場合にはOSとウェブサーバーを自由に選ぶことが出来ます。
-    さらに手続き型のプログラミングかオブジェクト指向のプログラミングか、
+    つまり、PHPでは開発者が OS とウェブサーバーを自由に選ぶことができます。
+    さらには手続き型プログラミングかオブジェクト指向プログラミングか、
     もしくはそれらを混在させるかといった選択を行うこともできます。
    </para>
    <para>
@@ -174,8 +175,8 @@
     などのように PHP のマニュアルに記載されていないものもあります。
    </para>
    <para>
-    お分かりの通り、このページではPHPの機能やPHPを使用することの利点を全て
-    紹介することは出来ません。<link linkend="install">PHPのインストール
+    このページだけではPHPの機能やPHPを使用することの利点を全て
+    紹介することはできません。<link linkend="install">PHPのインストール
     </link>の章を読んでみてください。紹介された拡張モジュールに関しては<link
     linkend="funcref">関数リファレンス</link>を読んでみてください。
    </para>
diff --git a/reference/openssl/functions/openssl-decrypt.xml b/reference/openssl/functions/openssl-decrypt.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 6ad22de1921790bfccc8c9a2590a48ab63bf8dd3 Maintainer: satoruyoshida Status: ready -->
+<!-- EN-Revision: e5ab2937efd9b1d7184993e0fdfa957893f7f827 Maintainer: satoruyoshida Status: ready -->
 <!-- Credits: mumumu -->
 <refentry xml:id="function.openssl-decrypt" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -22,7 +22,7 @@
   </methodsynopsis>
   <para>
    未加工の、または base64 エンコードされた文字列を受け取り、
-   与えられた暗号化方式とキーを使って文字列を復号します。
+   与えられた暗号化方式とパスフレーズを使って文字列を復号します。
   </para>
 
  </refsect1>
@@ -52,8 +52,16 @@
      <term><parameter>passphrase</parameter></term>
      <listitem>
       <para>
-       キー
+       パスフレーズ。パスフレーズが期待するよりも短い場合は、暗黙的に <literal>NUL</literal>
+       文字でパディングされます。パスフレーズが予想より長い場合、暗黙的に切り詰められます。
       </para>
+      <caution>
+       <simpara>
+        パスフレーズは、その名前から連想されるような安全な鍵生成機能は内包していません。
+        内部で処理される唯一の操作は、期待する鍵長と異なる場合に <literal>NUL</literal> で
+        パディングしたり、切り詰めたりするだけです。
+       </simpara>
+      </caution>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -70,7 +78,9 @@
      <term><parameter>iv</parameter></term>
      <listitem>
       <para>
-       NULL ではない初期化ベクトル
+       &null; ではない初期化ベクトル。 IV が期待よりも短い場合は、<literal>NUL</literal>
+       文字でパディングされ、警告が発行されます。
+       パスフレーズが期待よりも長い場合は、切り捨てられ、警告が発行されます。
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/openssl/functions/openssl-dh-compute-key.xml b/reference/openssl/functions/openssl-dh-compute-key.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 5bc68add3da3cd18c40f851e944b15095d3a26aa Maintainer: satoruyoshida Status: ready -->
+<!-- EN-Revision: 296d45da275cca752dd920738fd119e55fbbde97 Maintainer: satoruyoshida Status: ready -->
 <!-- Credits: mumumu -->
 <refentry xml:id="function.openssl-dh-compute-key" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -20,6 +20,12 @@
    リモート側と秘密の通信をするための暗号鍵としてよく使われます。
    これはディフィー・ヘルマン鍵共有として知られています。
   </para>
+  <caution>
+   <para>
+    リモートとローカルのキーペアに同じ DH パラメータを使用することが重要です。
+    そうしないと、両者の間で生成されたシークレットが一致しなくなります。
+   </para>
+  </caution>
   <note>
    <simpara>
     ECDH は、PHP 8.1.0 以降、<emphasis>かつ</emphasis>
diff --git a/reference/openssl/functions/openssl-encrypt.xml b/reference/openssl/functions/openssl-encrypt.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 6ad22de1921790bfccc8c9a2590a48ab63bf8dd3 Maintainer: satoruyoshida Status: ready -->
+<!-- EN-Revision: 7a016103e0d568448f5985dfd945092d69d5d59c Maintainer: satoruyoshida Status: ready -->
 <!-- Credits: mumumu -->
 <refentry xml:id="function.openssl-encrypt" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -22,7 +22,7 @@
    <methodparam choice="opt"><type>int</type><parameter>tag_length</parameter><initializer>16</initializer></methodparam>
   </methodsynopsis>
   <para>
-   与えられた文字列を与えられたメソッドとキーで暗号化して、
+   与えられた文字列を与えられたメソッドとパスフレーズで暗号化して、
    未加工の、または base64 エンコードされた文字列を返します。
   </para>
  </refsect1>
@@ -58,6 +58,13 @@
        期待された長さより長かった場合は、
        黙って切り詰められます。
       </para>
+      <caution>
+       <simpara>
+        パスフレーズは、その名前から連想されるような安全な鍵生成機能は内包していません。
+        内部で処理される唯一の操作は、期待する鍵長と異なる場合に <literal>NUL</literal> で
+        パディングしたり、切り詰めたりするだけです。
+       </simpara>
+      </caution>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -74,7 +81,9 @@
      <term><parameter>iv</parameter></term>
      <listitem>
       <para>
-       NULL ではない初期化ベクトル。
+       &null; ではない初期化ベクトル。 IV が期待よりも短い場合は、<literal>NUL</literal>
+       文字でパディングされ、警告が発行されます。
+       パスフレーズが期待よりも長い場合は、切り捨てられ、警告が発行されます。
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/openssl/functions/openssl-open.xml b/reference/openssl/functions/openssl-open.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 5bc68add3da3cd18c40f851e944b15095d3a26aa Maintainer: hirokawa Status: ready -->
+<!-- EN-Revision: 730fd5c3dd1523bb9330762084ce016d4e58e946 Maintainer: hirokawa Status: ready -->
 <!-- CREDITS: takagi,mumumu -->
 <refentry xml:id="function.openssl-open" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -20,14 +20,14 @@
    <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>iv</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
   <para>
-   <function>openssl_open</function> は、キー ID
-   <parameter>private_key</parameter> およびエンベロープキー
-   <parameter>encrypted_key</parameter> に関連する公開鍵を使用して、
+   <function>openssl_open</function> は、 <parameter>private_key</parameter> を使用して
+   <parameter>encrypted_key</parameter> から復号されたエンベロープキーによって
    <parameter>data</parameter> をオープン(復号)します。
-   その上で、<parameter>output</parameter> を復号化したデータで埋めます。
-   エンベロープキーは、データがシール(暗号化)された際に生成され、特定の
-   一つの公開鍵でのみ使用することが可能です。詳細な情報については、
-   <function>openssl_seal</function> を参照ください。
+   復号は <parameter>cipher_algo</parameter> と <parameter>iv</parameter> を使用して行なわれます。
+   IV は暗号方式が要求する場合にのみ必要です。復号されたデータは <parameter>output</parameter> に
+   格納されます。エンベロープキーは通常、秘密鍵に関連付けられた公開鍵を用いてデータがシール(暗号化)
+   されたときに生成されます。
+   詳細は <function>openssl_seal</function> を参照ください。
   </para>
  </refsect1>
 
@@ -39,39 +39,42 @@
      <term><parameter>data</parameter></term>
      <listitem>
       <para>
+       シール(暗号化)されたデータ。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>output</parameter></term>
      <listitem>
       <para>
-       成功した場合、オープンしたデータをここに返します。
+       成功した場合、オープンしたデータをこのパラメータのリファレンス変数として返します。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>encrypted_key</parameter></term>
      <listitem>
       <para>
+        <parameter>private_key</parameter> を用いて復号できる暗号化された対称鍵。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>private_key</parameter></term>
      <listitem>
       <para>
+        <parameter>encrypted_key</parameter>の復号に用いられる秘密鍵。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><parameter>cipher_algo</parameter></term>
      <listitem>
       <para>
-       暗号化方式
+       <parameter>data</parameter>の復号に使用される暗号化方式。
        <caution>
         <simpara>
-         デフォルト値 (<literal>'RC4'</literal>) はセキュアでない値です。
+         PHP 8.0 より前のデフォルト値 (<literal>'RC4'</literal>) は安全ではありません。
          明示的にセキュアな暗号化方式を指定することを強く推奨します。
         </simpara>
        </caution>
@@ -82,7 +85,9 @@
      <term><parameter>iv</parameter></term>
      <listitem>
       <para>
-       初期化ベクトル。
+       <parameter>data</parameter>の復号に用いられる初期化ベクトル。暗号方式が IV を要求する場合に必要です。
+       これは <parameter>cipher_algo</parameter> で <function>openssl_cipher_iv_length</function>
+       を呼び出すことで確認できます。
       </para>
      </listitem>
     </varlistentry>
@@ -139,24 +144,19 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-// $sealed および $env_key に暗号化されたデータおよびエンベロープキー
-// が含まれていると仮定。共にシール元(暗号化側)から与えられる。
 
-// ファイルから公開鍵を取得し、使用可能とする
-$fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
-$priv_key = fread($fp, 8192);
-fclose($fp);
-$pkeyid = openssl_get_privatekey($priv_key);
+// $sealed, $env_key および $iv に暗号化されたデータおよびエンベロープキーと
+// IV が含まれていると仮定。すべてシール元(暗号化側)から与えられる。
+
+// private_key.pem に置かれたファイルから公開鍵を取得する
+$pkey = openssl_get_privatekey("file://private_key.pem");
 
 // データを復号化し、$open に保存
-if (openssl_open($sealed, $open, $env_key, $pkeyid)) {
-    echo "here is the opened data: ", $open;
+if (openssl_open($sealed, $open, $env_key, $pkey, 'AES256', $iv)) {
+    echo "Here is the opened data: ", $open;
 } else {
-    echo "failed to open data";
+    echo "Failed to open data";
 }
-
-// 公開鍵をメモリから開放
-openssl_free_key($pkeyid);
 ?>
 ]]>
     </programlisting>
diff --git a/reference/openssl/functions/openssl-pbkdf2.xml b/reference/openssl/functions/openssl-pbkdf2.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 5bc68add3da3cd18c40f851e944b15095d3a26aa Maintainer: takagi Status: ready -->
+<!-- EN-Revision: 5136ca8abac85850155a0ae7375124a52917b240 Maintainer: takagi Status: ready -->
 <!-- Credits: mumumu -->
 
 <refentry xml:id="function.openssl-pbkdf2" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
@@ -40,7 +40,7 @@
     <term><parameter>salt</parameter></term>
     <listitem>
      <para>
-       PBKDF2 は、暗号化のソルトとして、少なくとも64ビット(8バイト)を推奨しています。
+       PBKDF2 は、暗号化のソルトとして、少なくとも128ビット(16バイト)を推奨しています。
      </para>
     </listitem>
    </varlistentry>
@@ -56,8 +56,11 @@
     <term><parameter>iterations</parameter></term>
     <listitem>
      <para>
-      イテレーションの回数。 
-      <link xlink:href="https://pages.nist.gov/800-63-3/sp800-63b.html#sec5">NIST は少なくとも10000を推奨しています</link>.
+      反復回数。
+      <link xlink:href="https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf">
+      NIST は最低でも1000を推奨</link>しています。
+      2023 年の時点で、OWASP は PBKDF2-HMAC-SHA256 に対して 600,000 回、
+      PBKDF2-HMAC-SHA512 に対して 210,000 回の反復を推奨しています。
      </para>
     </listitem>
    </varlistentry>
@@ -67,7 +70,7 @@
      <para>
        オプションのハッシュまたはダイジェストアルゴリズム。
        アルゴリズムの一覧は、<function>openssl_get_md_methods</function> で得られます。
-       デフォルトは SHA-1 です。
+       デフォルトは SHA-1 ですが、SHA-256 または SHA-512 を推奨しています。
      </para>
     </listitem>
    </varlistentry>
diff --git a/reference/openssl/functions/openssl-pkey-derive.xml b/reference/openssl/functions/openssl-pkey-derive.xml
diff --git a/reference/openssl/functions/openssl-seal.xml b/reference/openssl/functions/openssl-seal.xml
diff --git a/reference/zip/constants.xml b/reference/zip/constants.xml
