NAME
Crypt::CBC - Encrypt Data with Cipher Block Chaining Mode
SYNOPSIS
use Crypt::CBC;
$cipher = new CBC('my secret key','IDEA');
$ciphertext = $cipher->encrypt("This data is hush hush");
$plaintext = $cipher->decrypt($ciphertext);
$cipher->start('encrypting');
open(F,"./BIG_FILE");
while (read(F,$buffer,1024)) {
print $cipher->crypt($buffer);
}
print $cipher->finish;DESCRIPTION
This module is a Perl-only implementation of the cryptographic cipher block chaining mode (CBC). In combination with a block cipher such as DES or IDEA, you can encrypt and decrypt messages of arbitrarily long length. The encrypted messages are compatible with the encryption format used by SSLeay.
To use this module, you will first create a new CBC cipher object with new(). At the time of cipher creation, you specify an encryption key to use and, optionally, a block encryption algorithm. You will then call the start() method to initialize the encryption or decryption process, crypt() to encrypt or decrypt one or more blocks of data, and lastly finish(), to flush the encryption stream. For your convenience, you can call the encrypt() and decrypt() methods to operate on a whole data value at once.
new()
$cipher = new CBC($key,$algorithm);The new() method creates a new CBC object. Note that even though CBC is defined in the Crypt:: namespace, it occupies the CBC package, not the Crypt::CBC package. This is arguably wrong, but is consistent with the way that Crypt::DES and Crypt::IDEA do it.
You must provide an encryption/decryption key, which can be any series of characters of any length. Internally, the actual key used is derived from the MD5 hash of the key you provide. The optional second argument is the block encryption algorithm to use, specified as a package name. You may use any block encryption algorithm that you have installed. At the time this was written, only two were available on CPAN, Crypt::DES and Crypt::IDEA. You may refer to them using their full names ("Crypt::IDEA") or in abbreviated form ("IDEA".) If no algorithm is provided, DES is assumed.
start()
$cipher->start('encrypting');
$cipher->start('decrypting');The start() method prepares the cipher for a series of encryption or decryption steps, resetting the internal state of the cipher if necessary. You must provide a string indicating whether you wish to encrypt or decrypt. "E" or any word that begins with an "e" indicates encryption. "D" or any word that begins with a "d" indicates decryption.
crypt()
$ciphertext = $cipher->crypt($plaintext);After calling start(), you should call crypt() as many times as necessary to encrypt the desired data.
finish()
$ciphertext = $cipher->finish();The CBC algorithm must buffer data blocks inernally until they are even multiples of the encryption algorithm's blocksize (typically 8 bytes). After the last call to crypt() you should call finish(). This flushes the internal buffer and returns any leftover ciphertext.
In a typical application you will read the plaintext from a file or input stream and write the result to standard output in a loop that might look like this:
$cipher = new CBC('hey jude!');
$cipher->start('encrypting');
print $cipher->crypt($_) while <>;
print $cipher->finish();encrypt()
$ciphertext = $cipher->encrypt($plaintext)This convenience function runs the entire sequence of start(), crypt() and finish() for you, processing the provided plaintext and returning the corresponding ciphertext.
decrypt()
$plaintext = $cipher->decrypt($ciphertext)This convenience function runs the entire sequence of start(), crypt() and finish() for you, processing the provided ciphertext and returning the corresponding plaintext.
encrypt_hex(), decrypt_hex()
$ciphertext = $cipher->encrypt_hex($plaintext)
$plaintext = $cipher->decrypt_hex($ciphertext)These are convenience functions that operate on ciphertext in a hexadecimal representation. encrypt_hex($plaintext) is exactly equivalent to unpack('H*',encrypt($plaintext)). These functions can be useful if, for example, you wish to place the encrypted information into an e-mail message, Web page or URL.
EXAMPLES
Two examples, des.pl and idea.pl can be found in the eg/ subdirectory of the Crypt-CBC distribution. These implement command-line DES and IDEA encryption algorithms.
LIMITATIONS
The encryption and decryption process is about a tenth the speed of the equivalent SSLeay programs (compiled C). This could be improved by implementing this module in C. It may also be worthwhile to optimize the DES and IDEA block algorithms further.
BUGS
None that I know of.
AUTHOR
Lincoln Stein, lstein@cshl.org
SEE ALSO
perl(1), Crypt::DES(3), Crypt::IDEA(3)