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 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
58 No package variables are exported by default.
59 $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 $SIGNATURE
67 The filename for a distribution's signature file. Defaults to
68 "SIGNATURE".
69 $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 $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 $KeyServerPort
82 The OpenPGP key server port, defaults to 11371.
83 $Timeout
85 Maximum time to wait to try to establish a link to the key server.
86 Defaults to 3.
87 $AutoKeyRetrieve
89 Whether to automatically fetch unknown keys from the key server.
90 Defaults to 1.
91 $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 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 $Preamble
104 The explanatory text written to newly generated SIGNATURE files
105 before the actual entries.
106
108 Module::Signature honors these environment variables:
109 MODULE_SIGNATURE_AUTHOR
111 Works like $AUTHOR.
112 MODULE_SIGNATURE_CIPHER
114 Works like $Cipher.
115 MODULE_SIGNATURE_VERBOSE
117 Works like $Verbose.
118 MODULE_SIGNATURE_KEYSERVER
120 Works like $KeyServer.
121 MODULE_SIGNATURE_KEYSERVERPORT
123 Works like $KeyServerPort.
124 MODULE_SIGNATURE_TIMEOUT
126 Works like $Timeout.
127
129 These constants are not exported by default.
130 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 SIGNATURE_OK (0)
137 Signature successfully verified.
138 SIGNATURE_MISSING (-1)
140 The SIGNATURE file does not exist.
141 SIGNATURE_MALFORMED (-2)
143 The signature file does not contains a valid OpenPGP message.
144 SIGNATURE_BAD (-3)
146 Invalid signature detected -- it might have been tampered with.
147 SIGNATURE_MISMATCH (-4)
149 The signature is valid, but files in the distribution have changed
150 since its creation.
151 MANIFEST_MISMATCH (-5)
153 There are extra files in the current directory not specified by the
154 MANIFEST file.
155 CIPHER_UNKNOWN (-6)
157 The cipher used by the signature file is not recognized by the
158 "Digest" and "Digest::*" modules.
159
161 Signing your module as part of "make dist"
162 The easiest way is to use Module::Install:
163 sign; # put this before "WriteAll"
165 WriteAll;
166 For ExtUtils::MakeMaker (version 6.18 or above), you may do this:
168 WriteMakefile(
170 (MM->can('signature_target') ? (SIGN => 1) : ()),
171 # ... original arguments ...
172 );
173 Users of Module::Build may do this:
175 Module::Build->new(
177 (sign => 1),
178 # ... original arguments ...
179 )->create_build_script;
180 MANIFEST.SKIP Considerations
182 (The following section is lifted from Iain Truskett's Test::Signature
183 module, under the Perl license. Thanks, Iain!)
184 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 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 If you're using "ExtUtils::MakeMaker", you should have, at least:
196 #defaults
198 ^Makefile$
199 ^blib/
200 ^pm_to_blib
201 ^blibdirs
202 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 If you are using "Module::Build", you should have two extra entries:
208 ^Build$
210 ^_build/
211 If you don't have the correct entries, "Module::Signature" will
213 complain that you have:
214 ==> MISMATCHED content between MANIFEST and distribution files! <==
216 You should note this during normal development testing anyway.
218 Testing signatures
220 You may add this code as t/0-signature.t in your distribution tree:
221 #!/usr/bin/perl
223 use strict;
225 print "1..1\n";
226 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 __END__
250 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 Note that "MANIFEST.SKIP" is considered by default only when
256 $ENV{TEST_SIGNATURE} is set to a true value.
257 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
263 Digest, Digest::SHA, Digest::SHA::PurePerl
264 ExtUtils::Manifest, Crypt::OpenPGP, Test::Signature
266 Module::Install, ExtUtils::MakeMaker, Module::Build
268 Dist::Zilla::Plugin::Signature
270
272 Audrey Tang <cpan@audreyt.org>
273
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 To the extent possible under law, 唐鳳 has waived all copyright and
279 related or neighboring rights to Module-Signature.
280 This work is published from Taiwan.
282 <http://creativecommons.org/publicdomain/zero/1.0>
284perl v5.36.0 2023-01-20 Module::Signature(3)