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