/ 
Filter-Crypto-1.18
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

# 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 command-line option can be used to specify a "filter" through which to pass the Perl script being put into the PAR archive. Specifying this sub-class as the filter (i.e. "-f Crypto") means that the Perl script will be encrypted using the Filter::Crypto::CryptFile module. The resulting encrypted script is 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. A typical pp invocation is thus something like:

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

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.

EXPORTS

None.

KNOWN BUGS

None.

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-2006 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.02

DATE

14 Feb 2006

HISTORY

See the Changes file.