Crypt-FileHandle

 view release on metacpan or  search on metacpan

lib/Crypt/FileHandle.pm  view on Meta::CPAN

1;

__END__

=head1 NAME

Crypt::FileHandle - encrypted FileHandle

=head1 SYNOPSIS

  use Crypt::CBC;
  use Crypt::FileHandle;

  # example cipher
  $cipher = Crypt::CBC->new(
  	-cipher => 'Cipher::AES',
  	-key    => $key,
  	-header => 'salt'
  );

  # create tied FileHandle
  $fh = Crypt::FileHandle->new($cipher);

  ### treat $fh same as any FileHandle

lib/Crypt/FileHandle.pm  view on Meta::CPAN

=head1 DESCRIPTION

This package creates a tied FileHandle that automatically encrypts or
decrypts data using the provided cipher. The FileHandle returned from
new() can be treated like a normal FileHandle. All encrypting,
decrypting, and buffering is completely transparent to the caller.

=head1 CIPHER METHODS

This package generally supports ciphers compliant with Crypt::CBC,
including CryptX ciphers. The cipher provided to new() must support
at least the methods listed below, but no other methods are utilized
by this package. Refer to Crypt::CBC for more information on these
methods. Even though it is not recommended, a custom home-made cipher
object can be used if it supports these methods.

=over 4

=item start($string)

Initializes the encryption or decryption process according to the
provided string, either 'encrypting' or 'decrypting'.

lib/Crypt/FileHandle.pm  view on Meta::CPAN

=head1 WARNINGS

The sysopen() method is not supported with a tied FileHandle.

The syswrite() and sysread() methods are always used to write to and
read from real handles. This package cannot be used with handles that
do not support these methods, such as opening directly to a Perl
scalar.

If the salt or randomiv header options are not used in the Crypt::CBC
cipher provided to new(), it is the caller's responsibility to
initialize the decryption cipher appropriately to include any
necessary salt or iv values. Otherwise using the same cipher to both
encrypt and decrypt will be unsuccessful since the salt or iv values
are not included in the encrypted file. When the salt header option
is used, the necessary values are included in the resulting encrypted
file, and can also be decrypted with OpenSSL as shown in the example
below.

=over 4

openssl enc -d -aes-256-cbc -in <file> -k <key>

=back

Due to cipher block chaining (CBC), random access is currently not
permitted with this package. It would likely be necessary to read or
write the entire contents of the file, or large portions of it, to
enable random access. For this reason, the following restrictions
exist.

=over 4

SEEK() is not implemented.

Files must only be opened for read OR write access. Files cannot be

lib/Crypt/FileHandle.pm  view on Meta::CPAN

untie() on the tied FileHandle if desired, but this will not destroy
the underlying tied Crypt::FileHandle object. The tied FileHandle
returned from new() can be reused like any other FileHandle after it
has been closed, or properly destroyed by setting the reference to
undef like any other reference. This will properly destroy the tied
FileHandle and the Crypt::FileHandle object since there will no
longer be any references to either.

=head1 SEE ALSO

FileHandle(3), Crypt::CBC(3), CryptX(3), OpenSSL(1)

=head1 AUTHOR

Christopher J. Dunkle

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2004,2016,2018 by Christopher J. Dunkle

This library is free software; you can redistribute it and/or modify

t/Crypt-FileHandle.t  view on Meta::CPAN

#########################

use Test;
BEGIN { plan tests => 47 };
use Crypt::FileHandle;
ok(1);
$|=1;

############################################################

# inline package for testing a Crypt::CBC compatible cipher
# without the dependency of Crypt::CBC
{ 
	package CryptXOR;
	sub new {
		my $class = shift;
		my $self = bless({}, $class);
		# ensure non-zero
		$self->{'xor'} = chr(int(rand()*10) + 1);
		return $self;
	}
	sub start { return 1; }