view release on metacpan or  search on metacpan

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

=item B<twofish128> 

The Twofish algorithm with a 128 bit key.

=item B<arcfour> 

An algorithm which is 100% compatible with RSA Inc.'s RC4
algorithm.  Note that this is a stream cipher and must be used
very carefully to avoid a couple of weaknesses.

=back

=item mode

This is a string specifying one of the following
encryption/decryption modes:

=over 8

=item B<stream> 

only available for stream ciphers

=item B<ecb> 

doesn't use an IV, encrypts each block independently

=item B<cbc> 

the current ciphertext block is encryption of current plaintext block 
xor-ed with last ciphertext block

=item B<cfb> 

the current ciphertext block is the current plaintext
block xor-ed with the current keystream block, which is the encryption
of the last ciphertext block

=item B<ofb> 

the current ciphertext block is the current plaintext
block xor-ed with the current keystream block, which is the encryption
of the last keystream block

=back

If no mode is specified then B<cbc> is selected for block ciphers, and
B<stream> for stream ciphers.

=item padding

When the last block of plaintext is shorter than the block size, it must be 
padded before encryption. Padding should permit a safe unpadding after 
decryption. Crypt::GCrypt currently supports two methods:

=over 8

=item B<standard>

This is also known as PKCS#5 padding, as it's binary safe. The string is padded
with the number of bytes that should be truncated. It's compatible with Crypt::CBC.

=item B<null>

Only for text strings. The block will be padded with null bytes (00). If the last 
block is a full block and blocksize is 8, a block of "0000000000000000" will be 
appended.

=item B<none>

By setting the padding method to "none", Crypt::GCrypt will only accept a multiple
of blklen as input for L</"encrypt()">.

=back

=item secure

If this option is set to a true value, all data associated with this cipher will be 
put into non-swappable storage, if possible.

=item enable_sync

Enable the CFB sync operation.

=back

Once you've got your cipher object the following methods are available:

=head2 start()

   $cipher->start('encrypting');
   $cipher->start('decrypting');

This method must be called before any call to setkey() or setiv(). It prepares
the cipher for encryption or decryption, resetting the internal state.

=head2 setkey()

   $cipher->setkey('my secret key');

Encryption and decryption operations will use this key until a different
one is set. If your key is shorter than the cipher's keylen (see the
C<keylen> method) it will be zero-padded, if it is longer it will be
truncated.

=head2 setiv()

   $cipher->setiv('my iv');

Set the initialisation vector for the next encrypt/decrypt operation.
If I<IV> is missing a "standard" IV of all zero is used. The same IV is set in
newly created cipher objects.

=head2 encrypt()

   $ciphertext = $cipher->encrypt($plaintext);

This method encrypts I<$plaintext> with I<$cipher>, returning the
corresponding ciphertext. The output is buffered; this means that
you'll only get multiples of $cipher's block size and that at the 
end you'll have to call L</"finish()">.

=head2 finish()

    $ciphertext .= $cipher->finish;
    
    $plaintext .= $cipher->finish;

The CBC algorithm must buffer data blocks internally until there are even 
multiples of the encryption algorithm's blocksize (typically 8 or 16 bytes).
After the last call to encrypt() or decrypt() you should call finish() to flush 
the internal buffer and return any leftover data. This method will also take care
of padding/unpadding of data (see the L</padding> option above).

=head2 decrypt()

   $plaintext = $cipher->decrypt($ciphertext);

The counterpart to encrypt, decrypt takes a I<$ciphertext> and produces the
original plaintext (given that the right key was used, of course).
The output is buffered; this means that you'll only get multiples of $cipher's 
block size and that at the end you'll have to call L</"finish()">.

=head2 keylen()

   print "Key length is " . $cipher->keylen();

Returns the number of bytes of keying material this cipher needs.

=head2 blklen()

   print "Block size is " . $cipher->blklen();

As their name implies, block ciphers operate on blocks of data. This
method returns the size of this blocks in bytes for this particular
cipher. For stream ciphers C<1> is returned, since this implementation
does not feed less than a byte into the cipher.

=head2 sync()

   $cipher->sync();

Apply the CFB sync operation.

=head1 MESSAGE DIGESTS

=head2 digest_algo_available()

Determines whether a given digest algorithm is available in the local
gcrypt installation:

   if (Crypt::GCrypt::digest_algo_available('sha256')) {
      # do stuff with sha256
   }

=head2 new()

In order to create a message digest, you first have to build a
Crypt::GCrypt object:

  my $digest = Crypt::GCrypt->new(
    type => 'digest',
    algorithm => 'sha256',
  );

The I<type> argument must be "digest" and I<algorithm> is required too. See below
for a description of available algorithms and other initialization parameters:

=over 4