1Module::Signature(3) User Contributed Perl Documentation Module::Signature(3)
2
6 Module::Signature - Module signature file manipulation
7
9 As a shell command:
10 % cpansign # verify an existing SIGNATURE, or
12 # make a new one if none exists
13 % cpansign sign # make signature; overwrites existing one
15 % cpansign -s # same thing
16 % cpansign verify # verify a signature
18 % cpansign -v # same thing
19 % cpansign -v --skip # ignore files in MANIFEST.SKIP
20 % cpansign help # display this documentation
22 % cpansign -h # same thing
23 In programs:
25 use Module::Signature qw(sign verify SIGNATURE_OK);
27 sign();
28 sign(overwrite => 1); # overwrites without asking
29 # see the CONSTANTS section below
31 (verify() == SIGNATURE_OK) or die "failed!";
32
34 Module::Signature adds cryptographic authentications to CPAN
35 distributions, via the special SIGNATURE file.
36 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 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 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 Please also see "NOTES" about MANIFEST.SKIP issues, especially if you
50 are using Module::Build or writing your own MANIFEST.SKIP.
51
53 No package variables are exported by default.
54 $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 $SIGNATURE
62 The filename for a distribution's signature file. Defaults to
63 "SIGNATURE".
64 $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 $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 $KeyServerPort
77 The OpenPGP key server port, defaults to 11371.
78 $Timeout
80 Maximum time to wait to try to establish a link to the key server.
81 Defaults to 3.
82 $AutoKeyRetrieve
84 Whether to automatically fetch unknown keys from the key server.
85 Defaults to 1.
86 $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 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 $Preamble
100 The explanatory text written to newly generated SIGNATURE files
101 before the actual entries.
102
104 Module::Signature honors these environment variables:
105 MODULE_SIGNATURE_AUTHOR
107 Works like $AUTHOR.
108 MODULE_SIGNATURE_CIPHER
110 Works like $Cipher.
111 MODULE_SIGNATURE_VERBOSE
113 Works like $Verbose.
114 MODULE_SIGNATURE_KEYSERVER
116 Works like $KeyServer.
117 MODULE_SIGNATURE_KEYSERVERPORT
119 Works like $KeyServerPort.
120 MODULE_SIGNATURE_TIMEOUT
122 Works like $Timeout.
123
125 These constants are not exported by default.
126 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 SIGNATURE_OK (0)
133 Signature successfully verified.
134 SIGNATURE_MISSING ("-1")
136 The SIGNATURE file does not exist.
137 SIGNATURE_MALFORMED ("-2")
139 The signature file does not contains a valid OpenPGP message.
140 SIGNATURE_BAD ("-3")
142 Invalid signature detected -- it might have been tampered with.
143 SIGNATURE_MISMATCH ("-4")
145 The signature is valid, but files in the distribution have changed
146 since its creation.
147 MANIFEST_MISMATCH ("-5")
149 There are extra files in the current directory not specified by the
150 MANIFEST file.
151 CIPHER_UNKNOWN ("-6")
153 The cipher used by the signature file is not recognized by the
154 "Digest" and "Digest::*" modules.
155
157 Signing your module as part of "make dist"
158 The easiest way is to use Module::Install:
159 sign; # put this before "WriteAll"
161 WriteAll;
162 For ExtUtils::MakeMaker (version 6.18 or above), you may do this:
164 WriteMakefile(
166 (MM->can('signature_target') ? (SIGN => 1) : ()),
167 # ... original arguments ...
168 );
169 Users of Module::Build may do this:
171 Module::Build->new(
173 (sign => 1),
174 # ... original arguments ...
175 )->create_build_script;
176 MANIFEST.SKIP Considerations
178 (The following section is lifted from Iain Truskett's Test::Signature
179 module, under the Perl license. Thanks, Iain!)
180 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 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 If you're using "ExtUtils::MakeMaker", you should have, at least:
192 #defaults
194 ^Makefile$
195 ^blib/
196 ^pm_to_blib
197 ^blibdirs
198 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 If you are using "Module::Build", you should have two extra entries:
204 ^Build$
206 ^_build/
207 If you don't have the correct entries, "Module::Signature" will
209 complain that you have:
210 ==> MISMATCHED content between MANIFEST and distribution files! <==
212 You should note this during normal development testing anyway.
214 Testing signatures
216 You may add this code as t/0-signature.t in your distribution tree:
217 #!/usr/bin/perl
219 use strict;
221 print "1..1\n";
222 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 __END__
246 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 Note that "MANIFEST.SKIP" is considered by default only when
252 $ENV{TEST_SIGNATURE} is set to a true value.
253 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
259 Digest, Digest::SHA, Digest::SHA1, Digest::SHA::PurePerl
260 ExtUtils::Manifest, Crypt::OpenPGP, Test::Signature
262 Module::Install, ExtUtils::MakeMaker, Module::Build
264 Dist::Zilla::Plugin::Signature
266
268 Audrey Tang <cpan@audreyt.org>
269
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 To the extent possible under law, 唐鳳 has waived all copyright and
275 related or neighboring rights to Module-Signature.
276 This work is published from Taiwan.
278 <http://creativecommons.org/publicdomain/zero/1.0>
280perl v5.30.0 2019-07-26 Module::Signature(3)