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

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.