NAME
Crypt::CBC - Encrypt Data with Cipher Block Chaining Mode
SYNOPSIS
use Crypt::CBC;
$cipher = Crypt::CBC->new( { 'key' => 'my secret key',
'cipher' => 'Blowfish',
'iv' => '$KJh#(}q',
'regenerate_key' => 0,
'padding' => 'space',
'prepend_iv' => 0,
);
$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 Crypt::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 = Crypt::CBC->new( { 'key' => 'my secret key',
'cipher' => 'Blowfish',
'iv' => '$KJh#(}q',
'regenerate_key' => 0, # default true
'padding' => 'space',
'prepend_iv' => 0,
);
# or (for compatibility with earlier versions)
$cipher = new Crypt::CBC($key,$algorithm);The new() method creates a new Crypt::CBC object.
You must provide an encryption/decryption key, which can be any series of characters of any length. If regenerate_key is not specified as a false value, the actual key used is derived from the MD5 hash of the key you provide. The cipher is optional and will default to DES unless specified otherwise. It 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 three were available on CPAN, Crypt::DES, Crypt::IDEA, and Crypt::Blowfish. You may refer to them using their full names ("Crypt::IDEA") or in abbreviated form ("IDEA"). An initialization value may be specified, either by passing in a key of 'iv' as an option to new, or by calling $cipher->set_initialization_key($iv) before calling $cipher->start(). The initialization value will be ignored in decryption if the ciphertext is prepended by text which matches the regex /^RandomIV.{8}/, in which case the 8 characters following "RandomIV" will be used as the initialization value. When encrypting, by default the ciphertext will be prepended with "RandomIV<IV>" (16 bytes); to disable this, set prepend_iv to a false value. The padding method can be specified by the optional 'padding' argument to new(). If no padding method is specified, null padding 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 Crypt::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
get_initialization_vector()
$iv = $cipher->get_initialization_vector()This function will return the initialization vector used in encryption and or decryption. This function may be useful to determine the random initialization vector used when encrypting if none is specified in new(). The initialization vector is not guaranteed to be set when encrypting until start() is called, and when decrypting until crypt() is called the first time.
set_initialization_vector()
$cipher->set_initialization_vector('76543210')This function sets the initialization vector used in encryption and or decryption. This function may be useful if the initialization vector is not contained within the ciphertext string being decrypted, or if a particular initialization vector is desired when encrypting. If the initialization vector random initialization vector used when encrypting if none is specified in new(). The initialization vector is not guaranteed to be set when encrypting until start() is called, and when decrypting until crypt() is called the first time.
padding methods
When the last block of the encoded output is less than the block size, it will be padded. Padding can take the form of "space" padding, "null" padding, "oneandzeroes" padding, and a "standard" padding in which the last block is padded with bytes representing the true size of the block. The "padding" option controls what type of padding to use. If none is provided, padding defaults to "standard".
Both the standard and oneandzeroes paddings are binary safe. The space and null paddings are recommended only for text data. Which type of padding you use depends on whether you wish to communicate with an external (non Crypt::CBC library). If this is the case, use whatever padding method is compatible.
You can also pass in a custom padding function. To do this, create a function that takes the arguments:
$padded_block = function($block,$blocksize,$direction);where $block is the current block of data, $blocksize is the size to pad it to, $direction is "e" for encrypting and "d" for decrypting, and $padded_block is the result after padding or depadding.
when encrypting, the function should always return a string of <blocksize> length, and when decrypting, can expect the string coming in to always be that length. See _standard_padding, _space_padding, _null_padding, or _oneandzeroes_padding in the source for examples.
Standard padding is recommended, as both space and null padding can potentially truncate more characters than they should. Future versions of the module may include PKCS5 / PKCS7 padding support.
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
Please report them.
AUTHOR
Lincoln Stein, lstein@cshl.org
This module is distributed under the ARTISTIC LICENSE using the same terms as Perl itself.
SEE ALSO
perl(1), Crypt::DES(3), Crypt::IDEA(3)