view release on metacpan or  search on metacpan

PGP/Pipe.pm  view on Meta::CPAN

sub Debug
{
  my (@args) = @_;

  return if (! defined $PGP::Pipe::debug);

  print STDERR @args, "\n";
}


=item * PGP::Exec

	$pid = Exec $pgp $args, $in, $out, $err, $nobatchmode;

Execute the PGP command and attach the C<$in>, C<$out>, C<$err> file handles. 
This should be fine for the moment, but need to look into making
sure that data is not written to a temporary file anywhere. The C<$nobatchmode>
parameter causes the PGP command to be executed without the +batchmode
parameter. This seems to only be necessary when a key is being signed.

The $args variable can have several substituted strings:

	%p	PGP path variable
	%r	Path to PGP keyring
	%k	Specified user

B<Note:> The above substitutions may change at any time. It is not
advised that you write applications with substitutions. Almost
certainly, the next release will not include substitutions.

The file handle variables--C<$in>, C<$out> and C<$err>--are send as
normal filehandle names, but they reside in the PGP package. For
example, the following procedure call is made:

	PGP->Exec ($args, FIN, FOUT, FERR);

Even though the file handles were specified as C<FIN>, C<FOUT> and
C<FERR>; they must be referred to as C<PGP::FIN>, C<PGP::FOUT> and
C<PGP::FERR> in the orignal procedure that made the call.

=cut


sub Exec
{
  my ($self, $args, $in, $out, $err, $nobatchmode) = @_;
  my ($pgppath, $pgpcmd, $baseopts);
  my ($fin, $fout, $ferr);
  
  if ($nobatchmode)
    { $baseopts = '+force +verbose=1' }
   else
    { $baseopts = '+force +batchmode +verbose=1' };
  
  # Variable substitutions
  $args =~ s/%p/$self->{PGPPATH}/g;
  $args =~ s/%r/$self->{PGPPATH}\/$self->{Keyring}/g;   # PGP::Keyring
  $args =~ s/%k/0x$self->{Keyid}/g;			# PGP::Key
			  
  # Put the file descriptors in the callers package
  $fin = (caller)[0] . "::$in";
  $fout = (caller)[0] . "::$out";
  $ferr = (caller)[0] . "::$err";
  
  Debug ("PGP::Exec=$self->{PGPexec} $baseopts $args");
  
  # just to make sure that PGPPATH is exported!
  $ENV{PGPPATH} = $self->{PGPPATH};
  $result = open3 ($fin, $fout, $ferr, "$self->{PGPexec} $baseopts $args") || croak "PGP command error";
}


=item * PGP::Sign

	$signed_document = Sign $pgp %args;

The C<Sign> procedure will take a file or data and sign with a PGP
secret key. The default behavior is to sign the data with the last
secret key added to the keyring, but that can be overridden with the
I<Key> argument. This method always returns the signed document.

The C<%args> consist of a series of keys and values. Since there are
several variations in the way data can be signed, not all the
following options must be specified. This approach also makes it much
easier to scale to new versions of PGP with more options.

	Armor		The output should be ASCII armored
	Clear		Produce a "clear" signature
	Encrypt		Encrypt the resulting signed document with
			the given keyobj
	Detach		Create a detached signature
	File		Sign the specified file
	Key		Sign with the specified key object
	Nosave		Do not allow user to save message
	Password	The password to use for signing
	Signfile	The filename of the signed document
	Text		Data to be signed.
	Wipe		Remove the orignal file

The only absolute argument that is always required is the C<Password>. 

B<Examples>

 Sign $pgp Password => 'xyz', File => '/etc/motd', Clear => 1, Armor => 1;

This would return a signed copy of the F</etc/motd> file. In this
case, we use a file as the input, but the output is returned at the
method's termination. The orignal file remains in the clear, and the
signature is ASCII armored (Base64). 

 Sign $pgp Password => 'abc', Text => 'Important info', Armor => 1,
           Signfile => 'signed.asc', Key => $keyobj;

This is sort of the reverse of the first example. It takes what is in
the C<Text> field and signs it. It then puts the result in the file
F<signed.asc> and returns it to the caller. In this case, the entire
message is ASCII armored including the orignal text (i.e. C<Text>).
We also specify another secret key to produce the signature. For more
information on the the key objects, please see L<"PGP::Key"> section.

=cut