README
1 PGP::Sign 1.03
2 (create and verify detached PGP signatures)
3 Maintained by Russ Allbery <rra@cpan.org>
4
5 Copyright 1997-2000, 2002, 2004, 2018, 2020 Russ Allbery <rra@cpan.org>.
6 This software is distributed under the same terms as Perl itself.
7 Please see the section LICENSE below for more information.
8
9BLURB
10
11 PGP::Sign is a Perl module for generating and verifying detached OpenPGP
12 signatures of textual data using GnuPG. It was written to support
13 Netnews article signatures for signed control messages and PGPMoose.
14
15DESCRIPTION
16
17 PGP::Sign is a Perl module that can generate and verify OpenPGP
18 signatures on some data. Currently, only textual data (data that can be
19 processed using GnuPG's --textmode option) is supported. It uses GnuPG
20 under the hood to do the work.
21
22 The original purpose of this module was to factor out common code in a
23 News::Article class written by Andrew Gierth that handled PGPMoose and
24 control message signatures. It is used to verify control message
25 signatures for the ftp.isc.org Netnews metadata archive, and to generate
26 signed control messages for the Big Eight Usenet hierarchies.
27
28 Data to be signed or verified can be passed into PGP::Sign in a wide
29 variety of formats: scalars, arrays, open files, even code references
30 that act as generators. Keys with passphrases are supported and the
31 passphrase is passed to GnuPG securely (although getting the passphrase
32 to the PGP::Sign module is a problem for the calling application).
33
34 This module supports both GnuPG v2 and GnuPG v1 and, when used with
35 GnuPG v1, supports using OpenPGP keys and generating and verifying
36 signatures that are backward-compatible with PGP 2.6.2.
37
38 PGP::Sign provides both a (recommended) object-oriented API and a
39 (legacy) function-based API that uses global variables for configuration
40 and is backward-compatible with earlier versions of PGP::Sign.
41
42REQUIREMENTS
43
44 Perl 5.20 or later and Module::Build are required to build this module,
45 and IPC::Run is required to use it. Either GnuPG v2 (version 2.1.23 or
46 later) or GnuPG v1 (version 1.4.20 or later) is also required. The
47 implementation of GnuPG can be selected at runtime.
48
49 PGP::Sign requires the ability to redirect higher-numbered file
50 descriptors via IPC::Run, and thus will not work on Windows unless Perl
51 is built with some UNIX emulation layer that supports this. It has also
52 never been tested with Gpg4win.
53
54BUILDING AND INSTALLATION
55
56 PGP::Sign uses Module::Build and can be installed using the same process
57 as any other Module::Build module:
58
59 perl Build.PL
60 ./Build
61 ./Build install
62
63 You will have to run the last command as root unless you're installing
64 into a local Perl module tree in your home directory.
65
66TESTING
67
68 PGP::Sign comes with a test suite, which you can run after building
69 with:
70
71 ./Build test
72
73 If a test fails, you can run a single test with verbose output via:
74
75 ./Build test --test_files <path-to-test>
76
77 If the gpg binary found first on the PATH is too old, the tests will be
78 skipped rather than fail. This may not always be desirable, since the
79 module is not usable on such a system without configuration, but the
80 module can still be configured to use a GnuPG binary found elsewhere and
81 therefore this doesn't represent an error in the module itself.
82
83 The following additional Perl modules will be used by the test suite if
84 present:
85
86 * Devel::Cover
87 * Perl::Critic::Freenode
88 * Test::MinimumVersion
89 * Test::Perl::Critic
90 * Test::Pod
91 * Test::Pod::Coverage
92 * Test::Spelling
93 * Test::Strict
94 * Test::Synopsis
95
96 All are available on CPAN. Those tests will be skipped if the modules
97 are not available.
98
99 To enable tests that don't detect functionality problems but are used to
100 sanity-check the release, set the environment variable RELEASE_TESTING
101 to a true value. To enable tests that may be sensitive to the local
102 environment or that produce a lot of false positives without uncovering
103 many problems, set the environment variable AUTHOR_TESTING to a true
104 value.
105
106SUPPORT
107
108 The PGP::Sign web page at:
109
110 https://www.eyrie.org/~eagle/software/pgp-sign/
111
112 will always have the current version of this package, the current
113 documentation, and pointers to any additional resources.
114
115 For bug tracking, use the CPAN bug tracker at:
116
117 https://rt.cpan.org/Dist/Display.html?Name=PGP-Sign
118
119 However, please be aware that I tend to be extremely busy and work
120 projects often take priority. I'll save your report and get to it as
121 soon as I can, but it may take me a couple of months.
122
123SOURCE REPOSITORY
124
125 PGP::Sign is maintained using Git. You can access the current source on
126 GitHub at:
127
128 https://github.com/rra/pgp-sign
129
130 or by cloning the repository at:
131
132 https://git.eyrie.org/git/perl/pgp-sign.git
133
134 or view the repository via the web at:
135
136 https://git.eyrie.org/?p=perl/pgp-sign.git
137
138 The eyrie.org repository is the canonical one, maintained by the author,
139 but using GitHub is probably more convenient for most purposes. Pull
140 requests are gratefully reviewed and normally accepted. It's probably
141 better to use the CPAN bug tracker than GitHub issues, though, to keep
142 all Perl module issues in the same place.
143
144LICENSE
145
146 The PGP::Sign package as a whole is covered by the following copyright
147 statement and license:
148
149 Copyright 1997-2000, 2002, 2004, 2018, 2020
150 Russ Allbery <rra@cpan.org>
151
152 This program is free software; you may redistribute it and/or modify
153 it under the same terms as Perl itself. This means that you may
154 choose between the two licenses that Perl is released under: the GNU
155 GPL and the Artistic License. Please see your Perl distribution for
156 the details and copies of the licenses.
157
158 Some files in this distribution are individually released under
159 different licenses, all of which are compatible with the above general
160 package license but which may require preservation of additional
161 notices. All required notices, and detailed information about the
162 licensing of each file, are recorded in the LICENSE file.
163
164 Files covered by a license with an assigned SPDX License Identifier
165 include SPDX-License-Identifier tags to enable automated processing of
166 license information. See https://spdx.org/licenses/ for more
167 information.
168
169 For any copyright range specified by files in this package as YYYY-ZZZZ,
170 the range specifies every single year in that closed interval.
171
README.md
1# PGP::Sign 1.03
2
3[](https://github.com/rra/pgp-sign/actions)
5[](https://metacpan.org/release/PGP-Sign)
7[](https://github.com/rra/pgp-sign/blob/master/LICENSE)
8[](https://tracker.debian.org/pkg/libpgp-sign-perl)
10
11Copyright 1997-2000, 2002, 2004, 2018, 2020 Russ Allbery <rra@cpan.org>.
12This software is distributed under the same terms as Perl itself. Please
13see the section [License](#license) below for more information.
14
15## Blurb
16
17PGP::Sign is a Perl module for generating and verifying detached OpenPGP
18signatures of textual data using GnuPG. It was written to support Netnews
19article signatures for signed control messages and PGPMoose.
20
21## Description
22
23PGP::Sign is a Perl module that can generate and verify OpenPGP signatures
24on some data. Currently, only textual data (data that can be processed
25using GnuPG's `--textmode` option) is supported. It uses GnuPG under the
26hood to do the work.
27
28The original purpose of this module was to factor out common code in a
29News::Article class written by Andrew Gierth that handled PGPMoose and
30control message signatures. It is used to verify control message
31signatures for the ftp.isc.org Netnews metadata archive, and to generate
32signed control messages for the Big Eight Usenet hierarchies.
33
34Data to be signed or verified can be passed into PGP::Sign in a wide
35variety of formats: scalars, arrays, open files, even code references that
36act as generators. Keys with passphrases are supported and the passphrase
37is passed to GnuPG securely (although getting the passphrase to the
38PGP::Sign module is a problem for the calling application).
39
40This module supports both GnuPG v2 and GnuPG v1 and, when used with GnuPG
41v1, supports using OpenPGP keys and generating and verifying signatures
42that are backward-compatible with PGP 2.6.2.
43
44PGP::Sign provides both a (recommended) object-oriented API and a (legacy)
45function-based API that uses global variables for configuration and is
46backward-compatible with earlier versions of PGP::Sign.
47
48## Requirements
49
50Perl 5.20 or later and Module::Build are required to build this module,
51and IPC::Run is required to use it. Either GnuPG v2 (version 2.1.23 or
52later) or GnuPG v1 (version 1.4.20 or later) is also required. The
53implementation of GnuPG can be selected at runtime.
54
55PGP::Sign requires the ability to redirect higher-numbered file
56descriptors via IPC::Run, and thus will not work on Windows unless Perl is
57built with some UNIX emulation layer that supports this. It has also
58never been tested with Gpg4win.
59
60## Building and Installation
61
62PGP::Sign uses Module::Build and can be installed using the same process
63as any other Module::Build module:
64
65```
66 perl Build.PL
67 ./Build
68 ./Build install
69```
70
71You will have to run the last command as root unless you're installing
72into a local Perl module tree in your home directory.
73
74## Testing
75
76PGP::Sign comes with a test suite, which you can run after building with:
77
78```
79 ./Build test
80```
81
82If a test fails, you can run a single test with verbose output via:
83
84```
85 ./Build test --test_files <path-to-test>
86```
87
88If the gpg binary found first on the PATH is too old, the tests will be
89skipped rather than fail. This may not always be desirable, since the
90module is not usable on such a system without configuration, but the
91module can still be configured to use a GnuPG binary found elsewhere and
92therefore this doesn't represent an error in the module itself.
93
94The following additional Perl modules will be used by the test suite if
95present:
96
97* Devel::Cover
98* Perl::Critic::Freenode
99* Test::MinimumVersion
100* Test::Perl::Critic
101* Test::Pod
102* Test::Pod::Coverage
103* Test::Spelling
104* Test::Strict
105* Test::Synopsis
106
107All are available on CPAN. Those tests will be skipped if the modules are
108not available.
109
110To enable tests that don't detect functionality problems but are used to
111sanity-check the release, set the environment variable `RELEASE_TESTING`
112to a true value. To enable tests that may be sensitive to the local
113environment or that produce a lot of false positives without uncovering
114many problems, set the environment variable `AUTHOR_TESTING` to a true
115value.
116
117## Support
118
119The [PGP::Sign web page](https://www.eyrie.org/~eagle/software/pgp-sign/)
120will always have the current version of this package, the current
121documentation, and pointers to any additional resources.
122
123For bug tracking, use the [CPAN bug
124tracker](https://rt.cpan.org/Dist/Display.html?Name=PGP-Sign). However,
125please be aware that I tend to be extremely busy and work projects often
126take priority. I'll save your report and get to it as soon as I can, but
127it may take me a couple of months.
128
129## Source Repository
130
131PGP::Sign is maintained using Git. You can access the current source on
132[GitHub](https://github.com/rra/pgp-sign) or by cloning the repository at:
133
134https://git.eyrie.org/git/perl/pgp-sign.git
135
136or [view the repository on the
137web](https://git.eyrie.org/?p=perl/pgp-sign.git).
138
139The eyrie.org repository is the canonical one, maintained by the author,
140but using GitHub is probably more convenient for most purposes. Pull
141requests are gratefully reviewed and normally accepted. It's probably
142better to use the CPAN bug tracker than GitHub issues, though, to keep all
143Perl module issues in the same place.
144
145## License
146
147The PGP::Sign package as a whole is covered by the following copyright
148statement and license:
149
150> Copyright 1997-2000, 2002, 2004, 2018, 2020
151> Russ Allbery <rra@cpan.org>
152>
153> This program is free software; you may redistribute it and/or modify it
154> under the same terms as Perl itself. This means that you may choose
155> between the two licenses that Perl is released under: the GNU GPL and the
156> Artistic License. Please see your Perl distribution for the details and
157> copies of the licenses.
158
159Some files in this distribution are individually released under different
160licenses, all of which are compatible with the above general package
161license but which may require preservation of additional notices. All
162required notices, and detailed information about the licensing of each
163file, are recorded in the LICENSE file.
164
165Files covered by a license with an assigned SPDX License Identifier
166include SPDX-License-Identifier tags to enable automated processing of
167license information. See https://spdx.org/licenses/ for more information.
168
169For any copyright range specified by files in this package as YYYY-ZZZZ,
170the range specifies every single year in that closed interval.
171
){kind=link}