.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "PGP::Sign 3pm" .TH PGP::Sign 3pm "2020-11-14" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" PGP::Sign \- Create detached PGP signatures for data, securely .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& use PGP::Sign; \& my $keyid = \*(Aq\*(Aq; \& my $passphrase = \*(Aq\*(Aq; \& my @data = (\*(Aqlines to\*(Aq, \*(Aqbe signed\*(Aq); \& \& # 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(); .Ve .SH "REQUIREMENTS" .IX Header "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. .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module supports only two OpenPGP operations: Generate and check detached \&\s-1PGP\s0 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. .PP There are two APIs, an object-oriented one and a legacy function \s-1API.\s0 The function \s-1API\s0 is configured with global variables and has other legacy warts. It will continue to be supported for backwards compatibility, but the object-oriented \s-1API\s0 is recommended for all new code. The object-oriented \s-1API\s0 was added in PGP::Sign 1.00. .SH "CLASS METHODS" .IX Header "CLASS METHODS" .IP "new(\s-1ARGS\s0)" 4 .IX Item "new(ARGS)" Create a new PGP::Sign object. This should be used for all subsequent \s-1API\s0 calls. \s-1ARGS\s0 should be a hash reference with one or more of the following keys. .RS 4 .IP "home" 4 .IX Item "home" The GnuPG home directory containing keyrings and other configuration (as controlled with the \fB\-\-homedir\fR flag or the \s-1GNUPGHOME\s0 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 \f(CW\*(C`style\*(C'\fR parameter). .IP "munge" 4 .IX 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. .IP "path" 4 .IX Item "path" The path to the GnuPG binary to use. If not set, PGP::Sign defaults to running \fBgpg\fR (as found on the user's \s-1PATH\s0) for a \f(CW\*(C`style\*(C'\fR setting of \*(L"\s-1GPG\*(R"\s0 and \fBgpg1\fR (as found on the user's \s-1PATH\s0) for a \f(CW\*(C`style\*(C'\fR setting of \*(L"\s-1GPG1\*(R".\s0 .Sp PGP::Sign does not support \fBgpgv\fR (it passes options that it does not understand). This parameter should point to a full GnuPG implementation. .IP "style" 4 .IX Item "style" The style of OpenPGP backend to use, chosen from \*(L"\s-1GPG\*(R"\s0 for GnuPG v2 (the default) and \*(L"\s-1GPG1\*(R"\s0 for GnuPG v1. .Sp If set to \*(L"\s-1GPG1\*(R",\s0 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 \s-1PGP 2.6.2,\s0 at the cost of using deprecated protocols and cryptographic algorithms with known weaknesses. .IP "tmpdir" 4 .IX 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. .RE .RS 4 .RE .SH "INSTANCE METHODS" .IX Header "INSTANCE METHODS" .IP "sign(\s-1KEYID, PASSPHRASE,\s0 SOURCE[, \s-1SOURCE ...\s0])" 4 .IX Item "sign(KEYID, PASSPHRASE, SOURCE[, SOURCE ...])" Create an OpenPGP signature over all the data contained in the \s-1SOURCE\s0 parameters, using \s-1KEYID\s0 to make the signature. \s-1PASSPHRASE\s0 is the passphrase for this private key. \s-1KEYID\s0 can be in any format accepted by GnuPG. .Sp The data given in the \s-1SOURCE\s0 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. .Sp 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. .Sp The returned signature is the ASCII-armored block with embedded newlines but with the marker lines and all headers stripped. .Sp PGP::Sign will always pass the \fB\-\-textmode\fR flag to GnuPG to force treatment of all input data as text and canonicalize line endings before generating the signature. If configured with the \*(L"\s-1GPG1\*(R"\s0 style, PGP::Sign will also pass the \&\fB\-\-force\-v3\-sigs\fR and \fB\-\-allow\-weak\-digest\-algos\fR flags to allow use of old \&\s-1PGP\s0 keys and generate signatures that are compatible with old versions of \s-1PGP.\s0 .Sp On error, \fBsign()\fR will call \fBcroak()\fR. .IP "verify(\s-1SIGNATURE,\s0 SOURCE[, \s-1SOURCE ...\s0])" 4 .IX 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 \&\fBsign()\fR: an ASCII-armored block with embedded newlines but with the marker lines and all headers stripped. \fBverify()\fR accepts data sources in the \s-1SOURCE\s0 parameters in the same formats accepted by \fBsign()\fR. .Sp \&\fBverify()\fR returns the user \s-1ID\s0 of the signer, not the fingerprint or hex key \s-1ID.\s0 If the signature does not verify, \fBverify()\fR will return the empty string. For other errors, it will call \fBcroak()\fR. .Sp As with \fBsign()\fR, PGP::Sign will always pass the \fB\-\-textmode\fR flag to GnuPG. It will also always pass \fB\-\-allow\-weak\-digest\-algos\fR to allow verification of old signatures. .SH "FUNCTIONS" .IX Header "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 \s-1API.\s0 .PP \&\fBpgp_sign()\fR and \fBpgp_verify()\fR are exported by default. .IP "pgp_sign(\s-1KEYID, PASSPHRASE,\s0 SOURCE[, \s-1SOURCE ...\s0])" 4 .IX Item "pgp_sign(KEYID, PASSPHRASE, SOURCE[, SOURCE ...])" Equivalent to creating a new PGP::Sign object and then calling its \fBsign()\fR method with the given parameters. The parameters to the object will be set based on the global variables described in \*(L"\s-1VARIABLES\*(R"\s0. The \f(CW\*(C`path\*(C'\fR parameter will be set to \f(CW$PGP::Sign::PGPS\fR. .Sp When called in a scalar context, \fBpgp_sign()\fR returns the signature, the same as the \fBsign()\fR method. When called in an array context, \fBpgp_sign()\fR returns a two-item list. The second item is the fixed string \*(L"GnuPG\*(R". 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 \fBpgp_sign()\fR now always returns that fixed value. .Sp On error, \fBpgp_sign()\fR returns undef or an empty list, depending on context. To get the corresponding errors, call \fBpgp_error()\fR. .IP "pgp_verify(\s-1SIGNATURE, VERSION,\s0 SOURCE[, \s-1SOURCE ...\s0])" 4 .IX Item "pgp_verify(SIGNATURE, VERSION, SOURCE[, SOURCE ...])" Equivalent to creating a new PGP::Sign object and then calling its \fBverify()\fR method with the \s-1SIGNATURE\s0 and \s-1SOURCE\s0 parameters. The parameters to the object will be set based on the global variables described in \*(L"\s-1VARIABLES\*(R"\s0. The \&\f(CW\*(C`path\*(C'\fR parameter will be set to \f(CW$PGP::Sign::PGPV\fR. .Sp The \s-1VERSION\s0 parameter may be anything and is ignored. .Sp \&\fBpgp_verify()\fR returns the user \s-1ID\s0 of the signer (not the hex key \s-1ID\s0 or fingerprint) on success, an empty string if the signature is invalid, and undef on any other error. On error, \fBpgp_sign()\fR returns undef or an empty list, depending on context. To get the corresponding errors, call \&\fBpgp_error()\fR. .IP "\fBpgp_error()\fR" 4 .IX Item "pgp_error()" Return the errors encountered by the last \fBpgp_sign()\fR or \fBpgp_verify()\fR call, or undef or the empty list depending on context if there were no error. A bad signature passed to \fBpgp_verify()\fR is not considered an error for this purpose. .Sp 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. .Sp This function is not exported by default and must be explicitly requested. .SH "VARIABLES" .IX Header "VARIABLES" The following variables control the behavior of the legacy function interface. They are not used for the object-oriented \s-1API,\s0 which replaces them with parameters to the \fBnew()\fR class method. .ie n .IP "$PGP::Sign::MUNGE" 4 .el .IP "\f(CW$PGP::Sign::MUNGE\fR" 4 .IX 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. .ie n .IP "$PGP::Sign::PGPPATH" 4 .el .IP "\f(CW$PGP::Sign::PGPPATH\fR" 4 .IX Item "$PGP::Sign::PGPPATH" The GnuPG home directory containing keyrings and other configuration (as controlled with the \fB\-\-homedir\fR flag or the \s-1GNUPGHOME\s0 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 \&\f(CW$PGP::Sign::PGPSTYLE\fR). .ie n .IP "$PGP::Sign::PGPSTYLE" 4 .el .IP "\f(CW$PGP::Sign::PGPSTYLE\fR" 4 .IX Item "$PGP::Sign::PGPSTYLE" What style of command line arguments and responses to expect from \s-1PGP.\s0 Must be either \*(L"\s-1GPG\*(R"\s0 for GnuPG v2 or \*(L"\s-1GPG1\*(R"\s0 for GnuPG v1. The default is \*(L"\s-1GPG\*(R".\s0 .Sp If set to \*(L"\s-1GPG1\*(R",\s0 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 \s-1PGP 2.6.2,\s0 at the cost of using deprecated protocols and cryptographic algorithms with known weaknesses. .ie n .IP "$PGP::Sign::PGPS" 4 .el .IP "\f(CW$PGP::Sign::PGPS\fR" 4 .IX Item "$PGP::Sign::PGPS" The path to the program used by \fBpgp_sign()\fR. If not set, PGP::Sign defaults to running \fBgpg\fR (as found on the user's \s-1PATH\s0) if \f(CW$PGP::Sign::PGPSTYLE\fR is set to \&\*(L"\s-1GPG\*(R"\s0 and \fBgpg1\fR (as found on the user's \s-1PATH\s0) if \f(CW$PGP::Sign::PGPSTYLE\fR is set to \*(L"\s-1GPG1\*(R".\s0 .ie n .IP "$PGP::Sign::PGPV" 4 .el .IP "\f(CW$PGP::Sign::PGPV\fR" 4 .IX Item "$PGP::Sign::PGPV" The path to the program used by \fBpgp_verify()\fR. If not set, PGP::Sign defaults to running \fBgpg\fR (as found on the user's \s-1PATH\s0) if \f(CW$PGP::Sign::PGPSTYLE\fR is set to \*(L"\s-1GPG\*(R"\s0 and \fBgpg1\fR (as found on the user's \s-1PATH\s0) if \f(CW$PGP::Sign::PGPSTYLE\fR is set to \*(L"\s-1GPG1\*(R".\s0 .Sp PGP::Sign does not support \fBgpgv\fR (it passes options that it does not understand). This variable should point to a full GnuPG implementation. .ie n .IP "$PGP::Sign::TMPDIR" 4 .el .IP "\f(CW$PGP::Sign::TMPDIR\fR" 4 .IX Item "$PGP::Sign::TMPDIR" The directory in which temporary files are created. Defaults to whatever directory File::Temp chooses to use by default. .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" All environment variables that GnuPG normally honors will be passed along to GnuPG and will likely have their expected effects. This includes \s-1GNUPGHOME,\s0 unless it is overridden by setting the \f(CW\*(C`path\*(C'\fR parameter to the \fBnew()\fR constructor or \f(CW$PGP::Sign::PGPPATH\fR for the legacy interface. .SH "DIAGNOSTICS" .IX Header "DIAGNOSTICS" Error messages thrown by \fBcroak()\fR or (for the legacy interface) are mostly the output from GnuPG or from IPC::Run if it failed to run GnuPG. The exceptions are: .ie n .IP "Execution of %s failed with status %s" 4 .el .IP "Execution of \f(CW%s\fR failed with status \f(CW%s\fR" 4 .IX Item "Execution of %s failed with status %s" GnuPG failed and returned the given status code. .IP "No signature returned by GnuPG" 4 .IX 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. .ie n .IP "print failed: %s" 4 .el .IP "print failed: \f(CW%s\fR" 4 .IX Item "print failed: %s" When writing out the data for signing or verification, print failed with the given error. .ie n .IP "Unknown OpenPGP backend style %s" 4 .el .IP "Unknown OpenPGP backend style \f(CW%s\fR" 4 .IX Item "Unknown OpenPGP backend style %s" The parameter to the \f(CW\*(C`style\*(C'\fR option of the \fBnew()\fR constructor, or the setting of \f(CW$PGP::Sign::PGPSTYLE\fR, is not one of the recognized values. .SH "BUGS" .IX Header "BUGS" The \fBverify()\fR method returns a user \s-1ID,\s0 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 \s-1ID.\s0 .PP PGP::Sign does not currently work with binary data, as it unconditionally forces text mode using the \fB\-\-textmode\fR option. .PP There is no way to tell PGP::Sign to not allow unsafe digest algorithms when generating or verifying signatures. .PP 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. .SH "CAVEATS" .IX Header "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 \s-1API\s0 changes. I'm not sure at this point whether that will ever happen. .SH "AUTHOR" .IX Header "AUTHOR" Russ Allbery .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 1997\-2000, 2002, 2004, 2018, 2020 Russ Allbery .PP This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBgpg\fR\|(1), \fBgpg1\fR\|(1), File::Temp .PP \&\s-1RFC 4880\s0 , which is the current specification for the OpenPGP message format. .PP The current version of PGP::Sign is available from \s-1CPAN,\s0 or directly from its web site at .