/ 
Filter-Crypto-1.24
River stage zero No dependents
/ PAR::Filter::Crypto

NAME

PAR::Filter::Crypto - Encrypt Perl files in PAR archives

SYNOPSIS

# Create a PAR archive containing an encrypted Perl script:
$ pp -f Crypto -M Filter::Crypto::Decrypt -o hello hello.pl

# The same, but with included modules encrypted as well:
$ pp -f Crypto -F Crypto -M Filter::Crypto::Decrypt -o hello hello.pl

# Encrypt Perl source code in $code:
use PAR::Filter::Crypto;
PAR::Filter::Crypto->apply(\$code);

DESCRIPTION

This module is a PAR::Filter sub-class for producing PAR archives containing encrypted Perl files. The PAR::Filter class itself is part of the PAR distribution, and is clearly a prerequisite for using this sub-class.

The usual means of producing a PAR archive is using the pp script, which also comes with the PAR distribution. That script's -f and -F command-line options can be used to specify a "filter" through which to pass the Perl files being put into the PAR archive. Specifying this sub-class as the filter (i.e. "-f Crypto" for scripts and/or "-F Crypto" for modules) means that the Perl files will be encrypted using the Filter::Crypto::CryptFile module. The resulting encrypted files are what will be placed in the PAR archive.

Note that the encrypted script requires the Filter::Crypto::Decrypt module in order to decrypt itself when it is run. The original Perl script will not have specified any such dependency, so pp will not automatically include that module in the PAR archive for you. Therefore, you must use the -M option to force that module to be included. Also note that if you use the -F option to encrypt modules as well then the filtering will automatically skip the Filter::Crypto::Decrypt module itself for obvious reasons. A typical pp invocation is thus something like:

$ pp -f Crypto -F Crypto -M Filter::Crypto::Decrypt -o hello hello.pl

(Version 0.75 of the Module::ScanDeps module, used by pp to scan for dependencies that need including in the PAR archive, is known to have problems finding shared library files for modules specified by pp's -M option (as illustrated above). If you find that the shared library file for Filter::Crypto::Decrypt is missing from your PAR archive then you need to upgrade Module::ScanDeps to version 0.76 or higher.)

Of course, you must not include the Filter::Crypto::CryptFile module as well, otherwise people to whom you distribute your PAR archive will have the means to easily decrypt the encrypted Perl script within it!

Also, note that the script is encrypted by reading its entire contents into memory, encrypting it in memory, and then writing it out to disk. This should be safe for most purposes given that Perl scripts are typically not very large, but other methods should be considered instead if this is likely to cause out-of-memory errors due to the size of the scripts, e.g. if the scripts have very large __DATA__ sections.

Methods

apply($ref)

Class method. Encrypts the Perl source code referred to by $ref, and replaces the code referred to by $ref with the encrypted code. Thus, the code in $$ref gets encrypted "in-place".

Returns 1 on success, or croak()s on failure (since the usual caller, PAR::Filter::apply(), does not bother checking the return value (as of PAR::Filter version 0.02, at least)).

DIAGNOSTICS

Warnings and Error Messages

This module may produce the following diagnostic messages. They are classified as follows (a la perldiag):

(W) A warning (optional).
(F) A fatal error (trappable).
(I) An internal error that you should never see (trappable).
Can't close temporary filehandle after encryption: %s

(W) The temporary file used to perform the encryption could not be closed after use. The system error message corresponding to the standard C library errno variable is also given.

Can't rewind temporary filehandle before encryption: %s

(F) The temporary file used to perform the encryption could not be rewound before encrypting the source that was just written to it. The system error message corresponding to the standard C library errno variable is also given.

Can't rewind temporary filehandle after encryption: %s

(F) The temporary file used to perform the encryption could not be rewound after encrypting the source code that was written to it. The system error message corresponding to the standard C library errno variable is also given.

crypt_file() failed: %s

(F) The crypt_file() function from the Filter::Crypto::CryptFile module that is used to perform the encryption failed. The last error message from the Filter::Crypto::CryptFile module is also given.

Detected Module::ScanDeps version 0.75, which may not work correctly with PAR::Filter::Crypto

(W) Your current installation of the Module::ScanDeps module, used by pp to scan for dependencies that need including in the PAR archive, was found to be version 0.75, which is known to have problems finding shared library files for modules specified by pp's -M option. If you are running pp with the -M option and find that the shared library file for Filter::Crypto::Decrypt is missing from your PAR archive then you need to upgrade Module::ScanDeps to version 0.76 or higher.

EXPORTS

None.

KNOWN BUGS

  • The following test failure is expected if your current installation of Module::ScanDeps is version 0.75:

    t/04_par.t test 6

    This failure is the result of a bug in that version of Module::ScanDeps, and can be rectified by upgrading Module::ScanDeps to version 0.76 or higher. See DESCRIPTION for more information.

SEE ALSO

PAR::Filter;

Filter::Crypto.

ACKNOWLEDGEMENTS

The apply() method is based on that in the PAR::Filter::Bytecode module in the PAR distribution (version 0.85), written by Autrijus Tang.

AUTHOR

Steve Hay <shay@cpan.org>

COPYRIGHT

Copyright (C) 2004-2008 Steve Hay. All rights reserved.

LICENCE

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself, i.e. under the terms of either the GNU General Public License or the Artistic License, as specified in the LICENCE file.

VERSION

Version 1.04

DATE

25 Aug 2008

HISTORY

See the Changes file.