NAME

crypt_file - Encrypt (and decrypt) Perl files

SYNOPSIS

    crypt_file [--list-file=<file>]
               [--dir=<dir>]... [--recurse]
               [--test] [--silent]
               [--in-place] [--edit-mode=<mode>] [--bak-file-expr[=<expr>]]
               [--out-file-expr=<expr>]
               [--crypt-mode=<mode>]
               [--version] [--help] [--manpage]
               [<file-spec>...]

ARGUMENTS

<file-spec>: Specify one or more files on which to perform the encryption or decryption. Each file specifier may be one of:

An absolute file path;
A relative file path;
A shell-style file glob expression.

This list of file specifiers, together with any more read from the file specified by the --list-file option (if present), is used to build the input file list as follows:

Each absolute file path is added directly to the input file list;
Each relative file path is tested against each directory in the search directory list in turn until the first existing file path is found, which is then added to the input file list;
Each file glob expression is expanded against every directory in the search directory list in turn, and all the resulting file paths are then added to the input file list.
Note that typical UNIX shells will expand glob expressions before calling the program unless the expressions are quoted (normally with single quotes). The default Win32 cmd.exe shell does not do this, and does not remove single quotes from arguments either, so beware!

By default, the search directory list is just the current working directory, but other directories may be specified instead by using one or more --dir options.

If there are no file specifiers given, or if there is a single input file specifier consisting of just a single dash given, then input is read from <STDIN> instead.

OPTIONS

-l <file>, --list-file=<file>

Specify a file that lists file specifiers to use in building the input file list (one file specifier per line).

This file may be used as well as, or instead of, file specifiers given as arguments to this script.

See "ARGUMENTS" for more details on file specifiers.

-d <dir>, --dir=<dir>

Specify one or more directories to assign to the search directory list that is used to resolve relative file paths and/or expand file glob expressions in the list of input file specifiers.

Multiple directories can be assigned to the list by specifying multiple --dir options and/or specifying multiple directories separated by the path separator character with a single --dir option.

To determine what the path separator character is on your system type the following:

    perl -V:path_sep

By default, the search directory list is just the current working directory. If one or more directories are specified via this option then they replace the default, so if you want to include the current working directory as well as other directories then you will have to explicitly specify that too.

-r, --recurse

Specify that when expanding any file glob expressions in the list of input file specifiers, each glob should be expanded in all sub-directories (recursively) of each directory in the search directory list.

This option does not affect the resolution of relative file paths in the list of input file specifiers.

-t, --test

Run the script in test-only mode.

The input file list will be printed to "STDOUT", but no other action is taken. No input files are edited, and no backup files or output files are created.

-s, --silent

Run the script in silent mode.

The name of each input file is normally printed on "STDERR" before it is processed, followed by an "OK" message (and/or a warning or error message if anything went wrong) when the processing of that file is complete. Running in silent mode suppresses the output of the filename and "OK" message; any relevant warnings and/or error messages are still output.

-i, --in-place

Specify that each input file should be processed "in-place", i.e. the input file is overwritten with the output, rather than the output being sent either to "STDOUT" or else to an output file as specified by the --out-file-expr option.

This option is ignored if the input file list is empty and input is being read from "STDIN" instead.

-e <mode>, --edit-mode=<mode>

Specify how in-place editing should be performed:

memory: The entire contents of the input file are read into memory, processed in memory, and then written back out to the input file.
tempfile: The contents of the input file are processed and written out to a temporary file in chunks of at most "BUFSIZ" bytes at a time, and then the temporary file is renamed to the input file.

The default mode is "memory", which should be safe for most purposes given that Perl source code files are typically not very large, but the "tempfile" mode should be considered instead if this is likely to cause out-of-memory errors due to the size of the files, e.g. if the files have very large "__DATA__" sections.

The "tempfile" mode also has another useful advantage when combined with the "encrypted" or "decrypted" --crypt-mode option values: The file processing becomes safely re-runnable in the event of any errors on a first run because each input file is not touched until the final step in its processing when the temporary file that has been used up until then is renamed to it. Renaming a file is normally an atomic operation at the filesystem level, so even if the processing is interrupted or killed part-way through, each input file will be left either untouched or else fully encrypted or decrypted; there will be no partially written files left (other than temporary files, which are cleaned up if at all possible). Combined with, say, --crypt-mode=encrypted, this mode can therefore safely be used to run, and, if necessary, re-run, on a set of input files until they have all be successfully encrypted.

This option only applies when input files are being processed "in-place", and implies the --in-place option if that is not already present.

-b [<expr>], --bak-file-expr[=<expr>]: Specify an expression from which to determine the name of a backup file to create before processing each input file.
The optional expr value works in a similar way to the value for perl's own -i option, with a couple of enhancements:

•: If the expr contains one or more "*", "?" or "[" characters then

Each "*" character is replaced with the input file's basename (i.e. with the directory path removed from the start);
Each "?" character is replaced with the input file's basename minus the extension (i.e. the same as the basename used above, but with whatever matches "/\..*?$/" removed from the end);
Each "[" character is replaced with the input file's extension (i.e. the part that was removed from the basename above).

The resulting expression is then used as the name of the backup file.

•: Otherwise, the expr is appended to the input filename to make the name of the backup file.

In each case, the backup file is created in the same directory as the input file itself.

The default expr value is "*.bak".

This option only applies when input files are being processed "in-place", and implies the --in-place option if that is not already present.

-o <expr>, --out-file-expr=<expr>

Specify an expression from which to determine the name of an output file to send the output to when processing each input file.

The mandatory expr value works in exactly the same way as the expr value to the --bak-file-expr option described above, except that if the input file list is empty and input is being read from "STDIN" instead then the expr is used as the actual path (either absolute or relative to the current directory) of the output file itself.

This option is mutually exclusive with the --in-place option; if both options are specified then --in-place will be used and --out-file-expr is ignored.

The output is written to "STDOUT" by default.

-c <mode>, --crypt-mode=<mode>

Specify what action, if any, to perform on each file:

auto

The crypt mode is determined automatically on a per-file basis by reading the beginning of the file. If the beginning is

    use Filter::Crypto::Decrypt;

then the file is presumed to be in an encrypted state already so the mode will be set to "decrypt"; otherwise the mode will be set to "encrypt".

encrypt

Each input file is encrypted. Produces a warning if a file looks like it is already in an encrypted state, i.e. already begins with a "use Filter::Crypto::Decrypt;" statement.

decrypt

Each input file is decrypted. Produces a warning if a file looks like it is already in a decrypted state, i.e. does not begin with a "use Filter::Crypto::Decrypt;" statement.

encrypted

Each input file is encrypted unless it looks like it is already in an encrypted state, i.e. already begins with a "use Filter::Crypto::Decrypt;" statement.

decrypted

Each input file is decrypted unless it looks like it is already in a decrypted state, i.e. does not begin with a "use Filter::Crypto::Decrypt;" statement.

The default mode is "auto".

-v, --version: Display the script name and version, and then exit.
-h, --help | --?: Display a help page listing the arguments and options, and then exit.
-m, --manpage | --doc: Display the entire manual page, and then exit.

Options may be introduced with a double dash, a single dash, a plus sign or (on Win32) a forward slash; case does not matter; an equals sign may be used or omitted between option names and values; long option names may be abbreviated to uniqueness.

Options may also be placed between non-option arguments, and option processing may be stopped at any point in the command-line by inserting a double dash.

EXIT STATUS

    0   The script exited normally.

    1   The script exited after printing the version, help or manpage.

    2   Invalid command-line arguments.

    >2  An error occurred.

DIAGNOSTICS

Warnings and Error Messages

This script 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).

Warnings of the format "%s: Error: ..." and "%s: Warning: ..." are produced from within the main loop over the input file list. Those that say "Error:" are severe warnings that result in the processing of the specified input file to be aborted; in such cases, the script moves onto the next file in the list. Those that say "Warning:" are less serious warnings; in those cases, the script continues the processing of the file concerned. Other messages come from elsewhere in the script.

Can't cd back to '%s': %s: (F) Could not change back to the specified directory after changing into one of its sub-directories during a (possibly recursive) scan of the search directory list while attempting to expand a file glob expression in the list of input file specifiers. The system error message corresponding to the standard C library "errno" variable is also given.
Can't cd to '%s' from '%s': %s: (W) Could not change directory as indicated during a (possibly recursive) scan of the search directory list while attempting to expand a file glob expression in the list of input file specifiers. The search down that particular branch of the directory tree will be aborted, but other branches and search directories will continue to be scanned. The system error message corresponding to the standard C library "errno" variable is also given.
Can't close list file '%s' after reading: %s: (W) The specified list file (i.e. the file given by the --list-file option) could not be closed after reading the list of input file specifiers from it. The system error message corresponding to the standard C library "errno" variable is also given.
Can't close temporary file '%s': %s: (W) The specified temporary file could not be closed during the clean up of temporary files just before exiting when a SIGINT has been caught. The system error message corresponding to the standard C library "errno" variable is also given.
Can't delete temporary file '%s': %s: (W) The specified temporary file could not be deleted during the clean up of temporary files just before exiting when a SIGINT has been caught, or when removing an unneeded temporary file when an input file was found to already be in the requested state. The system error message corresponding to the standard C library "errno" variable is also given.
Can't open list file '%s' for reading: %s: (F) The specified list file (i.e. the file given by the --list-file option) from which to read the list of input file specifiers could not be opened for reading. The system error message corresponding to the standard C library "errno" variable is also given.
Caught SIGINT. Cleaning up temporary files before exiting: (W) The script has received an "interrupt" signal, e.g. the user may have pressed Ctrl+C. The signal is caught so that temporary files, used when editing files in-place with --edit-mode=tempfile, can be cleaned up before exiting.
%s: Error: Can't copy to backup file '%s': %s: (W) The specified input file could not be copied to the specified backup file. The system error message corresponding to the standard C library "errno" variable is also given.
%s: Error: Can't make file writable: %s: (W) [Win32 only.] The specified input file could not be made writable. On Win32 (only), the input file must be writable when editing files in-place using temporary files in order for the final step (in which the temporary file is renamed to the input file) to succeed. (On other systems, the ability to perform a rename is controlled by the permissions on the parent directory.) The system error message corresponding to the standard C library "errno" variable is also given.
%s: Error: Can't rename temporary file '%s' to input file: %s: (W) The specified temporary file could not be renamed to the specified input file. This is the final step of the process when editing files in-place using temporary files. The system error message corresponding to the standard C library "errno" variable is also given.
%s: Error: Can't stat file: %s: (W) Could not retrieve file information about the specified input file. This information is required when editing files in-place using temporary files in order to set the same file permissions on the temporary file as are on the input file before renaming the temporary file to the input file. The system error message corresponding to the standard C library "errno" variable is also given.
%s: Error: crypt_file() failed: %s: (W) The call to the "crypt_file()" function to perform the actual encryption or decryption failed. The last error message from the Filter::Crypto::CryptFile module is also given.
No such file '%s': (W) The specified input file specifier could not be resolved, either as an absolute file path, or as a relative file path or a file glob expression with respect to the current working directory or any of the directories specified with the --dir option.
Unknown edit mode '%s': (I) The mode specified for editing files in-place (i.e. the mode given by the --edit-mode option) was not recognized and was not caught by the option processing code run at the start of the script, causing an unexpected error later on.
Unknown warning type '%s': (I) The subroutine called internally when outputting warning messages was passed a warning type that it does not recognize.
%s: Warning: Can't close temporary file '%s' after writing: %s: (W) The filehandle opened on the temporary file being used to edit the specified input file in-place could not be closed after writing data to it. The system error message corresponding to the standard C library "errno" variable is also given.
%s: Warning: Can't set permissions on temporary file '%s': %s: (W) Could not set the file permissions on the temporary file to be the same as are on the specified input file. This is done when editing files in-place using temporary files so that the file permissions are left unchanged after the editing has been completed. The system error message corresponding to the standard C library "errno" variable is also given.

EXAMPLES

These examples assume standard UNIX shell quoting and redirection syntax apply. On Win32, you should replace single-quoted arguments with double-quoted arguments. (The redirection syntax is unchanged.)

Process test.pl, writing output to testenc.pl:

    crypt_file <test.pl >testenc.pl

    crypt_file test.pl >testenc.pl

    crypt_file -o '?enc.pl' test.pl

Process test.pl in-place, making a backup copy as test.pl.bak:

    crypt_file -i -b '*.bak' test.pl

Process test.pl in-place, with no backup copy:

    crypt_file -i test.pl

Process all *.pl files within /tmp and all sub-directories in-place:

    crypt_file -i -d /tmp -r '*.pl'

ENVIRONMENT

PERL_CRYPT_FILE_OPTS: Specify options to be prepended to the list of command-line options before the option processing takes place.
Note that as far as quoting and escaping is concerned, the environment variable value is interpreted in the same way as the Bourne shell would interpret the corresponding command-line.

KNOWN BUGS

None.

AUTHOR

Steve Hay <shay@cpan.org <mailto:shay@cpan.org>>.

COPYRIGHT

LICENCE

This script 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 2.09

DATE

08 Dec 2020

HISTORY

See the Changes file.