/ 
Crypt-GCrypt-1.14
River stage zero No dependents
/ Crypt::GCrypt

NAME

Crypt::GCrypt - Perl interface to the GNU Cryptographic library

SYNOPSIS

use Crypt::GCrypt;

$cipher = Crypt::GCrypt->new(
  type => 'cipher',
  algorithm => 'aes', 
  mode => 'cbc'
);
$cipher->start('encrypting');

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

$ciphertext = $cipher->encrypt('plaintext');
$ciphertext .= $cipher->finish;

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

ABSTRACT

Crypt::GCrypt provides an object interface to the C libgcrypt library. It currently supports symmetric encryption/decryption, while asymmetric cryptography is being worked on.

SYMMETRIC CRYPTOGRAPHY

new()

In order to encrypt/decrypt your data using a symmetric cipher you first have to build a Crypt::GCrypt object:

$cipher = Crypt::GCrypt->new(
  type => 'cipher',
  algorithm => 'aes', 
  mode => 'cbc'
);

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

algorithm

This may be one of the following:

3des

Triple-DES with 3 Keys as EDE. The key size of this algorithm is 168 but you have to pass 192 bits because the most significant bits of each byte are ignored.

aes

AES (Rijndael) with a 128 bit key.

aes192

AES (Rijndael) with a 192 bit key.

aes256

AES (Rijndael) with a 256 bit key.

blowfish

The blowfish algorithm. The current implementation allows only for a key size of 128 bits (and thus is not compatible with Crypt::Blowfish).

cast5

CAST128-5 block cipher algorithm. The key size is 128 bits.

des

Standard DES with a 56 bit key. You need to pass 64 bit but the high bits of each byte are ignored. Note, that this is a weak algorithm which can be broken in reasonable time using a brute force approach.

twofish

The Twofish algorithm with a 256 bit key.

twofish128

The Twofish algorithm with a 128 bit key.

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.

mode

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

stream

only available for stream ciphers

ecb

doesn't use an IV, encrypts each block independently

cbc

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

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

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

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

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:

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.

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.

secure

All data associated with this cipher will be put into non-swappable storage, if possible.

enable_sync

Enable the CFB sync operation.

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

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.

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 keylen method) it will be zero-padded, if it is longer it will be truncated.

setiv()

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

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

encrypt()

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

This method encrypts $plaintext with $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 "finish()".

finish()

$ciphertext .= $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() you should call finish() to flush the internal buffer and return any leftover ciphertext. The internal buffer will be padded before encryption (see the "padding" option above).

decrypt()

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

The counterpart to encrypt, decrypt takes a $ciphertext and produces the original plaintext (given that the right key was used, of course).

keylen()

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

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

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 1 is returned, since this implementation does not feed less than a byte into the cipher.

sync()

$cipher->sync();

Apply the CFB sync operation.

BUGS AND FEEDBACK

There are no known bugs. You are very welcome to write mail to the author (aar@cpan.org) with your contributions, comments, suggestions, bug reports or complaints.

AUTHOR

Alessandro Ranellucci <aar@cpan.org>

COPYRIGHT AND LICENSE

Copyright (c) 2005 Alessandro Ranellucci. Crypt::GCrypt is free software, you may redistribute it and/or modify it under the same terms as Perl itself.

ACKNOWLEDGEMENTS

This module was initially inspired by the GCrypt.pm bindings made by Robert Bihlmeyer in 2002. Thanks to users who give feedback (see Changelog).

DISCLAIMER

This software is provided by the copyright holders and contributors ``as is'' and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the regents or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.