Cryptographically signing a distribution is more of an integrity check than a security measure. As the documentation for Test::Signature explains, by the time the make test portion of the installation checks the signature of a module, you've already executed a Makefile.PL or Build.PL , giving potentially malicious code the chance to run. Still, a signed distribution assures you that every file in the distribution is exactly what the author originally uploaded. Signing a module distribution creates a file called SIGNATURE in the top-level directory that contains checksums for every file in the distribution. The author then signs the SIGNATURE file with a PGP or equivalent key. If you sign your distribution, you should include a signature validity check as part of the test suite. How do I do that? To sign a module, first install GnuPG and set up a private key that you'll use to do the signing with. For more information on how to use GnuPG, see the Documentation section on the GnuPG web site at http://www.gnupg.org/. Next, install Module::Signature . Module::Signature provides the cpansign utility to create and verify SIGNATURE files. Describing module signatures, how to use cpansign , and considerations when bundling up modules is a bigger topic than this lab allows, so please see the Module::Signature documentation for information on how to sign your modules. Once you've signed your distribution, you should see a SIGNATURE file in the distribution's directory containing something like: This file contains message digests of all files listed in MANIFEST, signed via the Module::Signature module, version 0.44. ... -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 SHA1 e72320c0cd1a851238273f7d1jd7d46t395mrjbs Changes SHA1 fm8b86bb3d93345751371f67chd01efe8tdua9f3 MANIFEST SHA1 67i17fa0ff0ea897b0a2e43ddac01m6e5r8n132s META.yml SHA1 cc0l0c8abd8a9941b1y0ad61fr808i7hfbcc32al Makefile.PL SHA1 1fa0y76d5dac6c64d15lb17f0td22l1sfmau2cci README SHA1 fd94a423d3e42462fec2if7997a19y8b6abs3f7m lib/FAQ/Sciuridae.pm SHA1 b7504edf3808b62742e3bm00dc464d3i9lf2b39m lib/FAQ/Sciuridae/Chipmunk.pm SHA1 edde6f2c4608bfeee6acf9effff9644jbc815d6e lib/FAQ/Sciuridae/Marmot.pm ... To verify the contents of SIGNATURE when the test suite is run, create a test file 00-signature.t : Note: Because a broken signature is a showstopper when installing modules, it is common practice to prefix the file name with zeroes so that it runs early in the test suite . use Test::More; eval 'use Test::Signature'; plan( skip_all => 'Test::Signature required for signature verification' ) if $@; plan( tests => 1 ); signature_ok( ); Run the test file with prove : $ prove -v t/00-signature.t t/00-signature....1..1 ok 1 - Valid signature ok All tests successful. Files=1, Tests=1, 1 wallclock secs ( 0.57 cusr + 0.05 csys = 0.62 CPU) What just happened ? Validating signatures is only a suggested step in installing modules, not a required one. Thus, 00-signature.t checks to see whether the user has Module::Signature installed. It skips signature verification if not. By default, Test::Signature exports a single function, signature_ok( ) , which reports a single test that indicates the validity of the SIGNATURE file. To verify a SIGNATURE file, the test first checks the integrity of the PGP signature contained within. Next, it creates a list of checksums for the files listed in MANIFEST , comparing that list to the checksums supplied in SIGNATURE . If all of these steps succeed, the test produced by signature_ok( ) succeeds. Internally, Test::Signature 's signature_ok( ) function and running cpansign -v use the same verify( ) function found in Module::Signature . If one of the steps to test the integrity of SIGNATURE fails, signature_ok( ) will produce the same or similar output to that of cpansign -v . For example, if one or more of the checksums is incorrect, the output will display a comparison of the list of checksums in the style of the diff utility. |