<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 14978 -->
<!-- Reviewed: no -->
<sect2 id="zend.filter.set.encrypt">
    <title>Encrypt</title>
    <para>
        Dieser Filter verschlüsselt beliebige Strings mit den angegebenen Einstellungen. Hierfür verwendet er
        Adapter. Aktuell gibt es Adapter für die <code>Mcrypt</code> und <code>OpenSSL</code> Erweiterungen
        von php.
    </para>

    <para>
        Da diese zwei Verschlüsselungs-Methodologien komplett unterschiedlich arbeiten, ist auch die
        Verwendung der Adapters unterschiedlich. Man muß die Adapter den man verwenden will, bei der
        Initialisierung des Filters auswählen.
    </para>

    <programlisting role="php"><![CDATA[
// Verwenden des Mcrypt Adapters
$filter1 = new Zend_Filter_Encrypt(array('adapter' => 'mcrypt'));

// Verwendung des OpenSSL Adapters
$filter2 = new Zend_Filter_Encrypt(array('adapter' => 'openssl'));
]]>
    </programlisting>

    <para>
        Um einen anderen Adapter zu setzen kann man auch <code>setAdapter()</code> verwenden, und die
        <code>getAdapter()</code> Methode um den aktuell gesetzten Adapter zu erhalten.
    </para>

    <programlisting role="php"><![CDATA[
// Verwenden des Mcrypt Adapters
$filter = new Zend_Filter_Encrypt();
$filter->setAdapter('openssl');
]]>
    </programlisting>

    <note>
        <para>
            Wenn man die <code>adapter</code> Option nicht angibt oder setAdapter nicht verwendet, dann wird
            standardmäßig der <code>Mcrypt</code> Adapter verwendet.
        </para>
    </note>

    <sect3 id="zend.filter.set.encrypt.mcrypt">
        <title>Verschlüsselung mit Mcrypt</title>
        <para>
            Wenn man die <code>Mcrypt</code> Erweiterung installiert hat, kann man den <code>Mcrypt</code>
            Adapter verwenden. Dieser Adapter unterstützt bei der Initialisierung die folgenden Optionen:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>key</emphasis>: Der Verschlüsselungs-Schlüssel mit dem die Eingabe verschlüsselt
                    wird. Man benötigt den gleichen Schlüssel für die Entschlüsselung.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>algorithm</emphasis>: Der Algorithmus der verwendet werden soll. Das sollte einer
                    der Algorithmus Cipher sein die man unter
                    <ulink url="http://php.net/mcrypt">PHP's Mcrypt Cipers</ulink> finden kann. Wenn er nicht
                    gesetzt wird, ist er standardmäßig <code>blowfish</code>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>algorithm_directory</emphasis>: Das Verzeichnis in dem der Algorithmus gefunden
                    werden kann. Wenn es nicht gesetzt wird, ist es standardmäßig der Pfad der in der
                    Mcrypt Erweiterung gesetzt wurde.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>mode</emphasis>: Der Verschlüsselungs Modus der verwendet werden soll. Es sollte
                    einer der Modi sein der unter <ulink url="http://php.net/mcrypt">PHP's Mcrypt Modi</ulink>
                    gefunden werden kann. Wenn er nicht gesetzt wird, ist er standardmäßig <code>cbc</code>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>mode_directory</emphasis>: Der Verzeichnis in dem der Modus gefunden werden kann.
                    Wenn es nicht gesetzt wird, ist es standardmäßig der Pfad der in der <code>mcrypt</code>
                    Erweiterung gesetzt wurde.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>vector</emphasis>: Der Initialisierungs Vektor der verwendet werden soll. Wenn er
                    nicht gesetzt wird, wird ein zufälliger Vektor verwende.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Wenn man einen String statt einem Array übergibt, wird dieser String als key Option verwendet.
        </para>

        <para>
            Man kan die Verschlüsselungswerte auch im Nachhinein mit den Methoden <code>getEncryption()</code>
            und <code>setEncryption()</code> erhalten und setzen.
        </para>

        <note>
            <para>
                Es ist zu beachten das man eine Ausnahme erhält wenn die mcrypt Erweiterung in der eigenen
                Umgebung nicht vorhanden ist.
            </para>
        </note>

        <note>
            <para>
                Man sollte auch beachten das alle Einstellungen geprüft werden wenn man eine Instanz erstellt
                oder setEncryption() aufruft. Wenn mcrypt ein Problem mit diesen Einstellungen erkennt wird
                eine Ausnahme geworfen.
            </para>
        </note>

        <para>
            Man kann den Verschlüsselungs Vektor durch den Aufruf von <code>getVector()</code> und
            <code>setVector()</code> erhalten/setzen. Ein engegebener String wird, je nach benötigter Vektorgröße
            des verwendeten Algorithmus, abgeschnitten oder aufgefüllt.
        </para>

        <note>
            <para>
                Es ist zu beachten das, wenn man keinen eigenen Vektor setzt, man den Vektor holen und speichern
                muß. Andernfalls ist man nicht in der Lage den verschlüsselten String wieder zu dekodieren.
            </para>
        </note>

        <programlisting role="php"><![CDATA[
// Verwendet die standardmäßigen Blowfish Einstellungen
$filter = new Zend_Filter_Encrypt('myencryptionkey');

// Setzt einen eigenen Vektor, andernfalls muß man getVector()
// ausrufen und diesen Vektor für spätere Entschlüsselung speichern
$filter->setVector('myvector');
// $filter->getVector();

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

// Für Entschlüsselung siehe den Decrypt Filter
]]>
        </programlisting>
    </sect3>

    <sect3 id="zend.filter.set.encrypt.openssl">
        <title>Verschlüsselung mit OpenSSL</title>
        <para>
            Wenn man die <code>OpenSSL</code> Erweiterung installiert hat, kann man den <code>OpenSSL</code>
            Adapter verwenden. Dieser Adapter unterstützt bei der Instanziierung die folgenden Optionen:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>public</emphasis>: Der öffentliche Schlüssel des Benutzer dem man verschlüsselte
                    Inhalte zur Verfügung stellen will. Man kann mehrere öffentliche Schlüssel angeben indem
                    man ein Array verwendet. Man kann entweder den Pfad und den Dateinamen der Schlüsseldatei
                    angeben, oder nur den Inhalt der Schlüseldatei selbst.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>private</emphasis>: Der eigene private Schlüssel der für die Verschlüsselung des
                    Inhalts verwendet wird. Auch der private Schlüssel kann entweder ein Dateiname mit Pfad zur
                    Schlüsseldatei sein, oder nur der Inhalt der Schlüsseldatei selbst.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Man kann öffentliche Schlüssel auch im Nachhinein mit den Methoden <code>getPublicKey()</code> und
            <code>setPublicKey()</code> erhalten und setzen. Auch der private Schlüssel kann mit den
            entsprechenden Methoden <code>getPrivateKey()</code> und <code>setPrivateKey()</code> geholt und
            gesetzt werden.
        </para>

        <programlisting role="php"><![CDATA[
// Verwende openssl und gib einen privaten Schlüssel an
$filter = new Zend_Filter_Encrypt(array(
    'adapter' => 'openssl',
    'private' => '/path/to/mykey/private.pem'
));

// natürlich kann man die öffentlichen Schlüssel auch
// bei der Instanziierung angeben
$filter->setPublicKey(array(
    '/public/key/path/first.pem',
    '/public/key/path/second.pem'
));
]]>
        </programlisting>

        <note>
            <para>
                Es ist zu beachten das der <code>OpenSSL</code> Adapter nicht funktionieren wird wenn keine
                gültigen Schlüsseln angegeben werden.
            </para>
        </note>

        <para>
            Wenn man auch die Schlüssel selbst verschlüsseln will, muß man eine Passphrase mit der
            <code>setPassphrase()</code> Methode angeben. Wenn man Inhalte entschlüsseln will, die mit einer
            Passphrase verschlüsselt wurden, muß man nicht nur den öffentlichen Schlüssel, sondern auch die
            Passphrase um den verschlüsselten Schlüssel zu entschlüsseln.
        </para>

        <programlisting role="php"><![CDATA[
// Verwende openssl und gib einen privaten Schlüssel an
$filter = new Zend_Filter_Encrypt(array(
    'adapter' => 'openssl',
    'private' => '/path/to/mykey/private.pem'
));

// Natürlich kann man die öffentlichen Schlüssel
// auch bei der Instanziierung angeben
$filter->setPublicKey(array(
    '/public/key/path/first.pem',
    '/public/key/path/second.pem'
));
$filter->setPassphrase('mypassphrase');
]]>
        </programlisting>

        <para>
            Zum Schluß muß man, wenn OpenSSL verwendet wird, dem Empfänger den verschlüsselten Inhalt, die
            Passphrase, wenn eine angegeben wurde, und den Umschlagschlüssel für die Entschlüsselung angeben.
        </para>

        <para>
            Das bedeutet, das man die Umschlagschlüssel nach der Verschlüsselung mit der
            <code>getEnvelopeKey()</code> Methode holen muß.
        </para>

        <para>
            Unser komplettes Beispiel für die Verschlüsselung von Inhalten mit <code>OpenSSL</code> schaut
            wie folgt aus.
        </para>

        <programlisting role="php"><![CDATA[
// Verwende openssl und gib einen privaten Schlüssel an
$filter = new Zend_Filter_Encrypt(array(
    'adapter' => 'openssl',
    'private' => '/path/to/mykey/private.pem'
));

// natürlich kann man die öffentlichen Schlüssel
// auch bei der Instaiziierung angeben
$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;

// Für die Entschlüsselung siehe beim Decrypt Filter
]]>
        </programlisting>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->