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 $KeyServer
66 The OpenPGP key server for fetching the author's public key
67 (currently only implemented on "gpg", not "Crypt::OpenPGP"). May
68 be set to a false value to prevent this module from fetching public
69 keys.
70 $KeyServerPort
72 The OpenPGP key server port, defaults to 11371.
73 $Timeout
75 Maximum time to wait to try to establish a link to the key server.
76 Defaults to 3.
77 $AutoKeyRetrieve
79 Whether to automatically fetch unknown keys from the key server.
80 Defaults to 1.
81 $Cipher
83 The default cipher used by the "Digest" module to make signature
84 files. Defaults to "SHA1", but may be changed to other ciphers via
85 the "MODULE_SIGNATURE_CIPHER" environment variable if the SHA1
86 cipher is undesirable for the user.
87 The cipher specified in the SIGNATURE file's first entry will be
89 used to validate its integrity. For "SHA1", the user needs to have
90 any one of these four modules installed: Digest::SHA, Digest::SHA1,
91 Digest::SHA::PurePerl, or (currently nonexistent)
92 Digest::SHA1::PurePerl.
93 $Preamble
95 The explanatory text written to newly generated SIGNATURE files
96 before the actual entries.
97
99 Module::Signature honors these environment variables:
100 MODULE_SIGNATURE_CIPHER
102 Works like $Cipher.
103 MODULE_SIGNATURE_VERBOSE
105 Works like $Verbose.
106 MODULE_SIGNATURE_KEYSERVER
108 Works like $KeyServer.
109 MODULE_SIGNATURE_KEYSERVERPORT
111 Works like $KeyServerPort.
112 MODULE_SIGNATURE_TIMEOUT
114 Works like $Timeout.
115
117 These constants are not exported by default.
118 CANNOT_VERIFY (0E0)
120 Cannot verify the OpenPGP signature, maybe due to the lack of a
121 network connection to the key server, or if neither gnupg nor
122 Crypt::OpenPGP exists on the system.
123 SIGNATURE_OK (0)
125 Signature successfully verified.
126 SIGNATURE_MISSING ("-1")
128 The SIGNATURE file does not exist.
129 SIGNATURE_MALFORMED ("-2")
131 The signature file does not contains a valid OpenPGP message.
132 SIGNATURE_BAD ("-3")
134 Invalid signature detected -- it might have been tampered with.
135 SIGNATURE_MISMATCH ("-4")
137 The signature is valid, but files in the distribution have changed
138 since its creation.
139 MANIFEST_MISMATCH ("-5")
141 There are extra files in the current directory not specified by the
142 MANIFEST file.
143 CIPHER_UNKNOWN ("-6")
145 The cipher used by the signature file is not recognized by the
146 "Digest" and "Digest::*" modules.
147
149 Signing your module as part of "make dist"
150 The easiest way is to use Module::Install:
151 sign; # put this before "WriteAll"
153 WriteAll;
154 For ExtUtils::MakeMaker (version 6.18 or above), you may do this:
156 WriteMakefile(
158 (MM->can('signature_target') ? (SIGN => 1) : ()),
159 # ... original arguments ...
160 );
161 Users of Module::Build may do this:
163 Module::Build->new(
165 (sign => 1),
166 # ... original arguments ...
167 )->create_build_script;
168 MANIFEST.SKIP Considerations
170 (The following section is lifted from Iain Truskett's Test::Signature
171 module, under the Perl license. Thanks, Iain!)
172 It is imperative that your MANIFEST and MANIFEST.SKIP files be accurate
174 and complete. If you are using "ExtUtils::MakeMaker" and you do not
175 have a MANIFEST.SKIP file, then don't worry about the rest of this. If
176 you do have a MANIFEST.SKIP file, or you use "Module::Build", you must
177 read this.
178 Since the test is run at "make test" time, the distribution has been
180 made. Thus your MANIFEST.SKIP file should have the entries listed
181 below.
182 If you're using "ExtUtils::MakeMaker", you should have, at least:
184 #defaults
186 ^Makefile$
187 ^blib/
188 ^pm_to_blib
189 ^blibdirs
190 These entries are part of the default set provided by
192 "ExtUtils::Manifest", which is ignored if you provide your own
193 MANIFEST.SKIP file.
194 If you are using "Module::Build", you should have two extra entries:
196 ^Build$
198 ^_build/
199 If you don't have the correct entries, "Module::Signature" will
201 complain that you have:
202 ==> MISMATCHED content between MANIFEST and distribution files! <==
204 You should note this during normal development testing anyway.
206 Testing signatures
208 You may add this code as t/0-signature.t in your distribution tree:
209 #!/usr/bin/perl
211 use strict;
213 print "1..1\n";
214 if (!$ENV{TEST_SIGNATURE}) {
216 print "ok 1 # skip Set the environment variable",
217 " TEST_SIGNATURE to enable this test\n";
218 }
219 elsif (!-s 'SIGNATURE') {
220 print "ok 1 # skip No signature file found\n";
221 }
222 elsif (!eval { require Module::Signature; 1 }) {
223 print "ok 1 # skip ",
224 "Next time around, consider install Module::Signature, ",
225 "so you can verify the integrity of this distribution.\n";
226 }
227 elsif (!eval { require Socket; Socket::inet_aton('pool.sks-keyservers.net') }) {
228 print "ok 1 # skip ",
229 "Cannot connect to the keyserver\n";
230 }
231 else {
232 (Module::Signature::verify() == Module::Signature::SIGNATURE_OK())
233 or print "not ";
234 print "ok 1 # Valid signature\n";
235 }
236 __END__
238 If you are already using Test::More for testing, a more straightforward
240 version of t/0-signature.t can be found in the Module::Signature
241 distribution.
242 Also, if you prefer a more full-fledged testing package, and are
244 willing to inflict the dependency of Module::Build on your users, Iain
245 Truskett's Test::Signature might be a better choice.
246
248 Digest, Digest::SHA, Digest::SHA1, Digest::SHA::PurePerl
249 ExtUtils::Manifest, Crypt::OpenPGP, Test::Signature
251 Module::Install, ExtUtils::MakeMaker, Module::Build
253 Dist::Zilla::Plugin::Signature
255
257 XX <cpan@audreyt.org>
258
260 To the extent possible under law, XX has waived all copyright and
261 related or neighboring rights to Module-Signature.
262 This work is published from Taiwan.
264 <http://creativecommons.org/publicdomain/zero/1.0>
266perl v5.16.3 2013-06-05 Module::Signature(3)