NAME¶
Crypt::CBC - Encrypt Data with Cipher Block Chaining Mode
SYNOPSIS¶
use Crypt::CBC;
$cipher = Crypt::CBC->new( -key => 'my secret key',
-cipher => 'Blowfish'
);
$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;
# do-it-yourself mode -- specify key, initialization vector yourself
$key = Crypt::CBC->random_bytes(8); # assuming a 8-byte block cipher
$iv = Crypt::CBC->random_bytes(8);
$cipher = Crypt::CBC->new(-literal_key => 1,
-key => $key,
-iv => $iv,
-header => 'none');
$ciphertext = $cipher->encrypt("This data is hush hush");
$plaintext = $cipher->decrypt($ciphertext);
# RANDOMIV-compatible mode
$cipher = Crypt::CBC->new(-key => 'Super Secret!'
-header => 'randomiv');
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 the
OpenSSL
package.
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',
);
# or (for compatibility with versions prior to 2.13)
$cipher = Crypt::CBC->new( {
key => 'my secret key',
cipher => 'Blowfish'
}
);
# 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), or
a preexisting cipher object.
-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)
-header What type of header to prepend to ciphertext. One of
'salt' -- use OpenSSL-compatible salted header
'randomiv' -- Randomiv-compatible "RandomIV" header
'none' -- prepend no header at all
-padding The padding method, one of "standard" (default),
"space", "oneandzeroes", "rijndael_compat",
"null", or "none" (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).
-keysize Force the cipher keysize to the indicated number of bytes.
-blocksize Force the cipher blocksize to the indicated number of bytes.
-insecure_legacy_decrypt
Allow decryption of data encrypted using the "RandomIV" header
produced by pre-2.17 versions of Crypt::CBC.
-add_header [deprecated; use -header instread]
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)
Crypt::CBC requires three pieces of information to do its job. First it needs
the name of the block cipher algorithm that will encrypt or decrypt the data
in blocks of fixed length known as the cipher's "blocksize." Second,
it needs an encryption/decryption key to pass to the block cipher. Third, it
needs an initialization vector (IV) that will be used to propagate information
from one encrypted block to the next. Both the key and the IV must be exactly
the same length as the chosen cipher's blocksize.
Crypt::CBC can derive the key and the IV from a passphrase that you provide, or
can let you specify the true key and IV manually. In addition, you have the
option of embedding enough information to regenerate the IV in a short header
that is emitted at the start of the encrypted stream, or outputting a
headerless encryption stream. In the first case, Crypt::CBC will be able to
decrypt the stream given just the original key or passphrase. In the second
case, you will have to provide the original IV as well as the key/passphrase.
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").
Instead of passing the name of a cipher class, you may pass an already-created
block cipher object. This allows you to take advantage of cipher algorithms
that have parameterized
new() methods, such as Crypt::Eksblowfish:
my $eksblowfish = Crypt::Eksblowfish->new(8,$salt,$key);
my $cbc = Crypt::CBC->new(-cipher=>$eksblowfish);
The
-key argument provides either a passphrase to use to generate the
encryption key, or the literal value of the block cipher key. If used in
passphrase mode (which is the default),
-key can be any number of
characters; the actual key will be derived by passing the passphrase through a
series of MD5 hash operations. To take full advantage of a given block cipher,
the length of the passphrase should be at least equal to the cipher's
blocksize. To skip this hashing operation and specify the key directly, pass a
true value to the
-literal_key option. In this case, you should choose
a key of length exactly equal to the cipher's key length. You should also
specify the IV yourself and a -header mode of 'none'.
If you pass an existing Crypt::* object to
new(), then the -key argument
is ignored and the module will generate a warning.
The
-header argument specifies what type of header, if any, to prepend to
the beginning of the encrypted data stream. The header allows Crypt::CBC to
regenerate the original IV and correctly decrypt the data without your having
to provide the same IV used to encrypt the data. Valid values for the
-header are:
"salt" -- Combine the passphrase with an 8-byte random value to
generate both the block cipher key and the IV from the
provided passphrase. The salt will be appended to the
beginning of the data stream allowing decryption to
regenerate both the key and IV given the correct passphrase.
This method is compatible with current versions of OpenSSL.
"randomiv" -- Generate the block cipher key from the passphrase, and
choose a random 8-byte value to use as the IV. The IV will
be prepended to the data stream. This method is compatible
with ciphertext produced by versions of the library prior to
2.17, but is incompatible with block ciphers that have non
8-byte block sizes, such as Rijndael. Crypt::CBC will exit
with a fatal error if you try to use this header mode with a
non 8-byte cipher.
"none" -- Do not generate a header. To decrypt a stream encrypted
in this way, you will have to provide the original IV
manually.
The "salt" header is now the default as of Crypt::CBC version 2.17.
In all earlier versions "randomiv" was the default.
When using a "salt" header, you may specify your own value of the
salt, by passing the desired 8-byte salt to the
-salt argument.
Otherwise, the module will generate a random salt for you. Crypt::CBC will
generate a fatal error if you specify a salt value that isn't exactly 8 bytes
long. For backward compatibility reasons, passing a value of "1"
will generate a random salt, the same as if no
-salt argument was
provided.
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).
The
-keysize and
-blocksize arguments can be used to force the
cipher's keysize and/or blocksize. This is only currently useful for the
Crypt::Blowfish module, which accepts a variable length keysize. If -keysize
is not specified, then Crypt::CBC will use the maximum length Blowfish key
size of 56 bytes (448 bits). The Openssl library defaults to 16 byte Blowfish
key sizes, so for compatibility with Openssl you may wish to set
-keysize=>16. There are currently no Crypt::* modules that have variable
block sizes, but an option to change the block size is provided just in case.
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.
IMPORTANT NOTE: Versions of this module prior to 2.17 were incorrectly
using 8-byte IVs when generating the "randomiv" style of header,
even when the chosen cipher's blocksize was greater than 8 bytes. This
primarily affects the Rijndael algorithm. Such encrypted data streams were
not secure. From versions 2.17 onward, Crypt::CBC will refuse to
encrypt or decrypt using the "randomiv" header and non-8 byte block
ciphers. To decrypt legacy data encrypted with earlier versions of the module,
you can override the check using the
-insecure_legacy_decrypt option.
It is not possible to override encryption. Please use the default
"salt" header style, or no headers at all.
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 internally 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 in an email message.
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. Unless the IV
was manually specified in the
new() call, the IV will change with every
complete encryption operation.
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 match the chosen cipher's blocksize 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 block cipher 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.
When salted headers are used, the block cipher key will change after each
complete sequence of encryption operations.
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.
$data = random_bytes($numbytes)¶
Return $numbytes worth of random data. On systems that support the
"/dev/urandom" device file, this data will be read from the device.
Otherwise, it will be generated by repeated calls to the Perl
rand()
function.
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", "rijndael_compat",
"null", and "none".
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.
rijndael_compat: Binary safe, with caveats
similar to oneandzeroes, except that no padding is performed if
the last block is a full block. This is provided for
compatibility with Crypt::Rijndael only and can only be used
with messages that are a multiple of the Rijndael blocksize
of 16 bytes.
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".
none:
no padding added. Useful for special-purpose applications where
you wish to add custom padding to the message.
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)