NAME Mail::GPG - Handling of GnuPG encrypted / signed mails SYNOPSIS use Mail::GPG; my $mg = Mail::GPG->new; my %keys_id2mail = $mg->query_keyring ( search => 'joern@zyn.de', ); my $entity = MIME::Entity->build ( From => 'joern@zyn.de', Subject => "Mail::GPG Testmail", Data => [ "Hiho, a nice encrypted mail" ], Encoding => "quoted-printable", Charset => "iso-8859-1", ); my $encrypted_entity = $mg->mime_sign_encrypt ( entity => $entity, key_id => $key_id, password => 'topsecret', recipients => [ 'niceguy@zyn.de' ], ); my $mail_text = $encrypted_entity->as_string; # and a lot more... $mg->mime_sign ( ... ); $mg->mime_encrypt ( ... ); $mg->mime_sign_encrypt ( ... ); $mg->armor_sign ( ... ); $mg->armor_encrypt ( ... ); $mg->armor_sign_encrypt ( ... ); $mg->decrypt ( ... ); $mg->verify ( ... ); $mg->is_encrypted ( ... ); $mg->is_signed ( ... ); $mg->get_decrypt_key ( ... ); DESCRIPTION This Perl modules handles all the details of encrypting and signing Mails using GnuPG according to RFC 3156 and RFC 2440, that is OpenPGP MIME and traditional armor signed/encrypted mails. This module also ships a patch to MIME-tools. Without this patch proper verification of MIME signed messages isn't guaranteed! Refer to the "MIME-tools PATCH" chapter in the documentation for details about this issue. PREREQUISITES Perl >= 5.00503 GnuPG::Interface >= 0.33 MIME-tools == 5.411 (with shipped patch applied) MIME::QuotedPrint >= 2.20 (part of MIME-Base64 distribution) INSTALLATION First get MIME-tools 5.411 and extract it, e.g. on the same level where you extracted the Mail::GPG tarball. % tar xvfz Mail-GPG-x.xx.tar.gz % tar xvfz MIME-tools-5.411.tar.gz Apply the MIME-tools patch shipped with this module and build and install the MIME-tools package (Mail::GPG works without this patch, but it's strongly suggested, that you apply it. Refer to the next chapter for details): % cd MIME-tools-5.411 % patch -p1 < ../Mail-GPG.x.xx/patches/MIME-tools-5.411.enc.preamble.txt % perl Makefile.PL % make test % make install Make sure that the gpg program is installed and can be found using your standard PATH. Then install Mail::GPG % cd ../Mail-GPG-x.xx % perl Makefile.PL % make test % make install Mail::GPG has a bunch of tests which will create a temporary gpg keyring to be able to do real encryption and stuff. You need to have gpg in your path for the tests to succeed, otherwise all useful tests will be skipped. Note that the test 04.big needs some time, on an Athlon 1800XP about 12 seconds, so be patient ;) MIME-tools PATCH Some words about MIME-tools: MIME::Entity internally stores all data in decoded form, that is without any content transfer encoding like quoted-printable or base64 applied. In particular if you parse with MIME::Parser, e.g. a MIME signed mail, the entity will always be stored that way. But RFC 3156 requires the encoded version of the MIME entity, because the signature is calculated based on the encoded form. Some content transfer encodings are ambigious and you can't reverse the process and get back the correct encoded version without breaking the signature. The shipped MIME-tools patch adds the ability of having encoded data in a MIME::Entity object and a method to advise MIME::Parser to use this ability and store the parsed data in encoded form. Additionally MIME-tools does not reproduce preambles which consist only of empty lines. This also invalids signatures. E.g. mutt and sylpheed are known to add such empty preambles. The patch fixes this problem. Mail::GPG generally works without this patch, but it's strongly suggested that you apply it. Otherwise you have no guarantee that MIME signed messages are verified correctly by Mail::GPG. Unfortunately the maintainer of MIME-tools currently seeks for a new maintainer and stopped development, so there is no chance to get the patch into an official CPAN version of MIME-tools. That's why you have to apply the patch manually. WHY ANOTHER GnuPG MAIL MODULE? I know the Mail::GnuPG module. I worked a long time with it and submitted a few patches adding features and fixing bugs. The problems with MIME signed messages mentioned above led me to my own implementation. In the meantime I know, that regarding the implemented RFC's Mail::GnuPG works as correct as Mail::GPG does. Only that Mail::GnuPG's documentation is not aware of these MIME signature problems resp. encoded vs decoded data storage. I like clean OO interfaces and well documented source code. With Mail::GnuPG you need to access internal data structures from outside (e.g. things like gpg's last output). Also Mail::GnuPG modifies the MIME::Entity objects you pass to it, which is bad in some situations. Mail::GPG has some more features, e.g. multiplexed I/O with the gpg program, which makes it work even with huge amounts of data. Last but not least it was simply more fun for me to fix my own bugs in my own code and to learn all the details by making my own faults. And fun is important for an Open Source programmer, in particular for me ;) So it's up to you: you have the choice, not too bad at all, not? ;) KNOWN BUGS Currently none. Please report any bugs to the author: Joern Reder . AUTHOR Joern Reder CONTACT You can contact me by email. Please place the module name "Mail::GPG" somewhere in the subject, because I filter my mails that way. I'm a native German speaker, but can contact me in english as well. COPYRIGHT Copyright (C) 2004 by Joern Reder, All Rights Reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.