1Module::Signature(3)  User Contributed Perl Documentation Module::Signature(3)
2
3
4

NAME

6       Module::Signature - Module signature file manipulation
7

SYNOPSIS

9       As a shell command:
10
11           % cpansign              # verify an existing SIGNATURE, or
12                                   # make a new one if none exists
13
14           % cpansign sign         # make signature; overwrites existing one
15           % cpansign -s           # same thing
16
17           % cpansign verify       # verify a signature
18           % cpansign -v           # same thing
19           % cpansign -v --skip    # ignore files in MANIFEST.SKIP
20
21           % cpansign help         # display this documentation
22           % cpansign -h           # same thing
23
24       In programs:
25
26           use Module::Signature qw(sign verify SIGNATURE_OK);
27           sign();
28           sign(overwrite => 1);       # overwrites without asking
29
30           # see the CONSTANTS section below
31           (verify() == SIGNATURE_OK) or die "failed!";
32

DESCRIPTION

34       Module::Signature adds cryptographic authentications to CPAN
35       distributions, via the special SIGNATURE file.
36
37       If you are a module user, all you have to do is to remember to run
38       "cpansign -v" (or just "cpansign") before issuing "perl Makefile.PL" or
39       "perl Build.PL"; that will ensure the distribution has not been
40       tampered with.
41
42       Module authors can easily add the SIGNATURE file to the distribution
43       tarball; see "NOTES" below for how to do it as part of "make dist".
44
45       If you really want to sign a distribution manually, simply add
46       "SIGNATURE" to MANIFEST, then type "cpansign -s" immediately before
47       "make dist".  Be sure to delete the SIGNATURE file afterwards.
48
49       Please also see "NOTES" about MANIFEST.SKIP issues, especially if you
50       are using Module::Build or writing your own MANIFEST.SKIP.
51

VARIABLES

53       No package variables are exported by default.
54
55       $Verbose
56           If true, Module::Signature will give information during processing
57           including gpg output.  If false, Module::Signature will be as quiet
58           as possible as long as everything is working ok.  Defaults to
59           false.
60
61       $SIGNATURE
62           The filename for a distribution's signature file.  Defaults to
63           "SIGNATURE".
64
65       $AUTHOR
66           The key ID used for signature. If empty/null/0, "gpg"'s configured
67           default ID, or the most recently added key within the secret
68           keyring for "Crypt::OpenPGP", will be used for the signature.
69
70       $KeyServer
71           The OpenPGP key server for fetching the author's public key
72           (currently only implemented on "gpg", not "Crypt::OpenPGP").  May
73           be set to a false value to prevent this module from fetching public
74           keys.
75
76       $KeyServerPort
77           The OpenPGP key server port, defaults to 11371.
78
79       $Timeout
80           Maximum time to wait to try to establish a link to the key server.
81           Defaults to 3.
82
83       $AutoKeyRetrieve
84           Whether to automatically fetch unknown keys from the key server.
85           Defaults to 1.
86
87       $Cipher
88           The default cipher used by the "Digest" module to make signature
89           files.  Defaults to "SHA1", but may be changed to other ciphers via
90           the "MODULE_SIGNATURE_CIPHER" environment variable if the SHA1
91           cipher is undesirable for the user.
92
93           The cipher specified in the SIGNATURE file's first entry will be
94           used to validate its integrity.  For "SHA1", the user needs to have
95           any one of these four modules installed: Digest::SHA, Digest::SHA1,
96           Digest::SHA::PurePerl, or (currently nonexistent)
97           Digest::SHA1::PurePerl.
98
99       $Preamble
100           The explanatory text written to newly generated SIGNATURE files
101           before the actual entries.
102

ENVIRONMENT

104       Module::Signature honors these environment variables:
105
106       MODULE_SIGNATURE_AUTHOR
107           Works like $AUTHOR.
108
109       MODULE_SIGNATURE_CIPHER
110           Works like $Cipher.
111
112       MODULE_SIGNATURE_VERBOSE
113           Works like $Verbose.
114
115       MODULE_SIGNATURE_KEYSERVER
116           Works like $KeyServer.
117
118       MODULE_SIGNATURE_KEYSERVERPORT
119           Works like $KeyServerPort.
120
121       MODULE_SIGNATURE_TIMEOUT
122           Works like $Timeout.
123

CONSTANTS

125       These constants are not exported by default.
126
127       CANNOT_VERIFY (0E0)
128           Cannot verify the OpenPGP signature, maybe due to the lack of a
129           network connection to the key server, or if neither gnupg nor
130           Crypt::OpenPGP exists on the system.
131
132       SIGNATURE_OK (0)
133           Signature successfully verified.
134
135       SIGNATURE_MISSING ("-1")
136           The SIGNATURE file does not exist.
137
138       SIGNATURE_MALFORMED ("-2")
139           The signature file does not contains a valid OpenPGP message.
140
141       SIGNATURE_BAD ("-3")
142           Invalid signature detected -- it might have been tampered with.
143
144       SIGNATURE_MISMATCH ("-4")
145           The signature is valid, but files in the distribution have changed
146           since its creation.
147
148       MANIFEST_MISMATCH ("-5")
149           There are extra files in the current directory not specified by the
150           MANIFEST file.
151
152       CIPHER_UNKNOWN ("-6")
153           The cipher used by the signature file is not recognized by the
154           "Digest" and "Digest::*" modules.
155

NOTES

157   Signing your module as part of "make dist"
158       The easiest way is to use Module::Install:
159
160           sign;       # put this before "WriteAll"
161           WriteAll;
162
163       For ExtUtils::MakeMaker (version 6.18 or above), you may do this:
164
165           WriteMakefile(
166               (MM->can('signature_target') ? (SIGN => 1) : ()),
167               # ... original arguments ...
168           );
169
170       Users of Module::Build may do this:
171
172           Module::Build->new(
173               (sign => 1),
174               # ... original arguments ...
175           )->create_build_script;
176
177   MANIFEST.SKIP Considerations
178       (The following section is lifted from Iain Truskett's Test::Signature
179       module, under the Perl license.  Thanks, Iain!)
180
181       It is imperative that your MANIFEST and MANIFEST.SKIP files be accurate
182       and complete. If you are using "ExtUtils::MakeMaker" and you do not
183       have a MANIFEST.SKIP file, then don't worry about the rest of this. If
184       you do have a MANIFEST.SKIP file, or you use "Module::Build", you must
185       read this.
186
187       Since the test is run at "make test" time, the distribution has been
188       made. Thus your MANIFEST.SKIP file should have the entries listed
189       below.
190
191       If you're using "ExtUtils::MakeMaker", you should have, at least:
192
193           #defaults
194           ^Makefile$
195           ^blib/
196           ^pm_to_blib
197           ^blibdirs
198
199       These entries are part of the default set provided by
200       "ExtUtils::Manifest", which is ignored if you provide your own
201       MANIFEST.SKIP file.
202
203       If you are using "Module::Build", you should have two extra entries:
204
205           ^Build$
206           ^_build/
207
208       If you don't have the correct entries, "Module::Signature" will
209       complain that you have:
210
211           ==> MISMATCHED content between MANIFEST and distribution files! <==
212
213       You should note this during normal development testing anyway.
214
215   Testing signatures
216       You may add this code as t/0-signature.t in your distribution tree:
217
218           #!/usr/bin/perl
219
220           use strict;
221           print "1..1\n";
222
223           if (!$ENV{TEST_SIGNATURE}) {
224               print "ok 1 # skip Set the environment variable",
225                           " TEST_SIGNATURE to enable this test\n";
226           }
227           elsif (!-s 'SIGNATURE') {
228               print "ok 1 # skip No signature file found\n";
229           }
230           elsif (!eval { require Module::Signature; 1 }) {
231               print "ok 1 # skip ",
232                       "Next time around, consider install Module::Signature, ",
233                       "so you can verify the integrity of this distribution.\n";
234           }
235           elsif (!eval { require Socket; Socket::inet_aton('pool.sks-keyservers.net') }) {
236               print "ok 1 # skip ",
237                       "Cannot connect to the keyserver\n";
238           }
239           else {
240               (Module::Signature::verify() == Module::Signature::SIGNATURE_OK())
241                   or print "not ";
242               print "ok 1 # Valid signature\n";
243           }
244
245           __END__
246
247       If you are already using Test::More for testing, a more straightforward
248       version of t/0-signature.t can be found in the Module::Signature
249       distribution.
250
251       Note that "MANIFEST.SKIP" is considered by default only when
252       $ENV{TEST_SIGNATURE} is set to a true value.
253
254       Also, if you prefer a more full-fledged testing package, and are
255       willing to inflict the dependency of Module::Build on your users, Iain
256       Truskett's Test::Signature might be a better choice.
257

SEE ALSO

259       Digest, Digest::SHA, Digest::SHA1, Digest::SHA::PurePerl
260
261       ExtUtils::Manifest, Crypt::OpenPGP, Test::Signature
262
263       Module::Install, ExtUtils::MakeMaker, Module::Build
264
265       Dist::Zilla::Plugin::Signature
266

AUTHORS

268       Audrey Tang <cpan@audreyt.org>
269

LICENSE

271       This work is under a CC0 1.0 Universal License, although a portion of
272       the documentation (as detailed above) is under the Perl license.
273
274       To the extent possible under law, 唐鳳 has waived all copyright and
275       related or neighboring rights to Module-Signature.
276
277       This work is published from Taiwan.
278
279       <http://creativecommons.org/publicdomain/zero/1.0>
280
281
282
283perl v5.28.0                      2018-08-29              Module::Signature(3)
Impressum