Linux Certif

Toute la documentation sur la certification Linux LPI

PGP::GPG::MessageProcessor.3pm

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>

OpenPGP fingerprint:

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

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