1Module::Signature(3) User Contributed Perl Documentation Module::Signature(3)
2
6 Module::Signature - Module signature file manipulation
7
9 This document describes version 0.54 of Module::Signature, released May
10 12, 2006.
11
13 As a shell command:
14 % cpansign # verify an existing SIGNATURE, or
16 # make a new one if none exists
17 % cpansign sign # make signature; overwrites existing one
19 % cpansign -s # same thing
20 % cpansign verify # verify a signature
22 % cpansign -v # same thing
23 % cpansign -v --skip # ignore files in MANIFEST.SKIP
24 % cpansign help # display this documentation
26 % cpansign -h # same thing
27 In programs:
29 use Module::Signature qw(sign verify SIGNATURE_OK);
31 sign();
32 sign(overwrite => 1); # overwrites without asking
33 # see the CONSTANTS section below
35 (verify() == SIGNATURE_OK) or die "failed!";
36
38 Module::Signature adds cryptographic authentications to CPAN distribu‐
39 tions, via the special SIGNATURE file.
40 If you are a module user, all you have to do is to remember to run
42 "cpansign -v" (or just "cpansign") before issuing "perl Makefile.PL" or
43 "perl Build.PL"; that will ensure the distribution has not been tam‐
44 pered with.
45 Module authors can easily add the SIGNATURE file to the distribution
47 tarball; see "NOTES" below for how to do it as part of "make dist".
48 If you really want to sign a distribution manually, simply add "SIGNA‐
50 TURE" to MANIFEST, then type "cpansign -s" immediately before "make
51 dist". Be sure to delete the SIGNATURE file afterwards.
52 Please also see "NOTES" about MANIFEST.SKIP issues, especially if you
54 are using Module::Build or writing your own MANIFEST.SKIP.
55
57 No package variables are exported by default.
58 $Verbose
60 If true, Module::Signature will give information during processing
61 including gpg output. If false, Module::Signature will be as quiet
62 as possible as long as everything is working ok. Defaults to
63 false.
64 $SIGNATURE
66 The filename for a distribution's signature file. Defaults to
67 "SIGNATURE".
68 $KeyServer
70 The OpenPGP key server for fetching the author's public key (cur‐
71 rently only implemented on "gpg", not "Crypt::OpenPGP"). May be
72 set to a false value to prevent this module from fetching public
73 keys.
74 $KeyServerPort
76 The OpenPGP key server port, defaults to 11371.
77 $Timeout
79 Maximum time to wait to try to establish a link to the key server.
80 Defaults to 3.
81 $AutoKeyRetrieve
83 Whether to automatically fetch unknown keys from the key server.
84 Defaults to 1.
85 $Cipher
87 The default cipher used by the "Digest" module to make signature
88 files. Defaults to "SHA1", but may be changed to other ciphers via
89 the "MODULE_SIGNATURE_CIPHER" environment variable if the SHA1
90 cipher is undesirable for the user.
91 The cipher specified in the SIGNATURE file's first entry will be
93 used to validate its integrity. For "SHA1", the user needs to have
94 any one of these four modules installed: Digest::SHA, Digest::SHA1,
95 Digest::SHA::PurePerl, or (currently nonexistent)
96 Digest::SHA1::PurePerl.
97 $Preamble
99 The explanatory text written to newly generated SIGNATURE files
100 before the actual entries.
101
103 Module::Signature honors these environment variables:
104 MODULE_SIGNATURE_CIPHER
106 Works like $Cipher.
107 MODULE_SIGNATURE_VERBOSE
109 Works like $Verbose.
110 MODULE_SIGNATURE_KEYSERVER
112 Works like $KeyServer.
113 MODULE_SIGNATURE_KEYSERVERPORT
115 Works like $KeyServerPort.
116 MODULE_SIGNATURE_TIMEOUT
118 Works like $Timeout.
119
121 These constants are not exported by default.
122 CANNOT_VERIFY (0E0)
124 Cannot verify the OpenPGP signature, maybe due to the lack of a
125 network connection to the key server, or if neither gnupg nor
126 Crypt::OpenPGP exists on the system.
127 SIGNATURE_OK (0)
129 Signature successfully verified.
130 SIGNATURE_MISSING ("-1")
132 The SIGNATURE file does not exist.
133 SIGNATURE_MALFORMED ("-2")
135 The signature file does not contains a valid OpenPGP message.
136 SIGNATURE_BAD ("-3")
138 Invalid signature detected -- it might have been tampered with.
139 SIGNATURE_MISMATCH ("-4")
141 The signature is valid, but files in the distribution have changed
142 since its creation.
143 MANIFEST_MISMATCH ("-5")
145 There are extra files in the current directory not specified by the
146 MANIFEST file.
147 CIPHER_UNKNOWN ("-6")
149 The cipher used by the signature file is not recognized by the
150 "Digest" and "Digest::*" modules.
151
153 Signing your module as part of "make dist"
154 The easiest way is to use Module::Install:
156 sign; # put this before "WriteAll"
158 WriteAll;
159 For ExtUtils::MakeMaker (version 6.18 or above), you may do this:
161 WriteMakefile(
163 (MM->can('signature_target') ? (SIGN => 1) : ()),
164 # ... original arguments ...
165 );
166 Users of Module::Build may do this:
168 Module::Build->new(
170 (sign => 1),
171 # ... original arguments ...
172 )->create_build_script;
173 MANIFEST.SKIP Considerations
175 (The following section is lifted from Iain Truskett's Test::Signature
177 module, under the Perl license. Thanks, Iain!)
178 It is imperative that your MANIFEST and MANIFEST.SKIP files be accurate
180 and complete. If you are using "ExtUtils::MakeMaker" and you do not
181 have a MANIFEST.SKIP file, then don't worry about the rest of this. If
182 you do have a MANIFEST.SKIP file, or you use "Module::Build", you must
183 read this.
184 Since the test is run at "make test" time, the distribution has been
186 made. Thus your MANIFEST.SKIP file should have the entries listed
187 below.
188 If you're using "ExtUtils::MakeMaker", you should have, at least:
190 #defaults
192 ^Makefile$
193 ^blib/
194 ^pm_to_blib
195 ^blibdirs
196 These entries are part of the default set provided by "ExtUtils::Mani‐
198 fest", which is ignored if you provide your own MANIFEST.SKIP file.
199 If you are using "Module::Build", you should have two extra entries:
201 ^Build$
203 ^_build/
204 If you don't have the correct entries, "Module::Signature" will com‐
206 plain that you have:
207 ==> MISMATCHED content between MANIFEST and distribution files! <==
209 You should note this during normal development testing anyway.
211 Testing signatures
213 You may add this code as t/0-signature.t in your distribution tree:
215 #!/usr/bin/perl
217 use strict;
219 print "1..1\n";
220 if (!$ENV{TEST_SIGNATURE}) {
222 print "ok 1 # skip Set the environment variable",
223 " TEST_SIGNATURE to enable this test\n";
224 }
225 elsif (!-s 'SIGNATURE') {
226 print "ok 1 # skip No signature file found\n";
227 }
228 elsif (!eval { require Module::Signature; 1 }) {
229 print "ok 1 # skip ",
230 "Next time around, consider install Module::Signature, ",
231 "so you can verify the integrity of this distribution.\n";
232 }
233 elsif (!eval { require Socket; Socket::inet_aton('pgp.mit.edu') }) {
234 print "ok 1 # skip ",
235 "Cannot connect to the keyserver\n";
236 }
237 else {
238 (Module::Signature::verify() == Module::Signature::SIGNATURE_OK())
239 or print "not ";
240 print "ok 1 # Valid signature\n";
241 }
242 __END__
244 If you are already using Test::More for testing, a more straightforward
246 version of t/0-signature.t can be found in the Module::Signature dis‐
247 tribution.
248 Also, if you prefer a more full-fledged testing package, and are will‐
250 ing to inflict the dependency of Module::Build on your users, Iain
251 Truskett's Test::Signature might be a better choice.
252
254 Digest, Digest::SHA, Digest::SHA1, Digest::SHA::PurePerl
255 ExtUtils::Manifest, Crypt::OpenPGP, Test::Signature
257 Module::Install, ExtUtils::MakeMaker, Module::Build
259
261 Audrey Tang <cpan@audreyt.org>
262
264 Copyright 2002-2006 by Audrey Tang <cpan@audreyt.org>.
265 Permission is hereby granted, free of charge, to any person obtaining a
267 copy of this software and associated documentation files (the "Soft‐
268 ware"), to deal in the Software without restriction, including without
269 limitation the rights to use, copy, modify, merge, publish, distribute,
270 sublicense, and/or sell copies of the Software, and to permit persons
271 to whom the Software is fur- nished to do so, subject to the following
272 conditions:
273 The above copyright notice and this permission notice shall be included
275 in all copies or substantial portions of the Software.
276 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
278 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MER‐
279 CHANTABILITY, FIT- NESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
280 IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
281 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
282 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
283 OTHER DEALINGS IN THE SOFTWARE.
284perl v5.8.8 2006-07-12 Module::Signature(3)