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.