Skip to content

Commit 89b09cd

Browse files
zonuexeKentarouTakeda
zonuexe
and
KentarouTakeda
authored
doc-enの差分を反映(4) (#142)
* 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 <[email protected]> * Update chapters/intro.xml Co-authored-by: KentarouTakeda <[email protected]> * Update reference/openssl/functions/openssl-open.xml Co-authored-by: KentarouTakeda <[email protected]> * Update reference/openssl/functions/openssl-seal.xml Co-authored-by: KentarouTakeda <[email protected]> * Update reference/openssl/functions/openssl-seal.xml Co-authored-by: KentarouTakeda <[email protected]> * fixup! Update and fix docs for openssl_open and openssl_seal --------- Co-authored-by: KentarouTakeda <[email protected]>
1 parent b8b21af commit 89b09cd

File tree

9 files changed

+140
-92
lines changed

9 files changed

+140
-92
lines changed

‎chapters/intro.xml

Lines changed: 23 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<!-- EN-Revision: 132cf39aedc8655f451233f15034bbfe39302936 Maintainer: hirokawa Status: ready -->
3+
<!-- EN-Revision: 77f5f3b3a8bbe1ad7727201c7603d1419dd7840f Maintainer: hirokawa Status: ready -->
44
<!-- CREDITS: shimooka,takagi -->
55
<chapter xml:id="introduction" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
6-
<title>入門</title>
6+
<info>
7+
<titleabbrev>入門</titleabbrev>
8+
<title>PHP は何ができるものですか?</title>
9+
</info>
710

8-
<section xml:id="intro-whatis">
11+
<section xml:id="intro-whatis" annotations="chunk:false">
912
<title>PHP とはなんでしょう?</title>
1013
<simpara>
1114
<acronym>PHP</acronym> (<emphasis>PHP: Hypertext Preprocessor</emphasis>
@@ -40,28 +43,28 @@
4043
</para>
4144
<para>
4245
HTMLを出力するために多くのコマンドを記述する (C や Perl のように)
43-
代わりに、PHP のページは "何か"
46+
代わりに、PHP のページは <replaceable>何か</replaceable>
4447
(この例では、<computeroutput>Hi, I'm a PHP script!</computeroutput> と出力)
4548
を行うコードを HTML に埋め込むことになります。
4649
PHP のコードは特別な <link
4750
linkend="language.basic-syntax.phpmode">開始および終了の処理命令
4851
<code>&lt;?php</code> と <code>?&gt;</code></link>
49-
で囲まれており、これによって "PHP モード" の切り替えを行います。
52+
で囲まれており、これによって <quote>PHP モード</quote> の切り替えを行います。
5053
</para>
5154
<para>
5255
PHP がクライアントサイド JavaScript のようなものと異なっている点は、
5356
コードがサーバーで実行され、その結果がクライアントに送信されるということです。
5457
クライアントは、スクリプトを実行した結果を受け取りますが、
5558
その出力を作成したコードがどんなものなのかを知ることはできません。
5659
全てのHTMLファイルをPHPで処理するようにWebサーバー
57-
を設定することさえ可能で、この場合、ユーザーが袖の内に何があるかを
58-
見分けることは不可能になることでしょう。
60+
を設定することさえ可能で、この場合、ユーザーはPHPが動いていることすら
61+
知ることができません。
5962
</para>
6063
<para>
6164
PHPを使用する上で最も優れている点は、初心者に対しては非常に分かり
62-
易いと同時に、プロフェッショナルのプログラマに対しては多くの進んだ
65+
やすいと同時に、プロフェッショナルのプログラマに対しては多くの進んだ
6366
機能を提供している点です。PHPの機能を羅列した長い一覧表を読まなけ
64-
ればならないのかと心配する必要はありません。PHPはすぐに始められま
67+
ればならないのかと心配する必要はありません。PHPは誰でもすぐに始められま
6568
すし、時間を掛けずに簡単なスクリプトが書けるようになります。
6669
</para>
6770
<para>
@@ -73,7 +76,7 @@
7376
</para>
7477
</section>
7578

76-
<section xml:id="intro-whatcando">
79+
<section xml:id="intro-whatcando" annotations="chunk:false">
7780
<title>PHPにできることは?</title>
7881
<para>
7982
あらゆることができます。PHPでは主にサーバーサイドでの活用に焦点が
@@ -87,14 +90,12 @@
8790
<itemizedlist>
8891
<listitem>
8992
<simpara>
90-
サーバーサイドでのスクリプティング。これは最も古くからあり
93+
サーバーサイドでのスクリプティング。これは幅広く使われていて
9194
PHPの中心となる分野です。ここでPHPを動作させるには
9295
3つのものが必要です。PHPパーサ(CGIもしくはサーバーモジュール)、
93-
ウェブサーバー、そしてブラウザです。ウェブサーバーは
94-
インストールされたPHPと連結して起動されなければなりません。
95-
ブラウザでウェブサーバーにアクセスし、PHPページを閲覧することで
96-
PHPプログラムの出力を得ることが出来ます。<link
97-
linkend="install">インストール手順</link>の章に詳しい
96+
ウェブサーバー、そしてブラウザです。これらはいずれもローカルマシンで
97+
実行して PHP プログラミングを試すことができます。
98+
<link linkend="install">インストール手順</link>の章に詳しい
9899
情報があります。
99100
</simpara>
100101
</listitem>
@@ -103,8 +104,8 @@
103104
コマンドラインでのスクリプティング。PHPスクリプトは
104105
サーバーもブラウザも無しで動作させるようにすることも出来ます。
105106
この場合、PHPパーサだけが必要となります。このタイプは
106-
cron(Windowsではタスクスケジューラ)を使用して一定間隔で
107-
スクリプトを実行したい場合や、ちょっとした文書処理を
107+
<command>cron</command>(Unix および macOS) やタスクスケジューラ(Windows)を使用して
108+
一定間隔で スクリプトを実行したい場合や、ちょっとした文書処理を
108109
行うのに最適な方法です。<link linkend="features.commandline">
109110
コマンドラインでPHPを使う</link>の章に詳しい情報があります。
110111
</simpara>
@@ -122,8 +123,8 @@
122123
CGI としても動作します。
123124
</para>
124125
<para>
125-
つまりPHPを使用する場合にはOSとウェブサーバーを自由に選ぶことが出来ます。
126-
さらに手続き型のプログラミングかオブジェクト指向のプログラミングか、
126+
つまり、PHPでは開発者が OS とウェブサーバーを自由に選ぶことができます。
127+
さらには手続き型プログラミングかオブジェクト指向プログラミングか、
127128
もしくはそれらを混在させるかといった選択を行うこともできます。
128129
</para>
129130
<para>
@@ -174,8 +175,8 @@
174175
などのように PHP のマニュアルに記載されていないものもあります。
175176
</para>
176177
<para>
177-
お分かりの通り、このページではPHPの機能やPHPを使用することの利点を全て
178-
紹介することは出来ません。<link linkend="install">PHPのインストール
178+
このページだけではPHPの機能やPHPを使用することの利点を全て
179+
紹介することはできません。<link linkend="install">PHPのインストール
179180
</link>の章を読んでみてください。紹介された拡張モジュールに関しては<link
180181
linkend="funcref">関数リファレンス</link>を読んでみてください。
181182
</para>

‎reference/openssl/functions/openssl-decrypt.xml

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<!-- EN-Revision: 6ad22de1921790bfccc8c9a2590a48ab63bf8dd3 Maintainer: satoruyoshida Status: ready -->
3+
<!-- EN-Revision: e5ab2937efd9b1d7184993e0fdfa957893f7f827 Maintainer: satoruyoshida Status: ready -->
44
<!-- Credits: mumumu -->
55
<refentry xml:id="function.openssl-decrypt" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
66
<refnamediv>
@@ -22,7 +22,7 @@
2222
</methodsynopsis>
2323
<para>
2424
未加工の、または base64 エンコードされた文字列を受け取り、
25-
与えられた暗号化方式とキーを使って文字列を復号します。
25+
与えられた暗号化方式とパスフレーズを使って文字列を復号します。
2626
</para>
2727

2828
</refsect1>
@@ -52,8 +52,16 @@
5252
<term><parameter>passphrase</parameter></term>
5353
<listitem>
5454
<para>
55-
キー
55+
パスフレーズ。パスフレーズが期待するよりも短い場合は、暗黙的に <literal>NUL</literal>
56+
文字でパディングされます。パスフレーズが予想より長い場合、暗黙的に切り詰められます。
5657
</para>
58+
<caution>
59+
<simpara>
60+
パスフレーズは、その名前から連想されるような安全な鍵生成機能は内包していません。
61+
内部で処理される唯一の操作は、期待する鍵長と異なる場合に <literal>NUL</literal> で
62+
パディングしたり、切り詰めたりするだけです。
63+
</simpara>
64+
</caution>
5765
</listitem>
5866
</varlistentry>
5967
<varlistentry>
@@ -70,7 +78,9 @@
7078
<term><parameter>iv</parameter></term>
7179
<listitem>
7280
<para>
73-
NULL ではない初期化ベクトル
81+
&null; ではない初期化ベクトル。 IV が期待よりも短い場合は、<literal>NUL</literal>
82+
文字でパディングされ、警告が発行されます。
83+
パスフレーズが期待よりも長い場合は、切り捨てられ、警告が発行されます。
7484
</para>
7585
</listitem>
7686
</varlistentry>

‎reference/openssl/functions/openssl-dh-compute-key.xml

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<!-- EN-Revision: 5bc68add3da3cd18c40f851e944b15095d3a26aa Maintainer: satoruyoshida Status: ready -->
3+
<!-- EN-Revision: 296d45da275cca752dd920738fd119e55fbbde97 Maintainer: satoruyoshida Status: ready -->
44
<!-- Credits: mumumu -->
55
<refentry xml:id="function.openssl-dh-compute-key" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
66
<refnamediv>
@@ -20,6 +20,12 @@
2020
リモート側と秘密の通信をするための暗号鍵としてよく使われます。
2121
これはディフィー・ヘルマン鍵共有として知られています。
2222
</para>
23+
<caution>
24+
<para>
25+
リモートとローカルのキーペアに同じ DH パラメータを使用することが重要です。
26+
そうしないと、両者の間で生成されたシークレットが一致しなくなります。
27+
</para>
28+
</caution>
2329
<note>
2430
<simpara>
2531
ECDH は、PHP 8.1.0 以降、<emphasis>かつ</emphasis>

‎reference/openssl/functions/openssl-encrypt.xml

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<!-- EN-Revision: 6ad22de1921790bfccc8c9a2590a48ab63bf8dd3 Maintainer: satoruyoshida Status: ready -->
3+
<!-- EN-Revision: 7a016103e0d568448f5985dfd945092d69d5d59c Maintainer: satoruyoshida Status: ready -->
44
<!-- Credits: mumumu -->
55
<refentry xml:id="function.openssl-encrypt" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
66
<refnamediv>
@@ -22,7 +22,7 @@
2222
<methodparam choice="opt"><type>int</type><parameter>tag_length</parameter><initializer>16</initializer></methodparam>
2323
</methodsynopsis>
2424
<para>
25-
与えられた文字列を与えられたメソッドとキーで暗号化して、
25+
与えられた文字列を与えられたメソッドとパスフレーズで暗号化して、
2626
未加工の、または base64 エンコードされた文字列を返します。
2727
</para>
2828
</refsect1>
@@ -58,6 +58,13 @@
5858
期待された長さより長かった場合は、
5959
黙って切り詰められます。
6060
</para>
61+
<caution>
62+
<simpara>
63+
パスフレーズは、その名前から連想されるような安全な鍵生成機能は内包していません。
64+
内部で処理される唯一の操作は、期待する鍵長と異なる場合に <literal>NUL</literal> で
65+
パディングしたり、切り詰めたりするだけです。
66+
</simpara>
67+
</caution>
6168
</listitem>
6269
</varlistentry>
6370
<varlistentry>
@@ -74,7 +81,9 @@
7481
<term><parameter>iv</parameter></term>
7582
<listitem>
7683
<para>
77-
NULL ではない初期化ベクトル。
84+
&null; ではない初期化ベクトル。 IV が期待よりも短い場合は、<literal>NUL</literal>
85+
文字でパディングされ、警告が発行されます。
86+
パスフレーズが期待よりも長い場合は、切り捨てられ、警告が発行されます。
7887
</para>
7988
</listitem>
8089
</varlistentry>

‎reference/openssl/functions/openssl-open.xml

Lines changed: 25 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<!-- EN-Revision: 5bc68add3da3cd18c40f851e944b15095d3a26aa Maintainer: hirokawa Status: ready -->
3+
<!-- EN-Revision: 730fd5c3dd1523bb9330762084ce016d4e58e946 Maintainer: hirokawa Status: ready -->
44
<!-- CREDITS: takagi,mumumu -->
55
<refentry xml:id="function.openssl-open" xmlns="http://docbook.org/ns/docbook">
66
<refnamediv>
@@ -20,14 +20,14 @@
2020
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>iv</parameter><initializer>&null;</initializer></methodparam>
2121
</methodsynopsis>
2222
<para>
23-
<function>openssl_open</function> は、キー ID
24-
<parameter>private_key</parameter> およびエンベロープキー
25-
<parameter>encrypted_key</parameter> に関連する公開鍵を使用して、
23+
<function>openssl_open</function> は、 <parameter>private_key</parameter> を使用して
24+
<parameter>encrypted_key</parameter> から復号されたエンベロープキーによって
2625
<parameter>data</parameter> をオープン(復号)します。
27-
その上で、<parameter>output</parameter> を復号化したデータで埋めます。
28-
エンベロープキーは、データがシール(暗号化)された際に生成され、特定の
29-
一つの公開鍵でのみ使用することが可能です。詳細な情報については、
30-
<function>openssl_seal</function> を参照ください。
26+
復号は <parameter>cipher_algo</parameter> と <parameter>iv</parameter> を使用して行なわれます。
27+
IV は暗号方式が要求する場合にのみ必要です。復号されたデータは <parameter>output</parameter> に
28+
格納されます。エンベロープキーは通常、秘密鍵に関連付けられた公開鍵を用いてデータがシール(暗号化)
29+
されたときに生成されます。
30+
詳細は <function>openssl_seal</function> を参照ください。
3131
</para>
3232
</refsect1>
3333

@@ -39,39 +39,42 @@
3939
<term><parameter>data</parameter></term>
4040
<listitem>
4141
<para>
42+
シール(暗号化)されたデータ。
4243
</para>
4344
</listitem>
4445
</varlistentry>
4546
<varlistentry>
4647
<term><parameter>output</parameter></term>
4748
<listitem>
4849
<para>
49-
成功した場合、オープンしたデータをここに返します。
50+
成功した場合、オープンしたデータをこのパラメータのリファレンス変数として返します。
5051
</para>
5152
</listitem>
5253
</varlistentry>
5354
<varlistentry>
5455
<term><parameter>encrypted_key</parameter></term>
5556
<listitem>
5657
<para>
58+
<parameter>private_key</parameter> を用いて復号できる暗号化された対称鍵。
5759
</para>
5860
</listitem>
5961
</varlistentry>
6062
<varlistentry>
6163
<term><parameter>private_key</parameter></term>
6264
<listitem>
6365
<para>
66+
<parameter>encrypted_key</parameter>の復号に用いられる秘密鍵。
6467
</para>
6568
</listitem>
6669
</varlistentry>
6770
<varlistentry>
6871
<term><parameter>cipher_algo</parameter></term>
6972
<listitem>
7073
<para>
71-
暗号化方式
74+
<parameter>data</parameter>の復号に使用される暗号化方式。
7275
<caution>
7376
<simpara>
74-
デフォルト値 (<literal>'RC4'</literal>) はセキュアでない値です。
77+
PHP 8.0 より前のデフォルト値 (<literal>'RC4'</literal>) は安全ではありません。
7578
明示的にセキュアな暗号化方式を指定することを強く推奨します。
7679
</simpara>
7780
</caution>
@@ -82,7 +85,9 @@
8285
<term><parameter>iv</parameter></term>
8386
<listitem>
8487
<para>
85-
初期化ベクトル。
88+
<parameter>data</parameter>の復号に用いられる初期化ベクトル。暗号方式が IV を要求する場合に必要です。
89+
これは <parameter>cipher_algo</parameter> で <function>openssl_cipher_iv_length</function>
90+
を呼び出すことで確認できます。
8691
</para>
8792
</listitem>
8893
</varlistentry>
@@ -139,24 +144,19 @@
139144
<programlisting role="php">
140145
<![CDATA[
141146
<?php
142-
// $sealed および $env_key に暗号化されたデータおよびエンベロープキー
143-
// が含まれていると仮定。共にシール元(暗号化側)から与えられる。
144147
145-
// ファイルから公開鍵を取得し、使用可能とする
146-
$fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
147-
$priv_key = fread($fp, 8192);
148-
fclose($fp);
149-
$pkeyid = openssl_get_privatekey($priv_key);
148+
// $sealed, $env_key および $iv に暗号化されたデータおよびエンベロープキーと
149+
// IV が含まれていると仮定。すべてシール元(暗号化側)から与えられる。
150+
151+
// private_key.pem に置かれたファイルから公開鍵を取得する
152+
$pkey = openssl_get_privatekey("file://private_key.pem");
150153
151154
// データを復号化し、$open に保存
152-
if (openssl_open($sealed, $open, $env_key, $pkeyid)) {
153-
echo "here is the opened data: ", $open;
155+
if (openssl_open($sealed, $open, $env_key, $pkey, 'AES256', $iv)) {
156+
echo "Here is the opened data: ", $open;
154157
} else {
155-
echo "failed to open data";
158+
echo "Failed to open data";
156159
}
157-
158-
// 公開鍵をメモリから開放
159-
openssl_free_key($pkeyid);
160160
?>
161161
]]>
162162
</programlisting>

‎reference/openssl/functions/openssl-pbkdf2.xml

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<!-- $Revision$ -->
3-
<!-- EN-Revision: 5bc68add3da3cd18c40f851e944b15095d3a26aa Maintainer: takagi Status: ready -->
3+
<!-- EN-Revision: 5136ca8abac85850155a0ae7375124a52917b240 Maintainer: takagi Status: ready -->
44
<!-- Credits: mumumu -->
55

66
<refentry xml:id="function.openssl-pbkdf2" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
@@ -40,7 +40,7 @@
4040
<term><parameter>salt</parameter></term>
4141
<listitem>
4242
<para>
43-
PBKDF2 は、暗号化のソルトとして、少なくとも64ビット(8バイト)を推奨しています。
43+
PBKDF2 は、暗号化のソルトとして、少なくとも128ビット(16バイト)を推奨しています。
4444
</para>
4545
</listitem>
4646
</varlistentry>
@@ -56,8 +56,11 @@
5656
<term><parameter>iterations</parameter></term>
5757
<listitem>
5858
<para>
59-
イテレーションの回数。
60-
<link xlink:href="https://pages.nist.gov/800-63-3/sp800-63b.html#sec5">NIST は少なくとも10000を推奨しています</link>.
59+
反復回数。
60+
<link xlink:href="https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf">
61+
NIST は最低でも1000を推奨</link>しています。
62+
2023 年の時点で、OWASP は PBKDF2-HMAC-SHA256 に対して 600,000 回、
63+
PBKDF2-HMAC-SHA512 に対して 210,000 回の反復を推奨しています。
6164
</para>
6265
</listitem>
6366
</varlistentry>
@@ -67,7 +70,7 @@
6770
<para>
6871
オプションのハッシュまたはダイジェストアルゴリズム。
6972
アルゴリズムの一覧は、<function>openssl_get_md_methods</function> で得られます。
70-
デフォルトは SHA-1 です。
73+
デフォルトは SHA-1 ですが、SHA-256 または SHA-512 を推奨しています。
7174
</para>
7275
</listitem>
7376
</varlistentry>

0 commit comments

Comments
 (0)