|$PGP::Sign::PGPS||The path to the program to use to generate signatures. This is set at the time of installation, but can be overridden.|
|$PGP::Sign::PGPV||The path to the program to use to verify signatures. This is set at the time of installation, but can be overridden. There are two separate variables since PGP 5.0 uses two separate program names for signing and verifying; for PGP 2.6, 6.5.2, or GnuPG, just set both this and $PGP::Sign::PGPS to the same value.|
|$PGP::Sign::PGPPATH||The path to a directory containing the PGP key rings that should be used. If this isnt set, all versions of PGP will use the value of the environment variable PGPPATH or $HOME/.pgp (the default). GnuPG will use the value of the environment variable GNUPGHOME or $HOME/.gnupg. Note that PGP when signing may want to write randseed.bin (or randseed.rnd) in this directory if there isnt already a random seed there, so if youre encountering problems with signing, make sure the directory PGP is using is writeable by the user doing the signing. Note also that if youre using GnuPG and the Entropy Gathering Daemon (egd), the entropy socket or a link to it must be located in this directory.|
|$PGP::Sign::PGPSTYLE||What style of command line arguments and responses to expect from PGP. The only three valid values for this variable are PGP2 for PGP 2.6 behavior, PGP5 for PGP 5.0 behavior, PGP6 for PGP 6.5 behavior, and GPG for GnuPG behavior. What command line arguments PGP::Sign uses when running PGP are entirely determined by this variable. It is set at the time of installation, but can be overridden.|
|$PGP::Sign::TMPDIR||The directory in which temporary files are created. Defaults to TMPDIR if set, and /tmp if not.|
|$PGP::Sign::MUNGE||If this variable is set to a true value, PGP::Sign will automatically strip trailing spaces when signing or verifying signatures. This will make the resulting signatures and verification compatible with programs that generate attached signatures (since PGP ignores trailing spaces when generating or checking attached signatures). See the more extensive discussion of whitespace below.|
In addition, all environment variables that PGP normally honors will be passed along to PGP and will likely have their expected effects. This includes PGPPATH, unless it is overridden (see above).
PGPPATH If $PGP::Sign::PGPPATH is set and $PGP::Sign::PGPSTYLE is something other than GPG, PGP::Sign sets PGPPATH to tell PGP where to find its key rings. (GnuPG uses a command line argument instead.) TMPDIR The directory in which to create temporary files. Can be overridden by changing $PGP::Sign::TMPDIR. If not set, defaults /tmp.
Mostly the contents of @PGP::Sign::ERROR (returned by pgp_error()) are just the output of PGP. The exceptions are:
Execution of %s failed: %s We couldnt fork off a PGP process for some reason, given (at least as the system reported it) after the colon. No signature from PGP (command not found?) We tried to generate a signature but the output from the command we tried to run didnt contain anything that looked like a signature. One common explanation for this is that the path in $PGP::Sign::PGPS is invalid and that binary doesnt exist. %s returned exit status %d Some command that we ran, or tried to run, returned a non-zero exit status. %s will contain the exact binary name that PGP::Sign was attempting to run.
PGP::Sign does not currently work with binary data, as it unconditionally forces text mode in PGP by using the -t option. This is a high priority to fix, but Id like to implement some sort of generic way of setting PGP options rather than just adding more entry points.
PGP, all versions that I have available, behaves differently when generating attached signatures than when generating detached signatures. For attached signatures, trailing whitespace in lines of the data is not significant, but for detached signatures it is. This, combined with the fact that theres no way that I can see to get PGP to verify a detached signature without using files on disk, means that in order to maintain the intended default semantics of this module (manipulating detached signatures), I had to use temporary files in the implementation of pgp_verify(). PGP::Sign sets its umask before creating those temporary files and opens them with O_EXCL, but files may be left behind in the event that an application using pgp_verify() crashes unexpectedly. Setting $PGP::Sign::TMPDIR is recommended.
Also, because of this incompatibility, you need to be aware of what the process checking the signatures you generate is expecting. If that process is going to turn your signature into an attached signature for verification (as pgpverify does for Usenet control messages), then you need to pre-munge your data to remove trailing whitespace at the ends of lines before feeding it to PGP. PGP::Sign will do that for you if you set $PGP::Sign::MUNGE to a true value.
To add even more confusion to the mix, earlier versions of GnuPG followed an interpretation of RFC 2440 that specified text-mode signatures are performed against data with canonicalized line endings and with trailing whitespace removed (see section 5.2.1). There is no difference specified there between attached and detached signatures, and GnuPG treated them both the same. Versions of GnuPG at least after 1.0 appear to have changed to follow the PGP behavior instead.
When verification of a signature fails, currently not very much information about what failed is available (since an invalid signature isnt considered an error in the pgp_error() sense).
This module is fairly good at what it does, but it doesnt do very much. At one point, I had plans to provide more options and more configurability in the future, particularly the ability to handle binary data, that would probably mean API changes. Im not sure at this point whether Ill get to that, or just replace this module with one that only uses GnuPG as I see no reason to use any other PGP implementation at this point and GnuPG has a much nicer programmatic interface.
However, just in case, the interface to this module should not be considered stable yet; you may have to change your application when you upgrade to a newer version of this module. The README will list API changes.
PGP::Sign passes pass phrases to PGP via an open one-ended pipe, since this is the only secure method (both command line switches and environment variables can potentially be read by other users on the same machine using ps). This should be supported by any recent version of PGP; I have tested it against 2.6.2, 2.6.3i, 5.0, 6.5.2, GnuPG 0.9.2, and GnuPG 1.0.1. Implicit in this mechanism, though, is the requirement that the operating system on which youre running this module supports passing an open pipe to an exec()ed subprocess. This may cause portability problems to certain substandard operating systems.
pgp(1), pgps(1), pgpv(1), gpg(1)
RFC 2440, <http://www.rfc-editor.org/rfc/rfc2440.txt>, which specifies the OpenPGP message format.
Russ Allbery <email@example.com>
Copyright 1997, 1998, 1999, 2000, 2002, 2004 Russ Allbery <firstname.lastname@example.org>.
This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.
Based heavily on work by Andrew Gierth and benefitting greatly from input, comments, suggestions, and help from him, this module came about in the process of implementing PGPMoose signatures and control message signatures for Usenet. PGPMoose is the idea of Greg Rose, and signcontrol and pgpverify are the idea of David Lawrence.
Support for PGPPATH, the test suite, some bug fixes, and the impetus to get another version released came from Andrew Ford. Thank you.
Original support for GnuPG from Todd Underwood and Monte Mitzelfelt. Code for using --status-fd based on code by Marco dItri.
|perl v5.20.3||SIGN (3)||2016-04-03|