PGP::Sign is a Perl module designed to do one and only one thing securely and well; namely, generate and check detached PGP signatures for some arbitrary data. It doesn't do encryption, it doesn't manage keyrings, it doesn't verify signatures, it just signs things. This is ideal for applications like PGPMoose or control message generation that just need a fast signing mechanism. It supports versions 2.6, 5.0, and 6.5.2 of PGP, as well as GnuPG, and therefore supports any of the signature types understood by those programs provided they are installed.
The interface is very simple; just call pgp_sign() with a key ID, a pass phrase, and some data, or call pgp_verify() with a signature (in the form generated by pgp_sign()), a version number (which can be undef if you don't want to give a version), and some data. The data can be specified in pretty much any form you can possibly consider data and a few you might not. Scalars and arrays are passed along to PGP; references to arrays are walked and passed one element at a time (to avoid making a copy of the array); file handles, globs, or references to globs are read a line at a time and passed to PGP; and references to code are even supported (see below). About the only thing that we don't handle are references to references (which are just printed to PGP, which probably isn't what you wanted) and hashes (which are treated like arrays, which doesn't make a lot of sense).
If you give either function a reference to a sub, it will repeatedly call that sub, sending the results to PGP to be signed, until the sub returns undef. What this lets you do is pass the function an anonymous sub that walks your internal data and performs some manipulations on it a line at a time, thus allowing you to sign a slightly modified form of your data (with initial dashes escaped, for example) without having to use up memory to make an internal copy of it.
In a scalar context, pgp_sign() returns the signature as an ASCII-armored block with embedded newlines (but no trailing newline). In a list context, it returns a two-element list consisting of the signature as above and the PGP version that signed it (if that information was present in the signature). Warning: It's expected that in the future this interface will change, and pgp_sign() will instead return a list consisting of the ASCII-armored block and all headers found in the armor.
If you're using GnuPG, pgp_sign() will pass it the option --force-v3-sigs so that it will generate PGP 5.0-compatible signatures.
pgp_sign() will return undef in the event of any sort of error.
pgp_verify() returns the signer of the message in the case of a good signature, the empty string in the case of a bad signature, and undef in the event of some error. It takes the same sort of data sources as pgp_sign().
pgp_error() (which isn't exported by default) returns the error encountered by the last pgp_sign() or pgp_verify(), or undef if there was no error. In a list context, a list of lines is returned; in a scalar context, a long string with embedded newlines is returned.
Six global variables can be modified (note that these may eventually be partially or completely replaced with an interface via a PGP::Sign::config() call):
The path to the program to use to generate signatures. This is set at the time of installation, but can be overridden.
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.
The path to a directory containing the PGP key rings that should be used. If this isn't 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 isn't already a random seed there, so if you're encountering problems with signing, make sure the directory PGP is using is writeable by the user doing the signing. Note also that if you're using GnuPG and the Entropy Gathering Daemon (egd), the entropy socket or a link to it must be located in this directory.
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.
The directory in which temporary files are created. Defaults to TMPDIR if set, and /tmp if not.
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.
($signature, $version) = pgp_sign ($keyid, $passphrase, @data);
$signer = pgp_verify ($signature, $version, @data);
@errors = PGP::Sign::pgp_error;