<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 20774 -->
<!-- Reviewed: no -->
<sect2 id="zend.filter.set.encrypt">
    <title>Encrypt</title>
    <para>
        Ce filtre va crypter toute chaine avec les paramètres spécifiés. Des adaptateurs sont utilisés.
        Actuellement, il existe des adaptateurs pour les extensions PHP <code>Mcrypt</code> et
        <code>OpenSSL</code>.
    </para>

    <para>
        Comme ces deux méthodes d'encryptage sont très différentes, l'utilisation de leurs adaptateurs
        l'est aussi.
    </para>

    <programlisting language="php"><![CDATA[
// Utiliser Mcrypt
$filter1 = new Zend_Filter_Encrypt(array('adapter' => 'mcrypt'));

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

    <para>
        Les méthodes <code>setAdapter()</code> et <code>getAdapter()</code> existent aussi.
    </para>

    <programlisting language="php"><![CDATA[
// Utiliser Mcrypt
$filter = new Zend_Filter_Encrypt();
$filter->setAdapter('openssl');
]]></programlisting>

    <note>
        <para>
            Si vous ne précisez pas d'adaptateur, <code>Mcrypt</code> est utilisé par défaut.
        </para>
    </note>

    <sect3 id="zend.filter.set.encrypt.mcrypt">
        <title>Cryptage avec Mcrypt</title>
        <para>
            Cet adaptateur nécessite la présence de l'extension PHP <code>Mcrypt</code>. Voici ses options:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>key</emphasis>: La clé d'encryptage. Cette même clé sera nécessaire pour le
                    décryptage.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>algorithm</emphasis>: L'algorithme à utiliser pour le cryptage. Voyez
                    <ulink url="http://php.net/mcrypt">PHP's mcrypt ciphers</ulink>. Si non précisé,
                    <code>blowfish</code> sera utilisé par défaut.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>algorithm_directory</emphasis>: Le dossier dans lequel se trouve l'algorithme. Si
                    non précisé, le dossier spécifié par l'extension mcrypt est alors utilisé.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>mode</emphasis>: Le mode de cryptage à utiliser. Un des
                    <ulink url="http://php.net/mcrypt">modes mcrypt</ulink> doit être utilisé.
                    Par défaut, <code>cbc</code> est utilisé.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>mode_directory</emphasis>: Le dossier dans lequel se trouve le mode. Si
                    non précisé, le dossier spécifié par l'extension mcrypt est alors utilisé.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>vector</emphasis>: Le vecteur d'initialisation à utiliser. Un vecteur aléatoire
                    est utilisé si non précisé.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>salt</emphasis>: Si la clé doit être utilisé comme grain de sel. Dans ce cas la clé
                    utilisée pour le cryptage sera elle même cryptée. Par défaut false : ce n'est pas le cas.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Si vous passez une chaine à la place d'un tableau pour la clé, celle-ci sera utilisée.
        </para>

        <para>
            Les méthodes <code>getEncryption()</code> et <code>setEncryption()</code> sont aussi présentes.
        </para>

        <note>
            <para>
                Une exception sera levée si l'extension PHP mcrypt n'est pas disponible.
            </para>
        </note>

        <note>
            <para>
                Notez aussi que tous vos paramètres utilisés à la création de l'instance ou avec setEncryption()
                vont être vérifiés. Si mcrypt détecte un problème, une exception sera levée.
            </para>
        </note>

        <para>
            <code>getVector()</code> et <code>setVector()</code> sont aussi disponibles si besoin.
            Une chaine passée sera mise à la taille du vecteur pour être utilisée avec l'algorithme en cours.
        </para>

        <note>
            <para>
                Notez que si vous n'utilisez pas un vecteur spécifique, alors vous devrez le récupérer et le stocker.
                En effet, celui-ci est indispensable pour décoder la valeur dans le futur.
            </para>
        </note>

        <programlisting language="php"><![CDATA[
// Utilise blowfish par défaut
$filter = new Zend_Filter_Encrypt('myencryptionkey');

// Affecte un vecteur précis.
$filter->setVector('myvector');
// $filter->getVector(); est nécessaire sinon, pour décoder la valeur plus tard

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

// Pour le décryptage, voyez le code du filtre Decrypt
]]></programlisting>
    </sect3>

    <sect3 id="zend.filter.set.encrypt.openssl">
        <title>Cryptage avec OpenSSL</title>
        <para>
            Lorsque vous avez installé l'extension PHP <code>OpenSSL</code>, vous pouvez utiliser l'adaptateur
            du même nom, dont voici les options d'instanciation:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>public</emphasis>: La clé publique de l'utilisateur auquel vous voulez proposer
                    du contenu crypté. Plusieurs clés peuvent être spécifiées via un tableau. Il est possible
                    de préciser le contenu de la clé, ou alors un chemin vers une clé.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>private</emphasis>: Votre clé privée utilisée pour crypter le contenu.
                    La encore la clé peut être précisée sous forme textuelle, ou alors un chemin vers
                    un fichier contenant la clé.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            <code>getPublicKey()</code> et <code>setPublicKey()</code> sont aussi présentes, ainsi que
            <code>getPrivateKey()</code> et <code>setPrivateKey()</code>.
        </para>

        <programlisting language="php"><![CDATA[
// Utiliser openssl
$filter = new Zend_Filter_Encrypt(array(
    'adapter' => 'openssl',
    'private' => '/path/to/mykey/private.pem'
));

// utilisation des méthodes
$filter->setPublicKey(array(
    '/public/key/path/first.pem',
    '/public/key/path/second.pem'
));
]]></programlisting>

        <note>
            <para>
                Attention l'adaptateur <code>OpenSSL</code> ne fonctionnera pas si vous ne passez pas des clés
                valides.
            </para>
        </note>

        <para>
            Si vous souhaitez encoder aussi les clés, passez alors une passphrase via
            <code>setPassphrase()</code>. Attention, la passphrase sera nécessaire pour décoder les clés.
        </para>

        <programlisting language="php"><![CDATA[
// Utilise openssl avec une clé privée
$filter = new Zend_Filter_Encrypt(array(
    'adapter' => 'openssl',
    'private' => '/path/to/mykey/private.pem'
));

// utilisation des méthodes pour specifier la clé publique
$filter->setPublicKey(array(
    '/public/key/path/first.pem',
    '/public/key/path/second.pem'
));
$filter->setPassphrase('mypassphrase');
]]></programlisting>

        <para>
            Pour décrypter le document, la passphrase (si utilisée) et les clés enveloppe sont nécessaires.
        </para>

        <para>
            Ceci signifie que vous devez appeler la méthode <code>getEnvelopeKey()</code> après le cryptage
            pour récupérer l'enveloppe.
        </para>

        <para>
            Voici donc un exemple complet de cryptage de données avec <code>OpenSSL</code>.
        </para>

        <programlisting language="php"><![CDATA[
// Utilisons openssl avec une clé privée
$filter = new Zend_Filter_Encrypt(array(
    'adapter' => 'openssl',
    'private' => '/path/to/mykey/private.pem'
));

// Voici la clé publique
$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;

// Le décryptage est expliqué dans le filtre Decrypt
]]></programlisting>
    </sect3>
</sect2>

<!--
vim:se ts=4 sw=4 et:
-->