[[PageOutline(2, Sommaire)]]

= Wamailer et OpenPGP =

== Présentation ==

Wamailer supporte désormais la signature numérique et le chiffrement des emails au travers du format OpenPGP/MIME décrit dans la [http://www.faqs.org/rfcs/rfc3156 RFC 3156] et de l’excellent programme [http://www.gnupg.org/ GnuPG]. La classe {{{SecureMail}}} vient s’intercaler entre la classe {{{Email}}} et votre programme. Ainsi, l’API est la même qu’avec la classe {{{Email}}} seule. Vient s’y ajouter entre autre les méthodes {{{SecureMail::sign()}}} et {{{SecureMail::encrypt()}}} qui permettent respectivement de signer l’email et de le chiffrer (et non pas crypter).

Les chiffrements symétrique aussi bien qu’asymétrique sont supportés. Vous pouvez aussi signer '''et''' chiffrer votre email. Les deux opérations ne sont pas exclusives.

== Exemples ==

Reprenons tout simplement le premier exemple de la page WikiStart et ajoutons la signature et le chiffrement de l’email :

{{{
#!php
<?php
require 'mailer.class.php';
require 'securemail.class.php';

$email = new SecureMail();
$email->addRecipient("bobe <my@address.tld>");
$email->setSubject("Ici, le sujet");
$email->setTextBody("Ici, le message");

$email->sign();
$email->encrypt('bobe@example.org');
Mailer::send($email);
?>
}}}

Il suffit d’ajouter les appels aux méthodes {{{SecureMail::sign()}}} et {{{SecureMail::encrypt()}}} et le tour est joué.

Dans cet exemple, on ne fournit pas d’identifiant de clé ni de passphrase à la méthode {{{SecureMail::sign()}}}. GnuPG utilisera dans ce cas la clé par défaut du trousseau de clé. 
Il faudra en outre que cette clé ne soit pas protégée par un passphrase. La FAQ de gnupg.org fournit un court howto pour créer une sous-clé sans passphrase et ainsi ne pas mettre en péril la sécurité de sa paire de clés: http://www.gnupg.org/(en)/documentation/faqs.html#q4.14

Si vous souhaitez spécifier la clé à utiliser, passez-là en premier argument de la méthode {{{SecureMail::sign()}}}. Si vous souhaitez spécifier un passphrase (mauvaise idée de laisser traîner ainsi son passphrase), passez-le en deuxième argument de la méthode {{{SecureMail::sign()}}}.

Passons maintenant à la méthode {{{SecureMail::encrypt()}}}. Cette méthode prend deux arguments, dont le premier est obligatoire. Le premier argument doit être la clé publique (ou toute information permettant d’identifier cette clé; nom, adresse email associée à cette clé, …) du destinataire. Votre email est à destination de plusieurs personnes ? Pas de problème, vous pouvez passer un tableau des clés publiques à utiliser lors du chiffrement.

Par défaut, le chiffrement est asymétrique. Cependant, si vous passez la valeur de la constante de classe {{{SecureMail::S_ENCRYPTION}}} en deuxième argument de la méthode {{{SecureMail::encrypt()}}}. Le chiffrement symétrique sera utilisé. Dans ce cas, c’est le passphrase de déchiffrement qui devra être passé en premier argument.

Un exemple de chiffrement symétrique :

{{{
#!php
<?php
require 'mailer.class.php';
require 'securemail.class.php';

$email = new SecureMail();
$email->addRecipient("bobe <my@address.tld>");
$email->addRecipient("Stefan <other@address.tld>");
$email->setSubject("Ici, le sujet");
$email->setTextBody("Ici, le message");
$email->attach('/path/to/file', 'MyFile');

$email->encrypt('mypassword', SecureMail::S_ENCRYPTION);
Mailer::send($email);
?>
}}}

Vous pouvez également signer les emails chiffrés symétriquement, mais seulement si la clé utilisée pour la signature ne nécessite pas de passphrase. C’est une limitation de GnuPG dans ses options de ligne de commande (du moins, toutes mes recherches sur ce point sont restées infructueuses).

Les autres méthodes et attributs de la classe :

 * L’attribut {{{$homedir}}} doit contenir le chemin vers le trousseau de clés à utiliser. Par défaut, sa valeur est {{{null}}}, ce qui signifie que GnuPG utilisera le trousseau de clés de l’utilisateur exécutant le script. Si vous spécifiez un autre trousseau de clés, assurez-vous de bien y avoir un accès en lecture (et en écriture ?)
 * L’attribut {{{$tmpdir}}} est le répertoire des fichiers temporaires du système. La valeur par défaut est {{{/tmp}}}.
 * L’attribut {{{$digest_algo}}} est l’algorithme de hashage à utiliser pour la signature de l’email. La valeur par défaut est {{{sha1}}}
 * L’attribut {{{$cipher_algo}}} est l’algorithme de chiffrement à utiliser pour l’opération de chiffrement de l’email. La valeur par défaut est {{{null}}}. GnuPG utilise alors son algorithme par défaut.
 * L’attribut {{{$gpg_bin}}} est le chemin vers l’exécutable du programme GnuPG.
 * La méthode {{{SecureMail::initialize()}}} permet de remettre à zéro les attributs volatiles de la classe. À utiliser si vous réutiliser le même objet Email pour un autre envoi.
 * Les deux constantes de classe {{{SecureMail::A_ENCRYPTION}}} et {{{SecureMail::S_ENCRYPTION}}} utilisables avec la méthode {{{SecureMail::encrypt()}}} (Le A de A_ENCRYPTION pour ASYMMETRIC et le S de S_ENCRYPTION pour SYMMETRIC ;¬))

== Liens ==

 * [http://www.gnupg.org/ GnuPG] -- Le site officiel du programme GnuPG
 * [http://www.faqs.org/rfcs/rfc3156 RFC 3156] -- La RFC sur le format OpenPGP/MIME de sécurisation des emails