Crypt::ECB - Use block ciphers using ECB mode
Use Crypt::ECB OO style
use Crypt::ECB;
$ecb = Crypt::ECB->new;
$ecb->cipher('Blowfish');
$ecb->key('some_key');
$enc = $ecb->encrypt("Some data.");
print $ecb->decrypt($enc);
or use the function style interface
use Crypt::ECB qw(encrypt decrypt encrypt_hex decrypt_hex);
$ciphertext = encrypt($key, 'Blowfish', "Some data");
$plaintext = decrypt($key, 'Blowfish', $ciphertext);
$hexcode = encrypt_hex($key, $cipher, $plaintext);
$plain = decrypt_hex($key, $cipher, $hexcode);
This module is a Perl-only implementation of the ECB mode. In combination with a
block cipher such as Blowfish, DES, IDEA or Rijndael, you can encrypt and
decrypt messages of arbitrarily long length. Though for security reasons other
modes than ECB such as CBC should be preferred. See textbooks on cryptography
if you want to know why.
The functionality of the module can be accessed via OO methods or via standard
function calls. Remember that some block cipher module like for example
Crypt::Blowfish has to be installed. The syntax of Crypt::ECB follows that of
Crypt::CBC.
$ecb = Crypt::ECB->new(
-cipher => $cipher,
-key => $key,
-padding => 'oneandzeroes',
-keysize => 8, # use to override cipher's default
-blocksize => 8, # use to override cipher's default
);
or
$ecb = Crypt::ECB->new({
cipher => $cipher,
key => $key,
padding => 'oneandzeroes',
keysize => 8, # use to override cipher's default
blocksize => 8, # use to override cipher's default
});
or (only key and cipher can be passed this way)
$ecb = Crypt::ECB->new($key, 'Blowfish');
$ecb = Crypt::ECB->new($key); # DES is assumed
The following options are recognized: cipher, key, keysize, blocksize and
padding. Options can be passed like in Crypt::CBC. All options can be read and
also be changed via corresponding methods afterwards.
If called without parameters you have to call at least
key() and
cipher() before you can
start crypting.
$ecb = Crypt::ECB->new;
$ecb->cipher('Blowfish');
$ecb->key('some_key');
print $ecb->cipher; # Blowfish
print $ecb->module; # Crypt::Blowfish
print $ecb->key; # some_key
or
my $ecb = Crypt::ECB->new;
my $xtea = Crypt::XTEA->new($key, 32, little_endian => 1);
$ecb->cipher($xtea);
cipher() sets the block cipher to be used. It tries to load
the corresponding module. If an error occurs, it dies with some errmessage.
Otherwise it returns the cipher name. Free packages available for Perl are for
example Blowfish, DES, IDEA or Rijndael. If called without parameter it just
returns the name of the cipher.
cipher() also accepts a pre-existing object from a suitable
block cipher module. This is useful e.g. for cipher modules such as
Crypt::XTEA which need additional parameters.
module() returns the perl package containing the block
cipher which has been specified using
cipher().
key() sets the key if given a parameter. It always returns
the key. Note that most block ciphers require keys of definite length. For
example DES expects an eight byte key.
$ecb = Crypt::ECB->new;
$ecb->cipher('Blowfish');
$keysize = $ecb->keysize;
$blocksize = $ecb->blocksize;
These methods can be used to retrieve keysize and blocksize as reported from the
block cipher chosen.
They can be used as well to override the values that are reported from the
cipher module. Of course that doesn't make sense unless the block cipher used
supports the new values. E.g. Crypt::Rijndael works with 16, 24 and 32 byte
keys.
$ecb->padding('oneandzeroes');
my $custom_padding = sub { ... };
$ecb->padding($custom_padding);
padding() sets the way how data is padded up to a multiple
of the cipher's blocksize. Until now the following methods are implemented:
'standard', 'zeroes', 'oneandzeroes', 'rijndael_compat', 'space', 'null' and
'none'. If the padding style is not set explicitly, 'standard' is used.
'standard' (default) (binary safe)
The PKCS#5 / PKCS#7 method (RFC 5652): Pads with the number of bytes
that should be truncated. So, if blocksize is 8, then "0A0B0C" will
be padded with five "05"s, resulting in "0A0B0C0505050505". If the
message is already a multiple of the cipher's block size, then another
whole block is appended.
'zeroes' (binary safe)
This is a variant of the standard method. It pads with null bytes, except
the last byte equals the number of padding bytes. So, if the blocksize is
8, then "0A0B0C" will be padded to "0A0B0C0000000005". If the message is
already a multiple of the cipher's block size, then another whole block
is appended.
'oneandzeroes' (binary safe)
Pads with "80" followed by as many "00"s as necessary to fill the block,
in other words a 1 bit followed by 0s. If the message already is a
multiple of the cipher's block size, then another whole block is
appended.
'rijndael_compat' (binary safe)
Similar to oneandzeroes, except that no padding is performed if the
message already is already a multiple of the cipher's block size. This is
provided for compatibility with Crypt::Rijndael.
'null'
Pads with as many null bytes as necessary to fill the block. If the
message is already a multiple of the cipher's block size, then another
whole block is appended.
ATTENTION: Can truncate more characters than it should (if the original
message ended with one or more null bytes).
'space'
Pads with as many space characters as necessary to fill the block.
If the message is already a multiple of the cipher's block size, unlike
the other methods NO block is appended.
ATTENTION: Can truncate more characters than it should (if the original
message ended with one or more space characters).
'none'
No padding added by Crypt::ECB. You then have to take care of correct
padding and truncating yourself.
You can also use a custom padding function. To do this, create a function that
is called like:
$padded_block = function($block, $blocksize, $direction);
and tell Crypt::ECB to use your function:
$ecb->padding(\&function);
$block is the current block of data, $blocksize is the size to pad to,
$direction is "e" for encrypting and "d" for decrypting,
and $padded_block is the result after padding or truncation. When encrypting,
the function should always return a string of $blocksize length, and when
decrypting, it can expect the string coming in to be of that length.
$ecb->start('encrypt');
$enc .= $ecb->crypt($_) foreach (@lines);
$enc .= $ecb->finish;
$ecb->start('decrypt');
print $ecb->mode;
start() sets the crypting mode, checks if all required
variables like key and cipher are set, then initializes the block cipher
specified. Allowed parameters are any words starting either with 'e' or 'd'.
The method returns the current mode.
mode() is called without parameters and just returns the
current mode.
crypt() processes the data given as argument. If called
without argument $_ is processed. The method returns the processed data.
Cipher and key have to be set in order to be able to process data. If some of
these are missing or
start() was not called before, the
method dies.
After having sent all data to be processed to
crypt() you
have to call
finish() in order to flush data that's left
in the buffer.
$enc = $ecb->encrypt($data);
print $ecb->decrypt($enc);
$hexenc = $ecb->encrypt_hex($data);
print $ecb->decrypt_hex($hexenc);
encrypt() and
decrypt() are
convenience methods which call
start(),
crypt() and
finish() for you.
encrypt_hex() and
decrypt_hex() are
convenience functions that operate on ciphertext in a hexadecimal
representation. These functions can be useful if, for example, you wish to
place the encrypted information into an e-mail message, web page or URL.
For convenience en- or decrypting can also be done by calling ordinary
functions. The functions are:
encrypt(),
decrypt() ,
encrypt_hex(),
decrypt_hex().
use Crypt::ECB qw(encrypt decrypt encrypt_hex decrypt_hex);
$ciphertext = encrypt($key, $cipher, $plaintext, $padstyle);
$plaintext = decrypt($key, $cipher, $ciphertext, $padstyle);
$ciphertext = encrypt_hex($key, $cipher, $plaintext, $padstyle);
$plaintext = decrypt_hex($key, $cipher, $ciphertext, $padstyle);
encrypt() and
decrypt() process the
provided text and return either the corresponding ciphertext (encrypt) or
plaintext (decrypt). Data and padstyle are optional. If the padding style is
omitted, 'standard' is assumed. If data is omitted, $_ is used.
encrypt_hex() and
decrypt_hex()
operate on ciphertext in a hexadecimal representation, just like the methods
with the same name, see above. Otherwise usage is the same as for
encrypt() and
decrypt().
None that I know of. Please report if you find any.
Implement 'random' padding, see
http://www.di-mgt.com.au/cryptopad.html.
A taint check on the key like Crypt::CBC does could be added.
Crypt-ECB is Copyright (C) 2000, 2005, 2008, 2016 by Christoph Appel.
This module is distributed using the same terms as Perl itself. It is free
software; you can redistribute it and/or modify it under the terms of either:
a) the GNU General Public License as published by the Free Software Foundation;
either version 1, or (at your option) any later version, or
b) the "Artistic License".
Christoph Appel (see ECB.pm for email address)
perl(1),
Crypt::DES(3),
Crypt::IDEA(3),
Crypt::CBC(3)