Provided by: libcrypt-cbc-perl_2.33-1_all bug

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)