=head1 NAME

PGP::PGP5::MessageProcessor - supply object methods for interacting with PGP5.

=head1 SYNOPSIS

  use PGP::PGP5::MessageProcessor;

  $messageProcessor = new PGP::PGP5::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' ];

=head1 DESCRIPTION

The purpose of I<PGP::PGP5::MessageProcessor> is to provide a simple, object-oriented
interface to PGP5,
and any other implementation of PGP that uses
the same syntax and piping mechanisms.

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

=head1 DATA MEMBERS

=over 2

=item B<$encrypt>

If true, the message will be encrypted.
Default is false.

=item B<$sign>

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

=item B<$recipients>

I<$recipients> is a reference to an array of keyIDs PGP5 will encrypt to.
Default is null.

=item B<$passphrase>

PGP5 will use I<$passphrase> for signing and decrypting.
Default is null.

=item B<$interactive>

I<PGP::PGP5::MessageProcessor> will allow the user to interact directly with
PGP5 such as to enter passphrases.
This is desired for maximum security.
Default is true.

=item B<$armor>

If true, PGP5 will produce an armored output.
Default is false.

=item B<$clearsign>

If true, PGP5 will produce clear-signed messages.
Default is false.

=item B<conventional( [$boolean] )>

If true, PGP5 will only symmetrically (conventionally) encrypt.
If true, I<$recipients> must be null.
Default is false.

=item B<$secretKeyID>

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

=item B<$extraArgs>

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

=back

=head1 METHODS

=over 2

=item B<new()>

Creates a new object.

=item B<passphrasePrompt()>

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

=item B<passphraseTest( [$passphrase] )>

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

=item B<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 PGP5's result.  If \@stderr is passed,
PGP5's stderr is captured into @stderr.  This is useful if you want to hide
everything PGP5 does from the user.

=item B<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 PGP5's result.  If \@stderr is passed,
PGP5's stderr is captured into @stderr.  This is useful if you want to hide
everything PGP5 does from the user.

=back

=head1 NOTES

Unless I<$interactive> is true, I<$passphrase> must be set, either
directly, or through
I<passphasePrompt()>, or I<passphraseTest()>.

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

=head1 SECURITY NOTES

Nothing fancy here for security such as memory-locking.

I<PGP::PGP5::MessageProcessor> uses solely pipes to pass the message and
passphrase to PGP5.

For maximum passphrase security, I<$interactive> should be true, forcing
the user to input the passphrase directly to PGP5.

=head1 PROBLEMS/BUGS

Nothing fancy here for security such as memory-locking.

=head1 AUTHOR

Frank J. Tobin <ftobin@bigfoot.com>

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

=cut
