NAME
PGP::GPG::MessageProcessor - supply object methods for interacting with GnuPG
SYNOPSIS
use IO::Handle;
use PGP::GPG::MessageProcessor;
$mp = new PGP::GPG::MessageProcessor;
$mp->{encrypt} = $boolean;
$mp->{sign} = $boolean;
$mp->{recipients} = [ 'keyID', ... ];
$mp->{passphrase} = $passphrase;
$success = $mp->passphrase_test( $passphrase);
$input = new IO::Handle; # These could be be a Symbol::gensym
$output = new IO::Handle;
$error = ''; # It becomes ">&STDERR".
$status = new IO::Handle;
$pid = $mp->cipher( $input, $output, $error, $status );
print $input @plaintext;
close $input;
@ciphertext = <$output>;
@error = <$error>;
@status = <$status>;
$input = "<&STDIN"; # read from stdin; could also just be ''
$output = ''; # write to stdout
$pid = $mp->decipher( $input, $output, $error );
$mp->{interactive} = $boolean;
$mp->{noTTY} = $boolean;
$mp->{armor} = $boolean;
$mp->{clearsign} = $boolean
$mp->{symmetric} = $boolean;
$mp->{secretKeyID} = $keyID;
$mp->{comment} = $string;
$mp->{homedir} = $pathname; # without shell expansions like ~
$mp->{extraArgs} = [ '--cipher-algo', 2 ];
$mp = new PGP::GPG::MessageProcessor { encrypt => 1,
symmetric => 1 }DESCRIPTION
The purpose of PGP::GPG::MessageProcessor is to provide a simple, object-oriented interface to GnuPG, 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 decipher().
The interface to cipher() and decipher() is modelled after IPC::Open3, a base Perl module. In fact, most of the inter-process communication code in this module is modelled after IPC::Open3.
METHODS
- new()
-
Creates a new object. One can pass in data members with values using an anonymous hash. See the synopsis for an example.
- passphrase_test( [ $passphrase ] )
-
Tests if $passphase (already set or passed as an argument) is valid for the secret key currently selected. Sets $passphrase to any passed argument.
- cipher( $stdin, [ $stdout, [ $stderr, [ $status ] ] ] )
-
This is a committal method; that is, it looks at all the previously-set data members, and calls GnuPG accordingly for encrypting or signing streams. The interface for this method is similar to IPC::Open3's interface; please read it for gritty details. Basically, handles are passed in, and they are attached to the GnuPG process. This interface is a lot more lenient, however. For example, $stdin, $stdout, or $stderr is eliminated, or false, its respective 'natural' file handle is used. That is, if $stderr is elminated, all of GnuPG's stderr is piped out to your stderr; if $stdin is eliminated, GnuPG reads from your stdin. $status reads from GnuPG's --status-fd option, and has no 'natural' backup; that is, if it is eliminated, the output is not piped to any other filehandle. To detect success or failure, one can either see if the output handle is eof, or, for more detail, read from $status, looking for error statements.. encrypt() and sign() are aliases for this subroutine, for ease of readibility.
- decipher( $stdin, [ $stdout, [ $stderr, [ $status ] ] ] )
-
This is just like cipher(), described above, except that it is used for decrypting or verifying streams. decrypt() and verify() are aliases for this subroutine, for ease of readibility.
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 GnuPG will encrypt to. Default is null.
- $passphrase
-
GnuPG will use $passphrase for signing and decrypting. This does not have to be set if $interactive is set, or the operation, such as signature verification, does not require it. Default is null.
- $interactive
-
Setting this will allow the user to interact directly with GnuPG such as to enter passphrases. This is desired for maximum security, so that passphrases are not held in memory. Default is true.
- $armor
-
If true, GnuPG will produce an armored output. Default is false.
- $clearsign
-
If true, GnuPG will produce clear-signed messages. Default is false.
- $symmetric
-
If true, GnuPG will only symmetrically (conventionally) encrypt. This option is supposed to be used in addition to a true value for $encrypt. If true, $recipients will be disregarded. Default is false.
- $secretKeyID
-
The secret key GnuPG will use for signing and passphrase testing. GnuPG 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; GnuPG determines.
- $homedir
-
This option determines the argument to GnuPG's --homedir option. Default is null; GnuPG determines.
- $gpg_program
-
This is the path which is used to call GnuPG. Default is 'gpg', which will find GnuPG if it is in your $PATH;
- $extraArgs
-
A reference to an array of any other possible arguments Please note that if you wish to have multiple options, including ones that are divided up among two arguments, such as --cipher-algo, which takes a second argument, an integer, divide up the arguments into different elements in the array reference. See the synopsis for an example.
NOTES
Unless $interactive is true, $passphrase must be set, either directly, or indirectly through passphrase_test().
Some settings have no effect in some situations. For instance, $encrypt has no effect if decipher() is called.
This module does not override any options in what GnuPG considers to be its option file.
You should wait for the $pid returned by cipher() or decipher(), using the wait() or waitpid() calls, or else you may end up accumulating zombies.
BACKWARDS COMPATIBILITY
Older versions of this module used a sick array-ref method of passing data around. That interface has been dropped, in favor of the cleaner, more efficient, easier to use passed-filehandle method. However, for a couple of revisions, the array-ref interface will still be allowed, but heavily discouraged. Expect this compatibility to be dropped, and change your code to use the new interface described in this manpage.
SECURITY NOTES
Nothing fancy here for security such as memory-locking.
This module solely uses pipes to interact with GnuPG.
For maximum passphrase security, $interactive should be true, forcing the user to input the passphrase directly to GnuPG.
PROBLEMS/BUGS
Nothing fancy here for security such as memory-locking.
This documentation is probably pretty bad. Please let me know of errors.
AUTHOR
Frank J. Tobin <ftobin@uiuc.edu>
COPYRIGHT
Copyright (C) 1999 Frank J. Tobin <ftobin@uiuc.edu>
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, visit the following URL: http://www.gnu.org/copyleft/gpl.html