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
52       Signatures made with Module::Signature prior to version 0.82 used the
53       SHA1 algorithm by default. SHA1 is now considered broken, and therefore
54       module authors are strongly encouraged to regenerate their SIGNATURE
55       files. Users verifying old SHA1 signature files will receive a warning.
56

VARIABLES

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

ENVIRONMENT

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

CONSTANTS

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

NOTES

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

SEE ALSO

263       Digest, Digest::SHA, Digest::SHA::PurePerl
264
265       ExtUtils::Manifest, Crypt::OpenPGP, Test::Signature
266
267       Module::Install, ExtUtils::MakeMaker, Module::Build
268
269       Dist::Zilla::Plugin::Signature
270

AUTHORS

272       Audrey Tang <cpan@audreyt.org>
273

LICENSE

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