1# PGP::Sign 1.03 2 3[![Build 4status](https://github.com/rra/pgp-sign/workflows/build/badge.svg)](https://github.com/rra/pgp-sign/actions) 5[![CPAN 6version](https://img.shields.io/cpan/v/PGP-Sign)](https://metacpan.org/release/PGP-Sign) 7[![License](https://img.shields.io/cpan/l/PGP-Sign)](https://github.com/rra/pgp-sign/blob/master/LICENSE) 8[![Debian 9package](https://img.shields.io/debian/v/libpgp-sign-perl/unstable)](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