NAME

       Mail::GnuPG - Process email with GPG.

SYNOPSIS

         use Mail::GnuPG;
         my $mg = new Mail::GnuPG( key => 'ABCDEFGH' );
         $ret = $mg->mime_sign( $MIMEObj, 'you@my.dom' );

DESCRIPTION

       Use GnuPG::Interface to process or create PGP signed or encrypted email.

   new
         Create a new Mail::GnuPG instance.

        Arguments:
          Paramhash...

          key    => gpg key id
          keydir => gpg configuration/key directory
          passphrase => primary key password
          use_agent => use gpg-agent if non-zero
          always_trust => always trust a public key
          # FIXME: we need more things here, maybe primary key id.

   decrypt
        Decrypt an encrypted message

        Input:
          MIME::Entity containing email message to decrypt.

         The message can either be in RFC compliant-ish multipart/encrypted
         format, or just a single part ascii armored message.

        Output:
         On Failure:
           Exit code of gpg.  (0 on success)

         On Success: (just encrypted)
           (0, undef, undef)

         On success: (signed and encrypted)
           ( 0,
             keyid,           # ABCDDCBA
             emailaddress     # Foo Bar <foo@bar.com>
           )

          where the keyid is the key that signed it, and emailaddress is full
          name and email address of the primary uid

         $self->{last_message} => any errors from gpg
         $self->{plaintext}    => plaintext output from gpg
         $self->{decrypted}    => parsed output as MIME::Entity

   get_decrypt_key
        determines the decryption key (and corresponding mail) of a message

        Input:
          MIME::Entity containing email message to analyze.

         The message can either be in RFC compliant-ish multipart/signed
         format, or just a single part ascii armored message.

        Output:
         $key    -- decryption key
         $mail   -- corresponding mail address

   verify
        verify a signed message

        Input:
          MIME::Entity containing email message to verify.

         The message can either be in RFC compliant-ish multipart/signed
         format, or just a single part ascii armored message.

         Note that MIME-encoded data should be supplied unmodified inside
         the MIME::Entity input message, otherwise the signature will be
         broken. Since MIME-tools version 5.419, this can be achieved with
         the C<decode_bodies> method of MIME::Parser. See the MIME::Parser
         documentation for more information.

        Output:
         On error:
           Exit code of gpg.  (0 on success)
         On success
           ( 0,
             keyid,           # ABCDDCBA
             emailaddress     # Foo Bar <foo@bar.com>
           )

          where the keyid is the key that signed it, and emailaddress is full
          name and email address of the primary uid

         $self->{last_message} => any errors from gpg

   has_public_key
       Does the keyring have a public key for the specified email address?

        FIXME: document better.  talk about caching.  maybe put a better
        interface in.

   mime_sign
         sign an email message

        Input:
          MIME::Entity containing email message to sign

        Output:
         Exit code of gpg.  (0 on success)

         $self->{last_message} => any errors from gpg

         The provided $entity will be signed.  (i.e. it _will_ be modified.)

   clear_sign
         clearsign the body of an email message

        Input:
          MIME::Entity containing email message to sign.
          This entity MUST have a body.

        Output:
         Exit code of gpg.  (0 on success)

         $self->{last_message} => any errors from gpg

         The provided $entity will be signed.  (i.e. it _will_ be modified.)

   ascii_encrypt
         encrypt an email message body using ascii armor

        Input:
          MIME::Entity containing email message to encrypt.
          This entity MUST have a body.

          list of recipients

        Output:
         Exit code of gpg.  (0 on success)

         $self->{last_message} => any errors from gpg

         The provided $entity will be encrypted.  (i.e. it _will_ be modified.)

   ascii_signencrypt
         encrypt and sign an email message body using ascii armor

        Input:
          MIME::Entity containing email message to encrypt.
          This entity MUST have a body.

          list of recipients

        Output:
         Exit code of gpg.  (0 on success)

         $self->{last_message} => any errors from gpg

         The provided $entity will be encrypted.  (i.e. it _will_ be modified.)

   mime_encrypt
         encrypt an email message

        Input:
          MIME::Entity containing email message to encrypt
          list of email addresses to sign to

        Output:
         Exit code of gpg.  (0 on success)

         $self->{last_message} => any errors from gpg

         The provided $entity will be encrypted.  (i.e. it _will_ be modified.)

   mime_signencrypt
         sign and encrypt an email message

        Input:
          MIME::Entity containing email message to sign encrypt
          list of email addresses to sign to

        Output:
         Exit code of gpg.  (0 on success)

         $self->{last_message} => any errors from gpg

         The provided $entity will be encrypted.  (i.e. it _will_ be modified.)

   is_signed
         best guess as to whether a message is signed or not (by looking at
         the mime type and message content)

        Input:
          MIME::Entity containing email message to test

        Output:
         True or False value

   is_encrypted
         best guess as to whether a message is signed or not (by looking at
         the mime type and message content)

        Input:
          MIME::Entity containing email message to test

        Output:
         True or False value

LICENSE

       Copyright 2003 Best Practical Solutions, LLC

       This program is free software; you can redistribute it and/or modify it under the terms of
       either:

           a) the GNU General Public License as published by the Free
           Software Foundation; version 2
           http://www.opensource.org/licenses/gpl-license.php

           b) the "Artistic License"
           http://www.opensource.org/licenses/artistic-license.php

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See either the GNU General Public License or the Artistic License for more details.

AUTHOR

       Robert Spier

       David Bremner <ddb@cpan.org>

BUGS/ISSUES/PATCHES

       Please send all bugs/issues/patches to
           bug-Mail-GnuPG@rt.cpan.org

SEE ALSO

       perl.

       GnuPG::Interface,

       MIME::Entity