NAME

PGP::Sign - Create detached PGP signatures for data, securely

SYNOPSIS

    use PGP::Sign;
    my $keyid = '<some-key-id>';
    my $passphrase = '<passphrase-for-key>';
    my @data = ('lines to', 'be signed');

    # Object-oriented API.
    my $pgp = PGP::Sign->new();
    my $signature = $pgp->sign($keyid, $passphrase, @data);
    my $signer = $pgp->verify($signature, @data);

    # Legacy API.
    $signature = pgp_sign($keyid, $passphrase, @data);
    $signer = pgp_verify($signature, undef, @data);
    my @errors = PGP::Sign::pgp_error();

REQUIREMENTS

Perl 5.20 or later, the IPC::Run module, and either GnuPG v1 or GnuPG v2. It is only tested on UNIX-derivative systems and is moderately unlikely to work on Windows.

DESCRIPTION

This module supports only two OpenPGP operations: Generate and check detached PGP signatures for arbitrary text data. It doesn't do encryption, it doesn't manage keyrings, it doesn't verify signatures, it just signs things and checks signatures. It was written to support Usenet applications like control message generation and PGPMoose.

There are two APIs, an object-oriented one and a legacy function API. The function API is configured with global variables and has other legacy warts. It will continue to be supported for backwards compatibility, but the object-oriented API is recommended for all new code. The object-oriented API was added in PGP::Sign 1.00.

CLASS METHODS

new(ARGS): Create a new PGP::Sign object. This should be used for all subsequent API calls. ARGS should be a hash reference with one or more of the following keys.

home: The GnuPG home directory containing keyrings and other configuration (as controlled with the --homedir flag or the GNUPGHOME environment variable). If not set, uses the GnuPG default. This directory must contain keyrings with the secret keys used for signing and the public keys used for verification, and must be in the format expected by the GnuPG version used (see the "style" parameter).
munge: If set to a true value, PGP::Sign will strip trailing spaces (only spaces, not arbitrary whitespace) when signing or verifying signatures. This will make the resulting signatures and verification compatible with programs that generate or verify cleartext signatures, since OpenPGP implementations ignore trailing spaces when generating or checking cleartext signatures.
path: The path to the GnuPG binary to use. If not set, PGP::Sign defaults to running gpg (as found on the user's PATH) for a "style" setting of "GPG" and gpg1 (as found on the user's PATH) for a "style" setting of "GPG1".
PGP::Sign does not support gpgv (it passes options that it does not understand). This parameter should point to a full GnuPG implementation.
style: The style of OpenPGP backend to use, chosen from "GPG" for GnuPG v2 (the default) and "GPG1" for GnuPG v1.
If set to "GPG1", PGP::Sign will pass the command-line flags for maximum backwards compatibility, including forcing v3 signatures instead of the current version. This is interoperable with PGP 2.6.2, at the cost of using deprecated protocols and cryptographic algorithms with known weaknesses.
tmpdir: The path to a temporary directory to use when verifying signatures. PGP::Sign has to write files to disk for signature verification and will do so in this directory. If not given, PGP::Sign will use File::Temp's default.

INSTANCE METHODS

sign(KEYID, PASSPHRASE, SOURCE[, SOURCE ...])

Create an OpenPGP signature over all the data contained in the SOURCE parameters, using KEYID to make the signature. PASSPHRASE is the passphrase for this private key. KEYID can be in any format accepted by GnuPG.

The data given in the SOURCE parameters can be given in a wide variety of formats: scalar variables, arrays, references to scalars or arrays, globs or references to globs (assumed to be an open file), IO::File objects, or code references.

If given a code reference, that function will be repeatedly called to obtain more data until it returns undef. This allows passing in an anonymous sub that transforms the data on the fly (escaping initial dashes, for instance) without having to make an in-memory copy.

The returned signature is the ASCII-armored block with embedded newlines but with the marker lines and all headers stripped.

PGP::Sign will always pass the --textmode flag to GnuPG to force treatment of all input data as text and canonicalize line endings before generating the signature. If configured with the "GPG1" style, PGP::Sign will also pass the --force-v3-sigs and --allow-weak-digest-algos flags to allow use of old PGP keys and generate signatures that are compatible with old versions of PGP.

On error, sign() will call croak().

verify(SIGNATURE, SOURCE[, SOURCE ...])

Verify a signature. PGP::Sign will attempt to verify the signature in detached mode. The signature must be in the same format as returned by sign(): an ASCII-armored block with embedded newlines but with the marker lines and all headers stripped. verify() accepts data sources in the SOURCE parameters in the same formats accepted by sign().

verify() returns the user ID of the signer, not the fingerprint or hex key ID. If the signature does not verify, verify() will return the empty string. For other errors, it will call croak().

As with sign(), PGP::Sign will always pass the --textmode flag to GnuPG. It will also always pass --allow-weak-digest-algos to allow verification of old signatures.

FUNCTIONS

The legacy function interface is supported for backwards compatibility with earlier versions of PGP::Sign. It is not recommended for any new code. Prefer the object-oriented API.

pgp_sign() and pgp_verify() are exported by default.

pgp_sign(KEYID, PASSPHRASE, SOURCE[, SOURCE ...])

Equivalent to creating a new PGP::Sign object and then calling its sign() method with the given parameters. The parameters to the object will be set based on the global variables described in "VARIABLES". The "path" parameter will be set to $PGP::Sign::PGPS.

When called in a scalar context, pgp_sign() returns the signature, the same as the sign() method. When called in an array context, pgp_sign() returns a two-item list. The second item is the fixed string "GnuPG". Historically, this was the version of the OpenPGP implementation, taken from the Version header of the signature, but this header is no longer set by GnuPG and had no practical use, so pgp_sign() now always returns that fixed value.

On error, pgp_sign() returns undef or an empty list, depending on context. To get the corresponding errors, call pgp_error().

pgp_verify(SIGNATURE, VERSION, SOURCE[, SOURCE ...])

Equivalent to creating a new PGP::Sign object and then calling its verify() method with the SIGNATURE and SOURCE parameters. The parameters to the object will be set based on the global variables described in "VARIABLES". The "path" parameter will be set to $PGP::Sign::PGPV.

The VERSION parameter may be anything and is ignored.

pgp_verify() returns the user ID of the signer (not the hex key ID or fingerprint) on success, an empty string if the signature is invalid, and undef on any other error. On error, pgp_sign() returns undef or an empty list, depending on context. To get the corresponding errors, call pgp_error().

pgp_error()

Return the errors encountered by the last pgp_sign() or pgp_verify() call, or undef or the empty list depending on context if there were no error. A bad signature passed to pgp_verify() is not considered an error for this purpose.

In an array context, a list of lines (including the ending newlines) is returned. In a scalar context, a string with embedded newlines is returned.

This function is not exported by default and must be explicitly requested.

VARIABLES

The following variables control the behavior of the legacy function interface. They are not used for the object-oriented API, which replaces them with parameters to the new() class method.

$PGP::Sign::MUNGE: If set to a true value, PGP::Sign will strip trailing spaces (only spaces, not arbitrary whitespace) when signing or verifying signatures. This will make the resulting signatures and verification compatible with programs that generate or verify cleartext signatures, since OpenPGP implementations ignore trailing spaces when generating or checking cleartext signatures.
$PGP::Sign::PGPPATH: The GnuPG home directory containing keyrings and other configuration (as controlled with the --homedir flag or the GNUPGHOME environment variable). If not set, uses the GnuPG default. This directory must contain keyrings with the secret keys used for signing and the public keys used for verification, and must be in the format expected by the GnuPG version used (see $PGP::Sign::PGPSTYLE).
$PGP::Sign::PGPSTYLE: What style of command line arguments and responses to expect from PGP. Must be either "GPG" for GnuPG v2 or "GPG1" for GnuPG v1. The default is "GPG".
If set to "GPG1", PGP::Sign will pass the command-line flags for maximum backwards compatibility, including forcing v3 signatures instead of the current version. This is interoperable with PGP 2.6.2, at the cost of using deprecated protocols and cryptographic algorithms with known weaknesses.
$PGP::Sign::PGPS: The path to the program used by pgp_sign(). If not set, PGP::Sign defaults to running gpg (as found on the user's PATH) if $PGP::Sign::PGPSTYLE is set to "GPG" and gpg1 (as found on the user's PATH) if $PGP::Sign::PGPSTYLE is set to "GPG1".
$PGP::Sign::PGPV: The path to the program used by pgp_verify(). If not set, PGP::Sign defaults to running gpg (as found on the user's PATH) if $PGP::Sign::PGPSTYLE is set to "GPG" and gpg1 (as found on the user's PATH) if $PGP::Sign::PGPSTYLE is set to "GPG1".
PGP::Sign does not support gpgv (it passes options that it does not understand). This variable should point to a full GnuPG implementation.
$PGP::Sign::TMPDIR: The directory in which temporary files are created. Defaults to whatever directory File::Temp chooses to use by default.

ENVIRONMENT

All environment variables that GnuPG normally honors will be passed along to GnuPG and will likely have their expected effects. This includes GNUPGHOME, unless it is overridden by setting the "path" parameter to the new() constructor or $PGP::Sign::PGPPATH for the legacy interface.

DIAGNOSTICS

Error messages thrown by croak() or (for the legacy interface) are mostly the output from GnuPG or from IPC::Run if it failed to run GnuPG. The exceptions are:

Execution of %s failed with status %s: GnuPG failed and returned the given status code.
No signature returned by GnuPG: We tried to generate a signature but, although GnuPG succeeded, the output didn't contain anything that looked like a signature.
print failed: %s: When writing out the data for signing or verification, print failed with the given error.
Unknown OpenPGP backend style %s: The parameter to the "style" option of the new() constructor, or the setting of $PGP::Sign::PGPSTYLE, is not one of the recognized values.

BUGS

The verify() method returns a user ID, which is a poor choice and may be insecure unless used very carefully. PGP::Sign should support an option to return richer information about the signature verification, including the long hex key ID.

PGP::Sign does not currently work with binary data, as it unconditionally forces text mode using the --textmode option.

There is no way to tell PGP::Sign to not allow unsafe digest algorithms when generating or verifying signatures.

The whitespace munging support addresses the most common difference between cleartext and detached signatures, but does not deal with all of the escaping issues that are different between those two modes. It's likely that extracting a cleartext signature and verifying it with this module or using a signature from this module as a cleartext signature will not work in all cases.

CAVEATS

This module is fairly good at what it does, but it doesn't 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. I'm not sure at this point whether that will ever happen.

AUTHOR

Russ Allbery <rra@cpan.org>

COPYRIGHT AND LICENSE

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.