On Apache/2.0.61 (Unix) PHP/4.4.7 mod_ssl/2.0.61 OpenSSL/0.9.7e mod_fastcgi/2.4.2 DAV/2 SVN/1.4.2
Under GNU General Public License
2009-01-06 15:06 @38.103.63.57 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
CBC(3pm) User Contributed Perl Documentation CBC(3pm)
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, # default true
'padding' => 'space',
'prepend_iv' => 0,
'pcbc' => 1 #default 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 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',
'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. You may use any compatible block encryption algorithm
that you have installed. Currently, this includes Crypt::DES, Crypt::DES_EDE3,
Crypt::IDEA, Crypt::Blowfish, and Crypt::Rijndael. You may refer to them using their full
names ("Crypt::IDEA") or in abbreviated form ("IDEA").
An initialization vector 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 IV 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 IV. 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 'padding' option. If no padding method
is specified, PKCS#5 ("standard") padding is assumed.
Instead of the default cipher-block-chaining mode a modified algorithm PCBC can be used.
It provides better error propagation characteristics than CBC encryption. To switch it on
you have to set 'pcbc' to a true value. The PCBC mode is part of the des library and
required e.g. in Kerberos4 authentication procedures as mentioned in RFC 2222 and other
documents.
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 indi-
cating 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 cipher-
text.
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 representa-
tion. 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. This function may
be useful to determine the random IV used when encrypting if none is specified in new().
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 use-
ful if the IV is not contained within the ciphertext string being decrypted, or if a par-
ticular IV is desired for encryption. If not set, a random IV will be generated. The IV
is not guaranteed to be set when encrypting until start() is called, and when decrypting
until crypt() is called the first time.
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 _stan-
dard_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 AT 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)
perl v5.8.4 2006-11-21 CBC(3pm)
Generated by $Id: phpMan.php,v 4.49 2006/02/26 13:18:18 chedong Exp $ Author: Che Dong
On Apache/2.0.61 (Unix) PHP/4.4.7 mod_ssl/2.0.61 OpenSSL/0.9.7e mod_fastcgi/2.4.2 DAV/2 SVN/1.4.2
Under GNU General Public License
2009-01-06 15:06 @38.103.63.57 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)