Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Filter::Crypto::CryptFUser3Contributed Perl DocumeFilter::Crypto::CryptFile(3)

NAME
       Filter::Crypto::CryptFile - Encrypt (and	decrypt) Perl files

SYNOPSIS
	   use Filter::Crypto::CryptFile qw(:DEFAULT $ErrStr);

	   # Encrypt one filehandle (or	file name) to another.
	   crypt_file($in_fh,	$out_fh,   $crypt_mode)	or
	       die "crypt_file() failed: $ErrStr\n";
	   crypt_file($in_file,	$out_file, $crypt_mode)	or
	       die "crypt_file() failed: $ErrStr\n";

	   # The crypt mode can	be determined automatically.
	   crypt_file($in_fh,	$out_fh)   or die "crypt_file()	failed:	$ErrStr\n";
	   crypt_file($in_file,	$out_file) or die "crypt_file()	failed:	$ErrStr\n";

	   # Encrypt one filehandle (or	file name) in-place (in	memory).
	   crypt_file($in_out_fh,   $crypt_mode) or
	       die "crypt_file() failed: $ErrStr\n";
	   crypt_file($in_out_file, $crypt_mode) or
	       die "crypt_file() failed: $ErrStr\n";

	   # The crypt mode can	be determined automatically.
	   crypt_file($in_out_fh)   or die "crypt_file() failed: $ErrStr\n";
	   crypt_file($in_out_file) or die "crypt_file() failed: $ErrStr\n";

DESCRIPTION
       This module provides a single function called "crypt_file()" for
       converting files	to/from	an encrypted state in which they can be	run
       via Filter::Crypto::Decrypt.

       The function takes either a pair	of open	filehandles (one to read from
       and one to write	to) or else a single open filehandle (to process "in-
       place").	 (File names can also be specified instead of open
       filehandles.)  It reads data from the input source, either encrypts it
       or decrypts it according	to the "crypt mode", and then writes the
       result to the output source.

       In each case, the "crypt	mode" may either be explicitly specified using
       the "CRYPT_MODE_*" flags, or else it can	be omitted (or specified as
       "undef" or the null string) in order to be determined automatically by
       "crypt_file()".

   Functions
       "crypt_file($in_fh, $out_fh[, $crypt_mode])"
       "crypt_file($in_out_fh[,	$crypt_mode])"
	   If two open filehandles, $in_fh and $out_fh,	are supplied then
	   input is read from $in_fh, encrypted	or decrypted, and the output
	   is written to $out_fh.  Clearly $in_fh must have been opened	for
	   reading and $out_fh must have been opened for writing.  Only	a
	   small amount	of data	is held	in memory at any time, so this method
	   is safe to use for "large" files without using unduly large amounts
	   of memory.

	   If only one open filehandle,	$in_out_fh, is supplied	then input is
	   read	from it, encrypted or decrypted, and the output	is written
	   back	to it after truncating the file	to zero	size.  In this case,
	   $in_out_fh must have	been opened for	"updating" (both reading and
	   writing).  Using this method	the whole file is read into memory in
	   one go, so it is not	suitable for use on "large" files.  This is
	   unlikely to be a problem in practice, however, since	Perl source
	   code	files are rarely, if ever, sufficiently	large to cause any
	   trouble in this regard.

	   Note	that the filehandle being written to when encrypting and the
	   filehandle being read from when decrypting must be opened in
	   "binary" mode on those platforms where it makes a difference
	   (notably Win32), otherwise the encrypted "binary" data being
	   written or read may become corrupted	by CR-LF translations.	It
	   will	also be	necessary to open the other filehandle (which the Perl
	   source code itself is being read from or written to)	in "binary"
	   mode	too if the Perl	source code happens to contain any "binary"
	   data, e.g. in a "__DATA__" section.

	   File	names may be supplied instead of open filehandles, in which
	   case	they will be opened appropriately by "crypt_file()" itself and
	   closed again	after use.  ("crypt_file()" always opens the
	   filehandles in "binary" mode	so any "binary"	data in	the Perl
	   source code will be correctly handled.)

	   The optional	$crypt_mode argument specifies whether to perform
	   encryption or decryption.  If it is omitted or specified as "undef"
	   or the null string then the crypt mode will be determined
	   automatically by reading the	beginning of the input data.  If the
	   beginning is

	       use Filter::Crypto::Decrypt;

	   then	the data is presumed to	be in an encrypted state already so
	   the mode will be set	to "CRYPT_MODE_DECRYPT"; otherwise the mode
	   will	be set to "CRYPT_MODE_ENCRYPT".

	   On success, returns the number of bytes written (which could	be
	   zero	if the input was already in the	requested state, in which case
	   the special "zero but true" value will be returned);	on failure
	   returns the undefined value (in scalar context) or the empty	list
	   (in list context) and sets $ErrStr.

   Crypt Mode Flags
       The $crypt_mode argument	in "crypt_file()" specifies whether to encrypt
       or decrypt the input data, as follows:

       "CRYPT_MODE_AUTO"
	   Have	the crypt mode determined automatically	by the same means as
	   described under "crypt_file()" in the case where the	$crypt_mode
	   argument is omitted or specified as "undef" or the null string.

       "CRYPT_MODE_ENCRYPT"
	   Encrypt the input data and prepend the statement

	       use Filter::Crypto::Decrypt;

	   to the output data so that it can be	run via
	   Filter::Crypto::Decrypt.  Produces a	warning	if the input data
	   already has that statement at the beginning.

       "CRYPT_MODE_DECRYPT"
	   Decrypt the input data after	first removing the statement

	       use Filter::Crypto::Decrypt;

	   from	the beginning.	Produces a warning if the input	data does not
	   have	that statement at the beginning.

       "CRYPT_MODE_ENCRYPTED"
	   The same as "CRYPT_MODE_ENCRYPT" except that	the encryption is not
	   performed if	the input data already begins with the statement

	       use Filter::Crypto::Decrypt;

	   Thus, unencrypted data will be encrypted, while encrypted data will
	   not be encrypted a second time.

       "CRYPT_MODE_DECRYPTED"
	   The same as "CRYPT_MODE_DECRYPT" except that	the decryption is not
	   attempted if	the input data does not	begin with the statement

	       use Filter::Crypto::Decrypt;

	   Thus, encrypted data	will be	decrypted, while unencrypted data will
	   not be decrypted a second time.

   Variables
       $ErrStr
	   Last	error message.

	   If the "crypt_file()" function fails	then a description of the last
	   error will be set in	this variable for use in reporting the cause
	   of the failure, much	like the use of	the Perl Special Variables $!
	   and $^E after failed	system calls and OS API	calls.	See "Error
	   Values" for a listing of the	possible values	of $ErrStr.

	   If the function succeeds then this variable will generally be set
	   to the null string.	The only exceptions to this are	when the crypt
	   mode	was specified as either	"CRYPT_MODE_ENCRYPTED" or
	   "CRYPT_MODE_DECRYPTED" and the input	data was found to be already
	   encrypted or	decrypted respectively so that no action was required:
	   in these cases a message to this effect will	be set in $ErrStr.

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 file	'%s' after updating: %s
	   (W) The specified file opened by "crypt_file()" for reading data
	   from	and writing data to when updating a file "in-place" could not
	   be closed after use.	 The system error message corresponding	to the
	   standard C library "errno" variable is also given.

       Can't close input file '%s' after reading: %s
	   (W) The specified input file	opened by "crypt_file()" for reading
	   data	from could not be closed after use.  The system	error message
	   corresponding to the	standard C library "errno" variable is also
	   given.

       Can't close output file '%s' after writing: %s
	   (W) The specified output file opened	by "crypt_file()" for writing
	   data	to could not be	closed after use.  The system error message
	   corresponding to the	standard C library "errno" variable is also
	   given.

       Can't release lock on filehandle	after updating:	%s
	   (W) The exclusive lock acquired by "crypt_file()" on	the filehandle
	   used	for reading data from and writing data to when updating	a file
	   "in-place" could not	be released after use.	The system error
	   message corresponding to the	standard library "errno" variable is
	   also	given.

       Can't release lock on input filehandle after reading: %s
	   (W) The shared lock acquired	by "crypt_file()" on the input
	   filehandle used for reading data from could not be released after
	   use.	 The system error message corresponding	to the standard	C
	   library "errno" variable is also given.

       Can't release lock on output filehandle after writing: %s
	   (W) The exclusive lock acquired by "crypt_file()" on	the output
	   filehandle used for writing data to could not be released after
	   use.	 The system error message corresponding	to the standard	C
	   library "errno" variable is also given.

       chsize/ftruncate	not implemented
	   (F) The attempt by "crypt_file()" to	truncate the file to zero size
	   before writing the data to it when updating a file "in-place"
	   failed because the "chsize()" and "ftruncate()" functions are not
	   implemented on this system.

       Input data already contains decryption filter
	   (W) The crypt mode was specified as "CRYPT_MODE_ENCRYPT" but	data
	   read	from the input filehandle already begins with the statement

	       use Filter::Crypto::Decrypt;

	   Perhaps you are attempting to encrypt data when you meant to	be
	   decrypting it?

       Input data does not contain decryption filter
	   (W) The crypt mode was specified as "CRYPT_MODE_DECRYPT" but	data
	   read	from the input filehandle did not begin	with the statement

	       use Filter::Crypto::Decrypt;

	   Perhaps you are attempting to decrypt data when you meant to	be
	   encrypting it?

       %s is not a filehandle or a file	name
	   (F) The first parameter for "crypt_file()" must be either a valid
	   (open) filehandle or	a file name, but the argument passed was
	   neither of these things.

       %s is not a valid crypt mode
	   (F) The third parameter for "crypt_file()" must be either "undef"
	   or the null string (meaning determine the crypt mode
	   automatically), or a	valid crypt mode (i.e. one of the
	   "CRYPT_MODE_*" flags), but the argument passed was neither of these
	   things.

       %s is not a valid crypt mode or a filehandle or a file name
	   (F) The second parameter for	"crypt_file()" must be one of: "undef"
	   or the null string (meaning determine the crypt mode
	   automatically), a valid crypt mode (i.e. one	of the "CRYPT_MODE_*"
	   flags), or a	valid (open) filehandle	or a file name,	but the
	   argument passed was none of these things.

       %s is not a valid Filter::Crypto::CryptFile macro
	   (F) You attempted to	lookup the value of the	specified constant in
	   the Filter::Crypto::CryptFile module, but that constant is unknown
	   to this module.

       No such package '%s'
	   (F) This module's bootstrap function	was called on the specified
	   package, which does not exist.

       Random IV may not be cryptographically strong
	   (W) libcrypto's random number generator failed to generate
	   cryptographically strong pseudo-random bytes	for use	as the
	   initialization vector (IV) in the encryption.  A weaker sequence of
	   pseudo-random bytes was used	instead, which is not necessarily
	   unpredictable and may not be	suitable for this purpose.

       Random salt may not be cryptographically	strong
	   (W) libcrypto's random number generator failed to generate
	   cryptographically strong pseudo-random bytes	for use	as the salt
	   when	performing the key derivation before encryption.  A weaker
	   sequence of pseudo-random bytes was used instead, which is not
	   necessarily unpredictable and may not be suitable for this purpose.

       Unexpected error	in AUTOLOAD(): constant() is not defined
	   (I) There was an unexpected error looking up	the value of a
	   constant: the constant-lookup function itself is apparently not
	   defined.

       Unexpected return type %d while processing Filter::Crypto::CryptFile
       macro %s
	   (I) There was an unexpected error looking up	the value of the
	   specified constant: the C component of the constant-lookup function
	   returned an unknown type.

       Unknown crypt mode '%d'
	   (I) The XSUB	called internally by "crypt_file()" was	passed a crypt
	   mode	that it	does not recognize or failed to	derive correctly a
	   crypt mode for setting in the crypto	context	structure to be	used
	   when	performing the encryption or decryption.

       Unknown crypto context mode '%d'
	   (I) The crypto context structure used internally when performing
	   encryption or decryption has	been set-up with a crypt mode that it
	   does	not recognize.

       Your vendor has not defined Filter::Crypto::CryptFile macro %s
	   (I) You attempted to	lookup the value of the	specified constant in
	   the Filter::Crypto::CryptFile module, but that constant is
	   apparently not defined.

   Error Values
       The "crypt_file()" function sets	$ErrStr	to a value indicating the
       cause of	the error when it fails.  The possible values are as follows:

       Can't acquire exclusive lock on output filehandle: %s
	   The filehandle used by "crypt_file()" for writing data to could not
	   be locked for exclusive use.	 The system error message
	   corresponding to the	standard C library "errno" variable is also
	   given.

       Can't acquire exclusive lock on update filehandle: %s
	   The filehandle used by "crypt_file()" for reading data from and
	   writing data	to when	updating a file	"in-place" could not be	locked
	   for exclusive use.  The system error	message	corresponding to the
	   standard C library "errno" variable is also given.

       Can't acquire shared lock on input filehandle: %s
	   The filehandle used by "crypt_file()" for reading data from could
	   not be locked for shared use.  The system error message
	   corresponding to the	standard C library "errno" variable is also
	   given.

       Can't cleanup cipher context: %s
	   The cipher context structure	used to	perform	the encryption or
	   decryption could not	be cleaned up after use.  The last error
	   message from	libcrypto is also given.

       Can't decode odd-numbered (%d-byte) length hexadecimal text
	   The hexadecimal encoding of the encrypted source code, consisting
	   of a	pair of	hexadecimal digits for each byte of data, could	not be
	   decoded because an odd number of hexadecimal	digits were found.

       Can't decode non-hexadecimal digit (byte	%02x at	position %d) in
       hexadecimal text
	   The hexadecimal encoding of the encrypted source code, consisting
	   of a	pair of	hexadecimal digits for each byte of data, could	not be
	   decoded because a byte other	than a hexadecimal digit was found.

       Can't derive %d-byte key: %s
	   libcrypto's PKCS#5 v2.0 compatible key derivation algorithm failed
	   to derive a key of the specified length from	the supplied password
	   for use in the encryption or	decryption.  The last error message
	   from	libcrypto is also given.

       Can't finalize cipher context: %s
	   The cipher context structure	used to	perform	the encryption or
	   decryption could not	be finalized.  The last	error message from
	   libcrypto is	also given.

       Can't generate %d-byte random salt: %s
	   libcrypto's random number generator failed to generate the
	   specified number of pseudo-random bytes for use as the salt when
	   performing the key derivation prior to encryption.  The last	error
	   message from	libcrypto is also given.

       Can't generate %d-byte random IV: %s
	   libcrypto's random number generator failed to generate the
	   specified number of pseudo-random bytes for use as the
	   initialization vector (IV) in the encryption.  The last error
	   message from	libcrypto is also given.

       Can't initialize	cipher context in crypt	mode '%d': %s
	   The cipher context structure	used to	perform	the encryption or
	   decryption could not	be initialized in the specified	crypt mode.
	   This	is the first stage of the cipher context structure
	   initialization, performed before setting the	key length and
	   modifying other cipher parameters.  The last	error message from
	   libcrypto is	also given.

       Can't initialize	cipher context in crypt	mode '%d' using	%d-byte	key:
       %s
	   The cipher context structure	used to	perform	the encryption or
	   decryption could not	be initialized in the specified	crypt mode
	   with	the specified key length.  This	is the final stage of the
	   cipher context structure initialization, performed after setting
	   the key length and modifying	other cipher parameters.  The last
	   error message from libcrypto	is also	given.

       Can't initialize	PRNG
	   libcrypto's random number generator could not be seeded with	enough
	   entropy.

       Can't open file '%s' for	updating: %s
	   The specified file could not	be opened by "crypt_file()" for
	   reading data	from and writing data to when updating a file "in-
	   place".  The	system error message corresponding to the standard C
	   library "errno" variable is also given.

       Can't open input	file '%s' for reading: %s
	   The specified file from which to read data could not	be opened for
	   reading by "crypt_file()".  The system error	message	corresponding
	   to the standard C library "errno" variable is also given.

       Can't open output file '%s' for writing:	%s
	   The specified file could not	be opened by "crypt_file()" for
	   writing data	to.  The system	error message corresponding to the
	   standard C library "errno" variable is also given.

       Can't read from input filehandle: %s
	   There was an	error reading data from	the input filehandle.  The
	   system error	message	corresponding to the standard C	library
	   "errno" variable is also given.

       Can't set key length to %d: %s
	   The specified key length could not be set for the cipher context
	   structure used to perform the encryption or decryption.  The	last
	   error message from libcrypto	is also	given.

       Can't set RC2 effective key bits	to %d: %s
	   The specified effective key bits could not be set for the cipher
	   context structure used to perform the encryption or decryption when
	   using the RC2 cipher.  The last error message from libcrypto	is
	   also	given.

       Can't set RC5 number of rounds to %d: %s
	   The specified number	of rounds could	not be set for the cipher
	   context structure used to perform the encryption or decryption when
	   using the RC5 cipher.  The last error message from libcrypto	is
	   also	given.

       Can't truncate filehandle: %s
	   The filehandle used by "crypt_file()" for reading data from and
	   writing data	to when	updating a file	"in-place" could not be
	   truncated to	zero size before writing data to it.  The system error
	   message corresponding to the	standard C library "errno" variable is
	   also	given.

       Can't update cipher context with	%d bytes of in-text: %s
	   The cipher context structure	used to	perform	the encryption or
	   decryption could not	be updated with	the specified number of	bytes
	   of input data.  The last error message from libcrypto is also
	   given.

       Can't write header line to output filehandle: %s
	   There was an	error writing the statement

	       use Filter::Crypto::Decrypt;

	   to the output filehandle.  The system error message corresponding
	   to the standard C library "errno" variable is also given.

       Can't write to filehandle: %s
	   There was an	error writing data to the filehandle when updating a
	   file	"in-place".  The system	error message corresponding to the
	   standard C library "errno" variable is also given.

       Can't write to output filehandle: %s
	   There was an	error writing data to the output filehandle.  The
	   system error	message	corresponding to the standard C	library
	   "errno" variable is also given.

       Derived key length is wrong (%d,	expected %d)
	   libcrypto's PKCS#5 v1.5 compatible key derivation algorithm failed
	   to derive a key of the requested length from	the supplied password
	   for use in the encryption or	decryption.

       Input data was already decrypted
	   The crypt mode was specified	as "CRYPT_MODE_DECRYPTED" and data
	   read	from the input filehandle does not begin with the statement

	       use Filter::Crypto::Decrypt;

	   indicating that the data is probably	already	decrypted.  No action
	   was taken, and "crypt_file()" returned success.  Use	the crypt mode
	   "CRYPT_MODE_DECRYPT"	if you really want to force decryption in this
	   case.

       Input data was already encrypted
	   The crypt mode was specified	as "CRYPT_MODE_ENCRYPTED" and data
	   read	from the input filehandle already begins with the statement

	       use Filter::Crypto::Decrypt;

	   indicating that the data is probably	already	encrypted.  No action
	   was taken, and "crypt_file()" returned success.  Use	the crypt mode
	   "CRYPT_MODE_ENCRYPT"	if you really want to force encryption in this
	   case.

EXAMPLES
       See the crypt_file script for examples of the use of the	"crypt_file()"
       function.

EXPORTS
       The following symbols are, or can be, exported by this module:

       Default Exports
	   "crypt_file";

	   "CRYPT_MODE_AUTO", "CRYPT_MODE_ENCRYPT", "CRYPT_MODE_DECRYPT",
	   "CRYPT_MODE_ENCRYPTED", "CRYPT_MODE_DECRYPTED".

       Optional	Exports
	   $ErrStr.

       Export Tags
	   None.

KNOWN BUGS
       None.

CAVEATS
       o   Note	that specifying	the "crypt_mode" as "CRYPT_MODE_AUTO", "undef"
	   or the null string can be used to resolve any ambiguity in the case
	   where "crypt_file()"	is called with two arguments, namely, did the
	   caller intend "crypt_file($in_file, $out_file)" or
	   "crypt_file($in_out_file, $crypt_mode)"?

	   In such cases, "crypt_file()" checks	if the second argument is a
	   valid "crypt	mode" before considering if it is a file name, so it
	   normally Does The Right Thing.  However, if you wanted to write the
	   output to a file called 1 (which happens to be the value of the
	   "CRYPT_MODE_ENCRYPT"	flag) then calling

	       crypt_file($in_file, '1');

	   will	not do what you	want.  In this case, you can call

	       crypt_file($in_file, '1', CRYPT_MODE_AUTO);

	   instead to get the desired behaviour	(without having	to explicitly
	   specify the crypt mode).

SEE ALSO
       Filter::Crypto.

ACKNOWLEDGEMENTS
       The "FilterCrypto_PRNGInit()" and "FilterCrypto_GetRandNum()" functions
       used by the XS code are based on	code taken from	the "ssl_rand_seed()"
       and "ssl_rand_choosenum()" functions in Apache httpd (version 2.4.9).

       Thanks to Steve Henson for help with performing PBE and PKCS#5 v2.0 key
       derivation with arbitrary ciphers and non-default key lengths using the
       OpenSSL libcrypto library.

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

COPYRIGHT
       Copyright (C) 2004-2009,	2012-2014 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 2.09

DATE
       08 Dec 2020

HISTORY
       See the Changes file.

perl v5.32.1			  2020-12-08	  Filter::Crypto::CryptFile(3)

NAME | SYNOPSIS | DESCRIPTION | DIAGNOSTICS | EXAMPLES | EXPORTS | KNOWN BUGS | CAVEATS | SEE ALSO | ACKNOWLEDGEMENTS | AUTHOR | COPYRIGHT | LICENCE | VERSION | DATE | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Filter::Crypto::CryptFile&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help