In order to install this module, run

perl Makefile.PL
make
make install

This module, PGP::GPG::MessageProcessor, provides an interface
to the encryption/decryption/signing/verifying methods of
GNU Privacy Guard.  It does not provide keyring manipulation.

The interface is designed to be consistent with
PGP::PGP5::MessageProcessor, so that the same methods may be
used on objects of both modules.

-------------------------------------------------------------------------

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

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 the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

-------------------------------------------------------------------------

NAME
    PGP::GPG::MessageProcessor - supply object methods for interacting with
    GPG.

SYNOPSIS
      use PGP::GPG::MessageProcessor;

      $messageProcessor = new PGP::GPG::MessageProcessor;

      $messageProcessor->{encrypt} = $boolean;
      $messageProcessor->{sign} = $boolean;

      $messageProcessor->{recipients} = [ 'keyID', ... ];

      $messageProcessor->{passphrase} = $passphrase;
      $passphrase = $messageProcessor->passphrasePrompt();
      $success    = $messageProcessor->passphraseTest( [$passphrase] );

      $success    = $messageProcessor->cipher( \@plaintext, [ [\@ciphertext],
                                       [\@stderr] ] );

      $success    = $messageProcessor->verify( \@ciphertext, [ [\@plaintext],
                                      [\@stderr] ] );

      $messageProcessor->{interactive} = $boolean;
      $messageProcessor->{armor}       = $boolean;
      $messageProcessor->{clearsign}   = $boolean
      $messageProcessor->{symmetric}   = $boolean;
      $messageProcessor->{secretKeyID} = $keyID;
      $messageProcessor->{extraArgs}   = [ '--foo' ];

DESCRIPTION
    The purpose of *PGP::GPG::MessageProcessor* is to provide a simple,
    object-oriented interface to GPG, the GNU Privacy Guard, and any other
    implementation of PGP that uses the same syntax and piping mechanisms.

    Normal usage involves creating a new object via *new()*, making some
    settings such as *$passphase*, *$armor*, or *$recipients*, and then
    committing these with *cipher()* or *verify()*.

DATA MEMBERS
    $encrypt
      If true, the message will be encrypted. Default is false.

    $sign
      If true, the message will be signed. Default is false.

    $recipients
      *$recipients* is a reference to an array of keyIDs GPG will encrypt
      to. Default is null.

    $passphrase
      GPG will use *$passphrase* for signing and decrypting. Default is
      null.

    $interactive
      *PGP::GPG::MessageProcessor* will allow the user to interact directly
      with GPG such as to enter passphrases. This is desired for maximum
      security. Default is true.

    $armor
      If true, GPG will produce an armored output. Default is false.

    $clearsign
      If true, GPG will produce clear-signed messages. Default is false.

    conventional( [$boolean] )
      If true, GPG will only symmetrically (conventionally) encrypt. If
      true, *$recipients* must be null. Default is false.

    $secretKeyID
      $secretKeyID is the secret key GPG will use for signing and passphrase
      testing. GPG will choose the default key if unset. Default is null.

    $extraArgs
      $extraArgs is a reference to an array of any other possible arguments
      to be passed to GPG.

METHODS
    new()
      Creates a new object.

    passphrasePrompt()
      Prompts the user for a passphrase; uses 'stty sane -echo < /dev/tty'
      for non-echoed input. Sets *$passphrase* to any input by the user.

    passphraseTest( [$passphrase] )
      Uses a crude mechanism to check if *$passphase* (already set or passed
      as an argument) is valid for the secret key currently selected. Sets
      *$passphrase* to any passed argument.

    cipher( \@plaintext, [ [\@ciphertext], [\@stderr] ] )
      Performs PGP encryption and/or signing over @plaintext. This is a
      'committal' method. If no \@ciphertext is passed, @plaintext is
      replaced with the ciphertext. Otherwise, @ciphertext contains GPG's
      result. If \@stderr is passed, GPG's stderr is captured into @stderr.
      This is useful if you want to hide everything GPG does from the user.

    verify( \@ciphertext, [ [\@plaintext], [\@stderr] ] )
      Performs PGP decryption and/or over @ciphertext. This a 'committal'
      method. If no \@plaintext is passed, @ciphertext is replaced with the
      plaintext. Otherwise, @plaintext contains GPG's result. If \@stderr is
      passed, GPG's stderr is captured into @stderr. This is useful if you
      want to hide everything GPG does from the user.

NOTES
    Unless *$interactive* is true, *$passphrase* must be set, either
    directly, or through *passphasePrompt()*, or *passphraseTest()*.

    Some settings have no effect in some situations. For instance,
    *$encrypt* has no effect if *verify()* is called.

SECURITY NOTES
    Nothing fancy here for security such as memory-locking.

    *PGP::GPG::MessageProcessor* uses solely pipes to pass the message and
    passphrase to GPG.

    For maximum passphrase security, *$interactive* should be true, forcing
    the user to input the passphrase directly to GPG.

PROBLEMS/BUGS
    Nothing fancy here for security such as memory-locking.

AUTHOR
    Frank J. Tobin <ftobin@bigfoot.com>

    fingerprint: 4F86 3BBB A816 6F0A 340F 6003 56FF D10A 260C 4FA3