In order to install this module, run perl Makefile.PL make make install This module, PGP::GPG::MessageProcessor, provides an interface to the encryption/decryption/signing/verifying methods of GNU Privacy Guard. It does not provide keyring manipulation. The interface is designed to be consistent with PGP::PGP5::MessageProcessor, so that the same methods may be used on objects of both modules. ---------------------------------------------------------------------- NAME PGP::GPG::MessageProcessor - supply object methods for interacting with GPG. SYNOPSIS use Symbol; # for gensym use PGP::GPG::MessageProcessor; $mp = new PGP::GPG::MessageProcessor; $mp->{encrypt} = $boolean; $mp->{sign} = $boolean; $mp->{recipients} = [ 'keyID', ... ]; $mp->{passphrase} = $passphrase; $passphrase = $mp->passphrase_prompt(); $success = $mp->passphrase_test( $passphrase); $input = gensym; # These could be a new IO::Handle or FileHandle $output = gensym; # instead; import theses modules if you want them. $error = ''; # Yes, youy can do this! It becomes ">&STDERR". $status = gensym; $pid = $mp->cipher( $input, $output, $error, $status ); $input = "<&STDIN"; $output = ''; $error = gensym; $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 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 *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. 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 Setting this will allow the user to interact directly with GPG 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, GPG will produce an armored output. Default is false. $clearsign If true, GPG will produce clear-signed messages. Default is false. $symmetric 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* will be disregarded. 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; GPG determines. $homedir This option determines the argument to GPG's --homedir option. Default is null; GPG determines. $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 example in the synopsis for an example. METHODS new() Creates a new object. One can pass in data members with values using an anonymous hash. See synopsis for an example. passphrase_prompt() Prompts the user for a passphrase; uses Term::ReadKey for non-echoed input. Sets *$passphrase* to any input by the user. 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 gpg accordingly for encrypting or signing streams. The interface for this method is similar to IPC::Open3's interface; please read it for gritty details. This interface is a lot more lenient, however. If $stdin, $stdout, or $stderr is eliminated, or false, its respective 'natural' file handle is used. That is, if $stderr is elminated, all of gpg's stderr is piped out to your stderr; if $stdin is eliminated, gpg reads from your stdin. $status reads from gpg'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 is null (a hack), or, preferrably, read from $status. This will give you the best, detailed output. *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. NOTES Unless *$interactive* is true, *$passphrase* must be set, either directly, or through *passphase_prompt()*, or *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 gpg considers to be its option file, located in its homedir. 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 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. This documentation is probably pretty bad. Please let me know of errors. AUTHOR Frank J. Tobin fingerprint: 4F86 3BBB A816 6F0A 340F 6003 56FF D10A 260C 4FA3 COPYRIGHT Copyright (C) 1999 Frank Tobin 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, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA