view release on metacpan or  search on metacpan

lib/Crypt/Nettle/Cipher.pm  view on Meta::CPAN

1;
__END__

=head1 NAME

Crypt::Nettle::Cipher - Perl interface to symmetric encryption and decryption from libnettle

=head1 SYNOPSIS

  use Crypt::Nettle::Cipher;

  my $cleartext = '01234567';
  my $cipher = Crypt::Nettle::Cipher->new('encrypt', 'aes128', '02ds3m#soE2d^7dw', 'ecb');
  $ciphertext = $cipher->process($cleartext);
  printf("encrypted: %s\n", unpack('H*', $ciphertext));

=head1 ABSTRACT

Crypt::Nettle::Cipher provides an object interface to symmetric
encryption and decryption from the nettle C library.  Each
Crypt::Nettle::Cipher object is initialized to do either encryption or
decryption.  If you need both encryption and decryption, make a
separate object for each direction.

=head1 BASIC OPERATIONS

=head2 algos_available()

Get a list of strings that refer to the ciphers this perl module knows
how to coax out of libnettle:

 my @algos = Crypt::Nettle::Cipher::algos_available();

=head2 modes_available()

Get a list of strings that refer to the cipher block modes this perl
module knows how to coax out of libnettle:

 my @modes = Crypt::Nettle::Cipher::modes_available();


=head1 ENCRYPTION CONTEXT CREATION

=head2 new($is_encrypt, $algo, $key, $mode, $iv)

Create a new context for encryption:

  my $encrypt = Crypt::Nettle::Cipher->new('encrypt', 'aes128', '02ds3m#soE2d^7dw', 'ecb');

The parameter $algo must be the name of a symmetric encryption
algorithm supported by libnettle.

Note that $key must match the key_size() for the selected algorithm.

If $is_encrypt is 'decrypt' or 0, the new object will do decryption;
If $is_encrypt is 'encrypt' or 1, it will encrypt.

You can set the $mode of the cipher with 'ecb' (Electronic Code Book),
'cbc' (Cipher Block Chaining), or 'ctr' (Counter).  ECB is the default
because it is simpler to configure, but you probably want CBC or CTR
for security.

If you use CBC or CTR, you'll need to supply an initialization vector
(CBC) or initialization counter (CTR) in the $iv parameter.  $iv
should be the size of block_size().

On error, will return undefined.

Supported encryption algorithms are: aes128, aes192, aes256, arctwo40,
arctwo64, arctwo128, arctwo_gutmann128, arcfour128, camellia128,
camellia192, camellia256, cast128, serpent128, serpent192, serpent256,
twofish128, twofish192, twofish256.

(you can retrieve these programmatically with algos_available()).

Every algorithm supports ECB, but some algorithms don't support some
of the other modes.  I recommend sticking to AES if you can.

=head2 copy()

Copy an existing Crypt::Nettle::Cipher object, including its internal
state:

  my $new_cipher = $cipher->copy();

On error, will return undefined.

=head1 ENCRYPTION CONTEXT OPERATION

=head2 process($data)

Encrypt or decrypt $data with the cipher object:

  $cleartext = 'this is a secret';
  my $encrypt = Crypt::Nettle::Cipher->new('encrypt', 'aes128', '02ds3m#soE2d^7dw');
  $ciphertext = $encrypt->process($cleartext);

or:

  $ciphertext = 'adfasdfasdfasdf';
  my $encrypt = Crypt::Nettle::Cipher->new('decrypt', 'aes128', '02ds3m#soE2d^7dw');
  $cleartext = $encrypt->process($ciphertext);

Note that the length of $data must be an even multiple of
$cipher->block_size().

=head2 process_in_place($data)

Process $data with the cipher object, overwriting $data with the result:

  $text = 'this is a secret';
  $encrypt->process_in_place($text);

Note that the length of $data must be an even multiple of
$cipher->block_size().

=head1 ENCRYPTION DETAILS

=head2 is_encrypt()

Returns non-zero if the object is an encryption cipher, or zero if the
object is set up for decryption.

  printf("Direction: %s\n", ($cipher->is_encrypt() ? 'encrypt' : 'decrypt'));