Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Sign(3)		      User Contributed Perl Documentation	       Sign(3)

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

SYNOPSIS
	   use PGP::Sign;
	   ($signature,	$version) = pgp_sign ($keyid, $passphrase, @data);
	   $signer = pgp_verify	($signature, $version, @data);
	   @errors = PGP::Sign::pgp_error;

DESCRIPTION
       This module is designed to do one and only one thing securely and well;
       namely, generate	and check detached PGP signatures for some arbitrary
       data.  It doesn't do encryption,	it doesn't manage keyrings, it doesn't
       verify signatures, it just signs	things.	 This is ideal for
       applications like PGPMoose or control message generation	that just need
       a fast signing mechanism.  It supports versions 2.6, 5.0, and 6.5.2 of
       PGP, as well as GnuPG, and therefore supports any of the	signature
       types understood	by those programs provided they	are installed.

       The interface is	very simple; just call pgp_sign() with a key ID, a
       pass phrase, and	some data, or call pgp_verify()	with a signature (in
       the form	generated by pgp_sign()), a version number (which can be undef
       if you don't want to give a version), and some data.  The data can be
       specified in pretty much	any form you can possibly consider data	and a
       few you might not.  Scalars and arrays are passed along to PGP;
       references to arrays are	walked and passed one element at a time	(to
       avoid making a copy of the array); file handles,	globs, or references
       to globs	are read a line	at a time and passed to	PGP; and references to
       code are	even supported (see below).  About the only thing that we
       don't handle are	references to references (which	are just printed to
       PGP, which probably isn't what you wanted) and hashes (which are
       treated like arrays, which doesn't make a lot of	sense).

       If you give either function a reference to a sub, it will repeatedly
       call that sub, sending the results to PGP to be signed, until the sub
       returns undef.  What this lets you do is	pass the function an anonymous
       sub that	walks your internal data and performs some manipulations on it
       a line at a time, thus allowing you to sign a slightly modified form of
       your data (with initial dashes escaped, for example) without having to
       use up memory to	make an	internal copy of it.

       In a scalar context, pgp_sign() returns the signature as	an ASCII-
       armored block with embedded newlines (but no trailing newline).	In a
       list context, it	returns	a two-element list consisting of the signature
       as above	and the	PGP version that signed	it (if that information	was
       present in the signature).  Warning:  It's expected that	in the future
       this interface will change, and pgp_sign() will instead return a	list
       consisting of the ASCII-armored block and all headers found in the
       armor.

       If you're using GnuPG, pgp_sign() will pass it the option
       --force-v3-sigs so that it will generate	PGP 5.0-compatible signatures.

       pgp_sign() will return undef in the event of any	sort of	error.

       pgp_verify() returns the	signer of the message in the case of a good
       signature, the empty string in the case of a bad	signature, and undef
       in the event of some error.  It takes the same sort of data sources as
       pgp_sign().

       pgp_error() (which isn't	exported by default) returns the error
       encountered by the last pgp_sign() or pgp_verify(), or undef if there
       was no error.  In a list	context, a list	of lines is returned; in a
       scalar context, a long string with embedded newlines is returned.

       Six global variables can	be modified (note that these may eventually be
       partially or completely replaced	with an	interface via a
       PGP::Sign::config() call):

       $PGP::Sign::PGPS
	   The path to the program to use to generate signatures.  This	is set
	   at the time of installation,	but can	be overridden.

       $PGP::Sign::PGPV
	   The path to the program to use to verify signatures.	 This is set
	   at the time of installation,	but can	be overridden.	There are two
	   separate variables since PGP	5.0 uses two separate program names
	   for signing and verifying; for PGP 2.6, 6.5.2, or GnuPG, just set
	   both	this and $PGP::Sign::PGPS to the same value.

       $PGP::Sign::PGPPATH
	   The path to a directory containing the PGP key rings	that should be
	   used.  If this isn't	set, all versions of PGP will use the value of
	   the environment variable PGPPATH or $HOME/.pgp (the default).
	   GnuPG will use the value of the environment variable	GNUPGHOME or
	   $HOME/.gnupg.  Note that PGP	when signing may want to write
	   randseed.bin	(or randseed.rnd) in this directory if there isn't
	   already a random seed there,	so if you're encountering problems
	   with	signing, make sure the directory PGP is	using is writeable by
	   the user doing the signing.	Note also that if you're using GnuPG
	   and the Entropy Gathering Daemon (egd), the entropy socket or a
	   link	to it must be located in this directory.

       $PGP::Sign::PGPSTYLE
	   What	style of command line arguments	and responses to expect	from
	   PGP.	 The only three	valid values for this variable are "PGP2" for
	   PGP 2.6 behavior, "PGP5" for	PGP 5.0	behavior, "PGP6" for PGP 6.5
	   behavior, and "GPG" for GnuPG behavior.  What command line
	   arguments PGP::Sign uses when running PGP are entirely determined
	   by this variable.  It is set	at the time of installation, but can
	   be overridden.

       $PGP::Sign::TMPDIR
	   The directory in which temporary files are created.	Defaults to
	   TMPDIR if set, and /tmp if not.

       $PGP::Sign::MUNGE
	   If this variable is set to a	true value, PGP::Sign will
	   automatically strip trailing	spaces when signing or verifying
	   signatures.	This will make the resulting signatures	and
	   verification	compatible with	programs that generate attached
	   signatures (since PGP ignores trailing spaces when generating or
	   checking attached signatures).  See the more	extensive discussion
	   of whitespace below.

ENVIRONMENT
       PGPPATH
	   If $PGP::Sign::PGPPATH is set and $PGP::Sign::PGPSTYLE is something
	   other than "GPG", PGP::Sign sets PGPPATH to tell PGP	where to find
	   its key rings.  (GnuPG uses a command line argument instead.)

       TMPDIR
	   The directory in which to create temporary files.  Can be
	   overridden by changing $PGP::Sign::TMPDIR.  If not set, defaults
	   /tmp.

       In addition, all	environment variables that PGP normally	honors will be
       passed along to PGP and will likely have	their expected effects.	 This
       includes	PGPPATH, unless	it is overridden (see above).

DIAGNOSTICS
       Mostly the contents of @PGP::Sign::ERROR	(returned by pgp_error()) are
       just the	output of PGP.	The exceptions are:

       Execution of %s failed: %s
	   We couldn't fork off	a PGP process for some reason, given (at least
	   as the system reported it) after the	colon.

       No signature from PGP (command not found?)
	   We tried to generate	a signature but	the output from	the command we
	   tried to run	didn't contain anything	that looked like a signature.
	   One common explanation for this is that the path in
	   $PGP::Sign::PGPS is invalid and that	binary doesn't exist.

       %s returned exit	status %d
	   Some	command	that we	ran, or	tried to run, returned a non-zero exit
	   status.  %s will contain the	exact binary name that PGP::Sign was
	   attempting to run.

BUGS
       PGP::Sign does not currently work with binary data, as it
       unconditionally forces text mode	in PGP by using	the "-t" option.  This
       is a high priority to fix, but I'd like to implement some sort of
       generic way of setting PGP options rather than just adding more entry
       points.

       There's no way of generating version four DSS signatures.  This will be
       fixed by	the same improvement that will fix the previous	bug.

       PGP, all	versions that I	have available,	behaves	differently when
       generating attached signatures than when	generating detached
       signatures.  For	attached signatures, trailing whitespace in lines of
       the data	is not significant, but	for detached signatures	it is.	This,
       combined	with the fact that there's no way that I can see to get	PGP to
       verify a	detached signature without using files on disk,	means that in
       order to	maintain the intended default semantics	of this	module
       (manipulating detached signatures), I had to use	temporary files	in the
       implementation of pgp_verify().	PGP::Sign sets its umask before
       creating	those temporary	files and opens	them with O_EXCL, but files
       may be left behind in the event that an application using pgp_verify()
       crashes unexpectedly.  Setting $PGP::Sign::TMPDIR is recommended.

       Also, because of	this incompatibility, you need to be aware of what the
       process checking	the signatures you generate is expecting.  If that
       process is going	to turn	your signature into an attached	signature for
       verification (as	pgpverify does for Usenet control messages), then you
       need to pre-munge your data to remove trailing whitespace at the	ends
       of lines	before feeding it to PGP.  PGP::Sign will do that for you if
       you set $PGP::Sign::MUNGE to a true value.

       To add even more	confusion to the mix, earlier versions of GnuPG
       followed	an interpretation of RFC 2440 that specified text-mode
       signatures are performed	against	data with canonicalized	line endings
       and with	trailing whitespace removed (see section 5.2.1).  There	is no
       difference specified there between attached and detached	signatures,
       and GnuPG treated them both the same.  Versions of GnuPG	at least after
       1.0 appear to have changed to follow the	PGP behavior instead.

       When verification of a signature	fails, currently not very much
       information about what failed is	available (since an invalid signature
       isn't considered	an error in the	pgp_error() sense).

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 I'll get to that, or just replace this module	with
       one that	only uses GnuPG	as I see no reason to use any other PGP
       implementation at this point and	GnuPG has a much nicer programmatic
       interface.

       However,	just in	case, the interface to this module should not be
       considered stable yet; you may have to change your application when you
       upgrade to a newer version of this module.  The README will list	API
       changes.

RESTRICTIONS
       PGP::Sign passes	pass phrases to	PGP via	an open	one-ended pipe,	since
       this is the only	secure method (both command line switches and
       environment variables can potentially be	read by	other users on the
       same machine using ps).	This should be supported by any	recent version
       of PGP; I have tested it	against	2.6.2, 2.6.3i, 5.0, 6.5.2, GnuPG
       0.9.2, and GnuPG	1.0.1.	Implicit in this mechanism, though, is the
       requirement that	the operating system on	which you're running this
       module supports passing an open pipe to an exec()ed subprocess.	This
       may cause portability problems to certain substandard operating
       systems.

SEE ALSO
       pgp(1), pgps(1),	pgpv(1), gpg(1)

       RFC 2440, <http://www.rfc-editor.org/rfc/rfc2440.txt>, which specifies
       the OpenPGP message format.

       The current version of this module is always available from its web
       site at <http://www.eyrie.org/~eagle/software/pgp-sign/>.

AUTHOR
       Russ Allbery <rra@stanford.edu>

COPYRIGHT AND LICENSE
       Copyright 1997, 1998, 1999, 2000, 2002, 2004 Russ Allbery
       <rra@stanford.edu>.

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

HISTORY
       Based heavily on	work by	Andrew Gierth and benefitting greatly from
       input, comments,	suggestions, and help from him,	this module came about
       in the process of implementing PGPMoose signatures and control message
       signatures for Usenet.  PGPMoose	is the idea of Greg Rose, and
       signcontrol and pgpverify are the idea of David Lawrence.

       Support for PGPPATH, the	test suite, some bug fixes, and	the impetus to
       get another version released came from Andrew Ford.  Thank you.

       Original	support	for GnuPG from Todd Underwood and Monte	Mitzelfelt.
       Code for	using --status-fd based	on code	by Marco d'Itri.

perl v5.24.1			  2017-07-08			       Sign(3)

NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | DIAGNOSTICS | BUGS | CAVEATS | RESTRICTIONS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PGP::Sign&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help