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

VARIABLES

53       No package variables are exported by default.
54
55       $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
61       $SIGNATURE
62           The filename for a distribution's signature file.  Defaults to
63           "SIGNATURE".
64
65       $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
71       $KeyServerPort
72           The OpenPGP key server port, defaults to 11371.
73
74       $Timeout
75           Maximum time to wait to try to establish a link to the key server.
76           Defaults to 3.
77
78       $AutoKeyRetrieve
79           Whether to automatically fetch unknown keys from the key server.
80           Defaults to 1.
81
82       $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
88           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
94       $Preamble
95           The explanatory text written to newly generated SIGNATURE files
96           before the actual entries.
97

ENVIRONMENT

99       Module::Signature honors these environment variables:
100
101       MODULE_SIGNATURE_CIPHER
102           Works like $Cipher.
103
104       MODULE_SIGNATURE_VERBOSE
105           Works like $Verbose.
106
107       MODULE_SIGNATURE_KEYSERVER
108           Works like $KeyServer.
109
110       MODULE_SIGNATURE_KEYSERVERPORT
111           Works like $KeyServerPort.
112
113       MODULE_SIGNATURE_TIMEOUT
114           Works like $Timeout.
115

CONSTANTS

117       These constants are not exported by default.
118
119       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
124       SIGNATURE_OK (0)
125           Signature successfully verified.
126
127       SIGNATURE_MISSING ("-1")
128           The SIGNATURE file does not exist.
129
130       SIGNATURE_MALFORMED ("-2")
131           The signature file does not contains a valid OpenPGP message.
132
133       SIGNATURE_BAD ("-3")
134           Invalid signature detected -- it might have been tampered with.
135
136       SIGNATURE_MISMATCH ("-4")
137           The signature is valid, but files in the distribution have changed
138           since its creation.
139
140       MANIFEST_MISMATCH ("-5")
141           There are extra files in the current directory not specified by the
142           MANIFEST file.
143
144       CIPHER_UNKNOWN ("-6")
145           The cipher used by the signature file is not recognized by the
146           "Digest" and "Digest::*" modules.
147

NOTES

149   Signing your module as part of "make dist"
150       The easiest way is to use Module::Install:
151
152           sign;       # put this before "WriteAll"
153           WriteAll;
154
155       For ExtUtils::MakeMaker (version 6.18 or above), you may do this:
156
157           WriteMakefile(
158               (MM->can('signature_target') ? (SIGN => 1) : ()),
159               # ... original arguments ...
160           );
161
162       Users of Module::Build may do this:
163
164           Module::Build->new(
165               (sign => 1),
166               # ... original arguments ...
167           )->create_build_script;
168
169   MANIFEST.SKIP Considerations
170       (The following section is lifted from Iain Truskett's Test::Signature
171       module, under the Perl license.  Thanks, Iain!)
172
173       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
179       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
183       If you're using "ExtUtils::MakeMaker", you should have, at least:
184
185           #defaults
186           ^Makefile$
187           ^blib/
188           ^pm_to_blib
189           ^blibdirs
190
191       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
195       If you are using "Module::Build", you should have two extra entries:
196
197           ^Build$
198           ^_build/
199
200       If you don't have the correct entries, "Module::Signature" will
201       complain that you have:
202
203           ==> MISMATCHED content between MANIFEST and distribution files! <==
204
205       You should note this during normal development testing anyway.
206
207   Testing signatures
208       You may add this code as t/0-signature.t in your distribution tree:
209
210           #!/usr/bin/perl
211
212           use strict;
213           print "1..1\n";
214
215           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
237           __END__
238
239       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
243       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

SEE ALSO

248       Digest, Digest::SHA, Digest::SHA1, Digest::SHA::PurePerl
249
250       ExtUtils::Manifest, Crypt::OpenPGP, Test::Signature
251
252       Module::Install, ExtUtils::MakeMaker, Module::Build
253
254       Dist::Zilla::Plugin::Signature
255

AUTHORS

257       XX <cpan@audreyt.org>
258

CC0 1.0 Universal

260       To the extent possible under law, XX has waived all copyright and
261       related or neighboring rights to Module-Signature.
262
263       This work is published from Taiwan.
264
265       <http://creativecommons.org/publicdomain/zero/1.0>
266
267
268
269perl v5.16.3                      2013-06-05              Module::Signature(3)
Impressum