NAME

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

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' ];

DESCRIPTION

The purpose of 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 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 PGP5 will encrypt to. Default is null.

$passphrase

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

$interactive

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.

$armor

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

$clearsign

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

conventional( [$boolean] )

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

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

$extraArgs

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

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

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.

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::PGP5::MessageProcessor uses solely pipes to pass the message and passphrase to PGP5.

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

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