view release on metacpan or  search on metacpan

lib/PGP/Sign.pm  view on Meta::CPAN

#
# $signature - The signature as an ASCII-armored string with embedded newlines
# @sources   - The data over which to check the signature
#
# Returns: The human-readable key ID of the signature
#          An empty string if the signature did not verify
#          undef on error
sub pgp_verify {
    my ($signature, $version, @sources) = @_;
    @ERROR = ();

    # Create the verifier object.
    my $verifier = PGP::Sign->new(
        {
            home   => $PGPPATH,
            munge  => $MUNGE,
            path   => $PGPV,
            style  => $PGPSTYLE,
            tmpdir => $TMPDIR,
        },
    );

    # Do the work, capturing any errors.
    my $signer = eval { $verifier->verify($signature, @sources) };
    if ($@) {
        @ERROR = split(m{\n}xms, $@);
        return;
    }

    # Return the results.
    return $signer;
}

# Retrieve errors from the previous pgp_sign() or pgp_verify() call.
#
# Historically the pgp_error() return value in list context had newlines at
# the end of each line, so add them back in.
#
# Returns: A list of GnuPG output and error messages in list context
#          The block of GnuPG output and error message in scalar context
## no critic (Freenode::Wantarray)
sub pgp_error {
    my @error_lines = map { "$_\n" } @ERROR;
    return wantarray ? @error_lines : join(q{}, @error_lines);
}
## use critic

##############################################################################
# Module return value and documentation
##############################################################################

# Make sure the module returns true.
1;

__DATA__

=for stopwords
Allbery DSS GNUPGHOME GPG GPG1 Gierth Mitzelfelt OpenPGP PGPMoose PGPPATH
TMPDIR canonicalized d'Itri egd keyrings pgpverify ps signcontrol
KEYID --force-v3-sigs --allow-weak-digest-algos --homedir --textmode cleartext
cryptographic gpg gpg1 gpgv homedir interoperable tmpdir

=head1 NAME

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

=head1 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();

=head1 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.

=head1 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.

=head1 CLASS METHODS

=over 4

=item 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.

=over 4

=item home

The GnuPG home directory containing keyrings and other configuration (as
controlled with the B<--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 C<style>
parameter).

=item 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.

=item path

The path to the GnuPG binary to use.  If not set, PGP::Sign defaults to
running B<gpg> (as found on the user's PATH) for a C<style> setting of "GPG"
and B<gpg1> (as found on the user's PATH) for a C<style> setting of "GPG1".

PGP::Sign does not support B<gpgv> (it passes options that it does not
understand).  This parameter should point to a full GnuPG implementation.

=item 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.

=item 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.

=back

=back

=head1 INSTANCE METHODS

=over 4

=item 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 B<--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
B<--force-v3-sigs> and B<--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().

=item 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().

lib/PGP/Sign.pm  view on Meta::CPAN

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().

=item 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.

=back

=head1 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.

=over 4

=item $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.

=item $PGP::Sign::PGPPATH

The GnuPG home directory containing keyrings and other configuration (as
controlled with the B<--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).

=item $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.

=item $PGP::Sign::PGPS

The path to the program used by pgp_sign().  If not set, PGP::Sign defaults to
running B<gpg> (as found on the user's PATH) if $PGP::Sign::PGPSTYLE is set to
"GPG" and B<gpg1> (as found on the user's PATH) if $PGP::Sign::PGPSTYLE is set
to "GPG1".

=item $PGP::Sign::PGPV

The path to the program used by pgp_verify().  If not set, PGP::Sign defaults
to running B<gpg> (as found on the user's PATH) if $PGP::Sign::PGPSTYLE is set
to "GPG" and B<gpg1> (as found on the user's PATH) if $PGP::Sign::PGPSTYLE is
set to "GPG1".

PGP::Sign does not support B<gpgv> (it passes options that it does not
understand).  This variable should point to a full GnuPG implementation.

=item $PGP::Sign::TMPDIR

The directory in which temporary files are created.  Defaults to whatever
directory File::Temp chooses to use by default.

=back

=head1 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 C<path> parameter to the new()
constructor or $PGP::Sign::PGPPATH for the legacy interface.

=head1 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:

=over 4

=item Execution of %s failed with status %s

GnuPG failed and returned the given status code.

=item 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.

=item print failed: %s

When writing out the data for signing or verification, print failed with the
given error.

=item Unknown OpenPGP backend style %s

The parameter to the C<style> option of the new() constructor, or the setting
of $PGP::Sign::PGPSTYLE, is not one of the recognized values.

=back

=head1 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 B<--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.

=head1 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.

=head1 AUTHOR

Russ Allbery <rra@cpan.org>

=head1 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.

=head1 SEE ALSO

gpg(1), gpg1(1), L<File::Temp>

L<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 L<https://www.eyrie.org/~eagle/software/pgp-sign/>.

=cut

# Local Variables:
# copyright-at-end-flag: t
# End: