NAME
Crypt::CBC - Encrypt Data with Cipher Block Chaining Mode
SYNOPSIS
use Crypt::CBC;
$cipher = Crypt::CBC->new( -key => 'my secret key',
-cipher => 'Blowfish',
-salt => 1,
);
$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, and can be made compatible with the newer OpenSSL package by specifying the -salt argument.
To use this module, you will first create a 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 pad and encrypt the final block. 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',
-salt => 1
);
# or (for compatibility with versions prior to 2.13)
$cipher = Crypt::CBC->new( {key => 'my secret key',
cipher => 'Blowfish',
salt => 1}
);
# or (for compatibility with versions prior to 2.0)
$cipher = new Crypt::CBC('my secret key','Blowfish');The new() method creates a new Crypt::CBC object. It accepts a list of -argument => value pairs selected from the following list:
Argument Description
-------- -----------
-key The encryption/decryption key (required)
-cipher The cipher algorithm (defaults to Crypt::DES)
-salt Enables OpenSSL-compatibility. If equal to a value
of "1" then causes a random salt to be generated
and used to derive the encryption key and IV. Other
true values are taken to be the literal salt.
-iv The initialization vector (IV)
-padding The padding method, one of "standard", "space",
"onesandzeroes", or "null". (default "standard")
-literal_key If true, the key provided by "key" is used directly
for encryption/decryption. Otherwise the actual
key used will be a hash of the provided key.
(default false)
-pcbc Whether to use the PCBC chaining algorithm rather than
the standard CBC algorithm (default false).
-add_header Whether to add the salt and IV to the header of the output
cipher text.
-regenerate_key [deprecated; use literal_key instead]
Whether to use a hash of the provided key to generate
the actual encryption key (default true)
-prepend_iv [deprecated; use add_header instead]
Whether to prepend the IV to the beginning of the
encrypted stream (default true)You must provide an encryption/decryption -key, which can be any series of characters of any length. If -regenerate_key is true (the default), then the actual key used is derived from the MD5 hash of the key you provide; otherwise the actual binary bits of the key are used.
The -cipher option specifies which block cipher algorithm to use to encode each section of the message. This argument is optional and will default to the quick-but-not-very-secure DES algorithm unless specified otherwise. You may use any compatible block encryption algorithm that you have installed. Currently, this includes Crypt::DES, Crypt::DES_EDE3, Crypt::IDEA, Crypt::Blowfish, Crypt::CAST5 and Crypt::Rijndael. You may refer to them using their full names ("Crypt::IDEA") or in abbreviated form ("IDEA").
The -salt argument actives an OpenSSL-compatible method of generating the encryption/decryption key and IV. If salt has the value "1", then a random salt is computed (highly recommended). Any other non-false value will be interpreted as the bytes of the actual salt to use. If you provide the salt, it must be exactly 8 bytes in length. It is highly recommended that you use -salt=>1, as this may become the default in future versions of this module.
The initialization vector (IV) is used to start the CBC chaining algorithm. Unless you have also specified a false value for -add_header, the IV should be exactly 8 bytes in length. The IV may be specified manually by passing in a key of -iv as an option to new() or by calling $cipher->set_initialization_vector($iv) before calling $cipher->start(). If no IV is specified, then one will be generated randomly for you. This is backwardly compatible with CBC encrypted streams generated by the older SSLEay library.
The -padding argument controls how the last few bytes of the encrypted stream are dealt with when they not an exact multiple of the cipher block length. The default is "standard", the method specified in PKCS#5.
The -pcbc argument, if true, activates a modified chaining mode known as PCBC. It provides better error propagation characteristics than the default CBC encryption and is required for authenticating to Kerberos4 systems (see RFC 2222).
When generating ciphertext, the IV or salt are inserted into the encrypted data as a 16 byte header. If the -salt option was specified, the header will consist of the string "Salted__" followed by 8 bytes of salt data. Otherwise the header will consist of "RandomIV" followed by 8 bytes of IV data. During decryption, if the ciphertext is found to contain either of these headers, the IV or salt will be retrieved and used during the decryption process, ignoring any values that you might have set manually.
You may disable the generation of the header, by specifying a false value for -add_header. You will then have to provide the correct values of IV or salt when you decrypt the resulting ciphertext.
For compatibility with earlier versions of this module, you can provide new() with a hashref containing key/value pairs. The key names are the same as the arguments described earlier, but without the initial hyphen. You may also call new() with one or two positional arguments, in which case the first argument is taken to be the key and the second to be the optional block cipher algorithm.
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 IV used in encryption and or decryption. The IV 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 IV used in encryption and/or decryption. This function may be useful if the IV is not contained within the ciphertext string being decrypted, or if a particular IV is desired for encryption. Note that the IV must be 8 bytes in length.
iv()
$iv = $cipher->iv();
$cipher->iv($new_iv);As above, but using a single method call.
key()
$key = $cipher->key();
$cipher->key($new_key);Get or set the actual key used for encryption/decryption. When encrypting, the key is not guaranteed to exist until start() is called, and when decrypting, the key is not guaranteed to exist until after the first call to crypt(). The key must match the length required by the underlying block cipher.
salt()
$salt = $cipher->salt();
$cipher->salt($new_salt);Get or set the salt used for deriving the encryption key and IV when in OpenSSL compatibility mode.
passphrase()
$passphrase = $cipher->passphrase();
$cipher->passphrase($new_passphrase);This gets or sets the value of the key passed to new() when literal_key is false.
cipher(), padding(), keysize(), blocksize(), pcbc()
These read-only methods return the identity of the chosen block cipher algorithm, padding method, key and block size of the chosen block cipher, and whether PCBC chaining is in effect.
Padding methods
Use the 'padding' option to change the padding method.
When the last block of plaintext is shorter than the block size, it must be padded. Padding methods include: "standard" (i.e., PKCS#5), "oneandzeroes", "space", and "null".
standard: (default) Binary safe
pads with the number of bytes that should be truncated. So, if
blocksize is 8, then "0A0B0C" will be padded with "05", resulting
in "0A0B0C0505050505". If the final block is a full block of 8
bytes, then a whole block of "0808080808080808" is appended.
oneandzeroes: Binary safe
pads with "80" followed by as many "00" necessary to fill the
block. If the last block is a full block and blocksize is 8, a
block of "8000000000000000" will be appended.
null: text only
pads with as many "00" necessary to fill the block. If the last
block is a full block and blocksize is 8, a block of
"0000000000000000" will be appended.
space: text only
same as "null", but with "20".
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 and oneandzeroes padding are recommended, as both space and null padding can potentially truncate more characters than they should.
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), rfc2898 (PKCS#5)