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->parse ( ... );

      $mg->decrypt ( ... );
      $mg->verify ( ... );

      $mg->is_encrypted ( ... );
      $mg->is_signed ( ... );
      $mg->is_signed_quick ( ... );

      $mg->get_decrypt_key ( ... );
      $mg->get_key_trust ( ... );

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  (optionally with shipped patch applied)
      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.

    You may apply the shipped GnuPG::Interface patch as well. It just fixes
    a warning which is throwed on any keyring inspection. This is a known
    problem and reported to the author, hopefully it will be fixed upstream
    soon:

      % tar xvfz GnuPG-Interface-0.33.tar.gz
      % cd GnuPG-Interface-0.33
      % patch -p1 ../Mail-GPG.x.xx/patches/GnuPG-Interface-0.33.tru-record-type.txt
      % perl Makefile.PL
      % make test
      % make install

    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 <joern
    AT zyn.de>.

AUTHOR
    Joern Reder <joern AT zyn.de>

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 you 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.

