NAME

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

SYNOPSIS

  use PGP::GPG::MessageProcessor;

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

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

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

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

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

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

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

  $mp = new PGP::GPG::MessageProcessor { encrypt => 1, symmetric => 1 }

Please note that brackets ( [ ] )'s around arguments to a function indicate that the arguments are optional, not the creation of an array reference. However, a pair brackets around a list that a data member of $mp is being set to does indicate that an array reference is being used. For example, the value $extraArgs is set to should be an array reference, while cipher() gets between 1 and 3 arguents.

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

A reference to an array of keyIDs GPG will encrypt to. Default is null.

$passphrase

GPG will use $passphrase for signing and decrypting. This does not have to be set if $interactive is set. 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. This option is supposed to be used in addition to a true value for $encrypt. If true, $recipients must be null. Default is false.

$secretKeyID

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

$comment This option fills defines what comment is put into the comment field of messages. Default is null; this will let GPG do what it likes.

$extraArgs

A reference to an array of any other possible arguments to be passed to GPG.

METHODS

new()

Creates a new object. One can pass in data members with values using an anonymous hash.

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@neverending.org>

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