SYNOPSIS

use Mail::GnuPG;
my $mg = new Mail::GnuPG( key => 'ABCDEFGH' );
$ret = $mg->mime_sign( $MIMEObj, '[email protected]' );

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 <[email protected]>
    )
   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 <[email protected]>
    )
   where the keyid is the key that signed it, and emailaddress is full
   name and email address of the primary uid. The email/uid is UTF8
   encoded, as output by GPG.
  $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 <[email protected]>