The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

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