Provided by: libpgp-sign-perl_1.04-1_all 
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
Copyright 1997-2000, 2002, 2004, 2018, 2020 Russ Allbery <rra@cpan.org> This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO
gpg(1), gpg1(1), File::Temp RFC 4880 <https://tools.ietf.org/html/rfc4880>, which is the current specification for the OpenPGP message format. The current version of PGP::Sign is available from CPAN, or directly from its web site at <https://www.eyrie.org/~eagle/software/pgp-sign/>.