<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect2 id="zend.filter.set.encrypt">
    <title>Encrypt 及び Decrypt</title>

    <para>
        これらのフィルタにより、与えられた文字列を暗号化したり復号化できます。
        したがって、それらはアダプタを利用します。
        実際には、<acronym>PHP</acronym> 由来の <classname>Mcrypt</classname>
        および <classname>OpenSSL</classname> エクステンション用のアダプタを使用します。
    </para>

    <sect3 id="zend.filter.set.encrypt.options">
        <title>Zend_Filter_Encrypt および Zend_Filter_Decrypt でサポートされるオプション</title>

        <para>
            <classname>Zend_Filter_Encrypt</classname> および
            <classname>Zend_Filter_Decrypt</classname> では、下記のオプションがサポートされます。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis><property>adapter</property></emphasis>:
                    使用する暗号化アダプタを設定します。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>algorithm</property></emphasis>:
                    <classname>MCrypt</classname> のみ。
                    使用するアルゴリズム
                    <ulink url="http://php.net/mcrypt">PHP の mcrypt 暗号</ulink>
                    であげられている暗号化アルゴリズムのいずれかでなければなりません。
                    省略した場合のデフォルトは <property>blowfish</property> です。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>algorithm_directory</property></emphasis>:
                    <classname>MCrypt</classname> のみ。
                    アルゴリズムが存在するディレクトリ。
                    省略した場合のデフォルトは、mcrypt エクステンション内に設定されたパスです。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>compression</property></emphasis>:
                    暗号化した値を圧縮するかどうか。既定値は圧縮なし。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>envelope</property></emphasis>:
                    <classname>OpenSSL</classname> のみ。
                    コンテンツを暗号化した人から受け取った、
                    暗号化されたエンベロープ鍵。
                    鍵ファイルのパスとファイル名を指定するか、
                    あるいは単に鍵ファイルの内容そのものを指定することもできます。
                    <property>package</property> オプションが設定された場合、
                    このパラメータは省略できます。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>key</property></emphasis>:
                    <classname>MCrypt</classname> のみ。
                    暗号化用の鍵。
                    入力を暗号化する際に使用します。
                    復号する際にも同じ鍵が必要です。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>mode</property></emphasis>:
                    <classname>MCrypt</classname> のみ。
                    使用する暗号化モード。
                    <ulink url="http://php.net/mcrypt">PHP の mcrypt 暗号</ulink>
                    であげられているモードのいずれかでなければなりません。
                    省略した場合のデフォルトは 'cbc' です。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>mode_directory</property></emphasis>:
                    <classname>MCrypt</classname> のみ。
                    モードが存在するディレクトリ。
                    省略した場合のデフォルトは、<classname>Mcrypt</classname>
                    拡張モジュールで設定されているパスです。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>package</property></emphasis>:
                    <classname>OpenSSL</classname> のみ。
                    暗号化された値と一緒にエンベロープ鍵が梱包されるべきかどうか
                    デフォルトは <constant>FALSE</constant> です。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>private</property></emphasis>:
                    <classname>OpenSSL</classname> のみ。
                    コンテンツの暗号化に使用する、あなたの秘密鍵。
                    鍵ファイルのパスとファイル名を指定するか、
                    あるいは単に鍵ファイルの内容そのものを指定することもできます。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>public</property></emphasis>:
                    <classname>OpenSSL</classname> のみ。
                    暗号化したコンテンツを渡したい相手の公開鍵。
                    複数の公開鍵を指定するには、配列を使用します。
                    鍵ファイルのパスとファイル名を指定するか、
                    あるいは単に鍵ファイルの内容そのものを指定することもできます。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>salt</property></emphasis>:
                    <classname>MCrypt</classname> のみ。
                    キーを salt 値として使用するかどうか。
                    使用すると、暗号化に使用するキー自体も暗号化されます。
                    デフォルトは <constant>FALSE</constant> です。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>vector</property></emphasis>:
                    <classname>MCrypt</classname> のみ。
                    使用する初期化ベクトル。
                    省略した場合はランダムなベクトルとなります。
                </para>
            </listitem>
        </itemizedlist>
    </sect3>

    <sect3 id="zend.filter.set.encrypt.adapterusage">
        <title>アダプタの使用法</title>

        <para>
            これら 2 つの暗号化手法はまったく異なる方式なので、
            アダプタの使用法もそれぞれ異なります。
            フィルタを初期化する際に、どのアダプタを使うかを選ばなければなりません。
        </para>

        <programlisting language="php"><![CDATA[
// Mcrypt アダプタを使用します
$filter1 = new Zend_Filter_Encrypt(array('adapter' => 'mcrypt'));

// OpenSSL アダプタを使用します
$filter2 = new Zend_Filter_Encrypt(array('adapter' => 'openssl'));
]]></programlisting>

        <para>
            別のアダプタを設定するために <methodname>setAdapter()</methodname>
            を使用することもできます。また <methodname>getAdapter()</methodname>
            メソッドで、実際に設定されているアダプタを取得できます。
        </para>

        <programlisting language="php"><![CDATA[
// Mcrypt アダプタを使用します
$filter = new Zend_Filter_Encrypt();
$filter->setAdapter('openssl');
]]></programlisting>

        <note>
            <para>
                <property>adapter</property> オプションを指定しなかったり <methodname>setAdapter()</methodname>
                を使用しなかったりした場合は、デフォルトで
                <classname>Mcrypt</classname> アダプタを使用します。
            </para>
        </note>
    </sect3>

    <sect3 id="zend.filter.set.encrypt.mcrypt">
        <title>Mcrypt での暗号化</title>

        <para>
            <classname>Mcrypt</classname> 拡張モジュールをインストールすると、
            <classname>Mcrypt</classname> アダプタが使えるようになります。
            もしオプション配列の代わりに文字列を与えると、
            文字列がキーとして使われます。
        </para>

        <para>
            初期化した後で暗号化の値を取得したり設定したりするには、それぞれ
            <methodname>getEncryption()</methodname> および <methodname>setEncryption()</methodname>
            メソッドを使用します。
        </para>

        <note>
            <para>
                mcrypt 拡張モジュールが使用できない場合は例外が発生することに注意しましょう。
            </para>
        </note>

        <note>
            <para>
                また、インスタンス作成時あるいは <methodname>setEncryption()</methodname>
                をコールした際にすべての設定がチェックされることにも注意しましょう。
                設定内容に問題があることを mcrypt が検知すると、例外がスローされます。
            </para>
        </note>

        <para>
            暗号化ベクトルの取得や設定には、それぞれ <methodname>getVector()</methodname>
            および <methodname>setVector()</methodname> を使用可能です。指定した文字列が、
            そのアルゴリズムに必要なベクトルのサイズに応じて切り詰められたり伸ばされたりします。
        </para>

        <note>
            <para>
                自前のベクトル以外を使用する場合は、
                そのベクトルを取得してどこかに保存しておかなければならないことに注意しましょう。
                そうしないと、文字列が復号できなくなります。
            </para>
        </note>

        <programlisting language="php"><![CDATA[
// デフォルト設定の blowfish を使用します
$filter = new Zend_Filter_Encrypt('myencryptionkey');

// 自前のベクトルを設定します。それ以外の場合は getVector()
// をコールしてベクトルを保存しておかないと、後で復号できなくなります
$filter->setVector('myvector');
// $filter->getVector();

$encrypted = $filter->filter('text_to_be_encoded');
print $encrypted;

// 復号の方法は Decrypt フィルタを参照ください
]]></programlisting>
    </sect3>

    <sect3 id="zend.filter.set.encrypt.mcryptdecrypt">
        <title>Mcrypt の復号</title>
        <para>
            <classname>Mcrypt</classname> で暗号化したコンテンツを復号するには、
            暗号化を行った際に指定したオプションが必要です。
        </para>

        <para>
            ここでひとつ暗号化時との大きな違いがあります。
            暗号化の際にベクトルを指定しなかった場合は、コンテンツを暗号化した後で
            フィルタの <methodname>getVector()</methodname> メソッドを使用してベクトルを取得する必要があります。
            正しいベクトルがなければ、コンテンツを復号することはできません。
        </para>

        <para>
            オプションを指定しさえすれば、復号は暗号化と同じくらい単純なことです。
        </para>

        <programlisting language="php"><![CDATA[
// デフォルト設定の blowfish を使用します
$filter = new Zend_Filter_Decrypt('myencryptionkey');

// コンテンツの暗号化用ベクトルを設定します
$filter->setVector('myvector');

$decrypted = $filter->filter('encoded_text_normally_unreadable');
print $decrypted;
]]></programlisting>

        <note>
            <para>
                mcrypt 拡張モジュールが使用できない場合は例外が発生することに注意しましょう。
            </para>
        </note>

        <note>
            <para>
                また、インスタンス作成時あるいは <methodname>setEncryption()</methodname>
                をコールした際にすべての設定がチェックされることにも注意しましょう。
                設定内容に問題があることを mcrypt が検知すると、例外がスローされます。
            </para>
        </note>
    </sect3>

    <sect3 id="zend.filter.set.encrypt.openssl">
        <title>OpenSSL での暗号化</title>

        <para>
            <classname>OpenSSL</classname> 拡張モジュールをインストールすると、
            <classname>OpenSSL</classname> アダプタが使えるようになります。
            後から公開鍵を取得あるいは設定するには、<methodname>getPublicKey()</methodname>
            および <methodname>setPublicKey()</methodname> メソッドを使用します。
            秘密鍵についても、<methodname>getPrivateKey()</methodname> および <methodname>setPrivateKey()</methodname>
            メソッドで取得あるいは設定できます。
        </para>

        <programlisting language="php"><![CDATA[
// openssl を使用し、秘密鍵を指定します
$filter = new Zend_Filter_Encrypt(array(
    'adapter' => 'openssl',
    'private' => '/path/to/mykey/private.pem'
));

// もちろん、初期化時に公開鍵を指定することもできます
$filter->setPublicKey(array(
    '/public/key/path/first.pem',
    '/public/key/path/second.pem'
));
]]></programlisting>

        <note>
            <para>
                <classname>OpenSSL</classname> アダプタは、正しい鍵を渡さないと動作しないことに注意しましょう。
            </para>
        </note>

        <para>
            鍵自体も暗号化したい場合は、パスフレーズを
            <methodname>setPassphrase()</methodname> メソッドで渡します。
            パスフレーズつきで暗号化したコンテンツを復号したい場合は、
            公開鍵だけではなく (暗号化された鍵を復号するための) パスフレーズも必要となります。
        </para>

        <programlisting language="php"><![CDATA[
// openssl を使用し、秘密鍵を指定します
$filter = new Zend_Filter_Encrypt(array(
    'adapter' => 'openssl',
    'private' => '/path/to/mykey/private.pem'
));

// もちろん、初期化時に公開鍵を指定することもできます
$filter->setPublicKey(array(
    '/public/key/path/first.pem',
    '/public/key/path/second.pem'
));
$filter->setPassphrase('mypassphrase');
]]></programlisting>

        <para>
            最後に、OpenSSL を使用した場合に受け手に渡す必要があるものをまとめます。
            暗号化されたコンテンツ、パスフレーズを使用した場合はそのパスフレーズ、
            そして復号用のエンベロープ鍵。これらが必要となります。
        </para>

        <para>
            つまり、暗号化を終えたらエンベロープ鍵を取得する必要があるということです。
            取得するには <methodname>getEnvelopeKey()</methodname> メソッドを使用します。
        </para>

        <para>
            <classname>OpenSSL</classname> でコンテンツの暗号化を行う完全な例は、このようになります。
        </para>

        <programlisting language="php"><![CDATA[
// openssl を使用し、秘密鍵を指定します
$filter = new Zend_Filter_Encrypt(array(
    'adapter' => 'openssl',
    'private' => '/path/to/mykey/private.pem'
));

// もちろん、初期化時に公開鍵を指定することもできます
$filter->setPublicKey(array(
    '/public/key/path/first.pem',
    '/public/key/path/second.pem'
));
$filter->setPassphrase('mypassphrase');

$encrypted = $filter->filter('text_to_be_encoded');
$envelope  = $filter->getEnvelopeKey();
print $encrypted;

// 復号の方法は Decrypt フィルタを参照ください
]]></programlisting>

        <sect4 id="zend.filter.set.encrypt.openssl.simplified">
            <title>Openssl と一緒に簡単に使う方法</title>

            <!-- TODO : to be translated -->
            <para>
                As seen before, you need to get the envelope key to be able to decrypt the previous
                encrypted value. This can be very annoying when you work with multiple values.
            </para>

            <para>
                To have a simplified usage you can set the <property>package</property> option to
                <constant>TRUE</constant>. The default value is <constant>FALSE</constant>.
            </para>

            <programlisting language="php"><![CDATA[
// openssl を使用し、秘密鍵を指定します
$filter = new Zend_Filter_Encrypt(array(
    'adapter' => 'openssl',
    'private' => '/path/to/mykey/private.pem',
    'public'  => '/public/key/path/public.pem',
    'package' => true
));

$encrypted = $filter->filter('text_to_be_encoded');
print $encrypted;

// 復号の方法は Decrypt フィルタを参照ください
]]></programlisting>

            <!-- TODO : to be translated -->
            <para>
                Now the returned value contains the encrypted value and the envelope. You don't
                need to get them after the compression. But, and this is the negative aspect of
                this feature, the encrypted value can now only be decrypted by using
                <classname>Zend_Filter_Encrypt</classname>.
            </para>
        </sect4>

        <sect4 id="zend.filter.set.encrypt.openssl.compressed">
            <title>コンテンツの圧縮</title>

            <para>
                Based on the original value, the encrypted value can be a very large string. To
                reduce the value <classname>Zend_Filter_Encrypt</classname> allows the usage of
                compression.
            </para>

            <para>
                The <property>compression</property> option can eighter be set to the name of a
                compression adapter, or to an array which sets all wished options for the
                compression adapter.
            </para>

            <programlisting language="php"><![CDATA[
// Use basic compression adapter
$filter1 = new Zend_Filter_Encrypt(array(
    'adapter'     => 'openssl',
    'private'     => '/path/to/mykey/private.pem',
    'public'      => '/public/key/path/public.pem',
    'package'     => true,
    'compression' => 'bz2'
));

// Use basic compression adapter
$filter2 = new Zend_Filter_Encrypt(array(
    'adapter'     => 'openssl',
    'private'     => '/path/to/mykey/private.pem',
    'public'      => '/public/key/path/public.pem',
    'package'     => true,
    'compression' => array('adapter' => 'zip', 'target' => '\usr\tmp\tmp.zip')
));
]]></programlisting>

            <note>
                <title>同一設定での復号化</title>

                <para>
                    When you want to decrypt a value which is additionally compressed, then you
                    need to set the same compression settings for decryption as for encryption.
                    Otherwise the decryption will fail.
                </para>
            </note>
        </sect4>
    </sect3>

    <sect3 id="zend.filter.set.encrypt.openssldecrypt">
        <title>OpenSSL での復号</title>

        <para>
            <classname>OpenSSL</classname> での復号は、暗号化と同様にシンプルです。
            しかし、コンテンツを暗号化した人からすべてのデータを受け取る必要があります。
            下記の例をご覧ください。
        </para>

        <programlisting language="php"><![CDATA[
// openssl を使用し、秘密鍵を指定します
$filter = new Zend_Filter_Decrypt(array(
    'adapter' => 'openssl',
    'private' => '/path/to/mykey/private.pem'
));

// もちろん、初期化時にエンベロープ鍵を指定することもできます
$filter->setEnvelopeKey(array(
    '/key/from/encoder/first.pem',
    '/key/from/encoder/second.pem'
));
]]></programlisting>

        <note>
            <para>
                <classname>OpenSSL</classname> アダプタは、正しい鍵を渡さないと動作しないことに注意しましょう。
            </para>
        </note>

        <para>
            オプションで、パスフレーズを渡さなければ鍵を復号できないようにすることもできます。
            そのために使用するのが <methodname>setPassphrase()</methodname> メソッドです。
        </para>

        <programlisting language="php"><![CDATA[
// openssl を使用し、秘密鍵を指定します
$filter = new Zend_Filter_Decrypt(array(
    'adapter' => 'openssl',
    'private' => '/path/to/mykey/private.pem'
));

// もちろん、初期化時にエンベロープ鍵を指定することもできます
$filter->setEnvelopeKey(array(
    '/key/from/encoder/first.pem',
    '/key/from/encoder/second.pem'
));
$filter->setPassphrase('mypassphrase');
]]></programlisting>

        <para>
            最後に、コンテンツを復号します。
            暗号化したコンテンツの復号を行う完全な例は、このようになります。
        </para>

        <programlisting language="php"><![CDATA[
// openssl を使用し、秘密鍵を指定します
$filter = new Zend_Filter_Decrypt(array(
    'adapter' => 'openssl',
    'private' => '/path/to/mykey/private.pem'
));

// もちろん、初期化時にエンベロープ鍵を指定することもできます
$filter->setEnvelopeKey(array(
    '/key/from/encoder/first.pem',
    '/key/from/encoder/second.pem'
));
$filter->setPassphrase('mypassphrase');

$decrypted = $filter->filter('encoded_text_normally_unreadable');
print $decrypted;
]]></programlisting>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->