Provided by: libcrypt-ecb-perl_2.21-1_all bug

NAME

       Crypt::ECB - Use block ciphers using ECB mode

SYNOPSIS

       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);

DESCRIPTION

       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.

METHODS

   new()
         $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.

   cipher(), module(), key()
         $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.

   keysize(), blocksize()
         $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.

   padding()
         $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.

   start(), mode(), crypt(), finish()
         $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.

   encrypt(), decrypt(), encrypt_hex(), decrypt_hex()
         $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.

FUNCTIONS

       For convenience en- or decrypting can also be done by calling ordinary functions. The
       functions are: encrypt(), decrypt(), encrypt_hex(), decrypt_hex().

   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().

BUGS

       None that I know of. Please report if you find any.

TODO

       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.

LICENSE

       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".

AUTHOR

       Christoph Appel (see ECB.pm for email address)

SEE ALSO

       perl(1), Crypt::DES(3), Crypt::IDEA(3), Crypt::CBC(3)