view release on metacpan or  search on metacpan

README  view on Meta::CPAN

                        'randomiv' -- Randomiv-compatible "RandomIV" header
                        'none'     -- prepend no header at all 
                                      (compatible with prehistoric versions
                                       of OpenSSL)

      -iv             The initialization vector (IV). If not provided, it will be generated
                          by the key derivation function.

      -salt           The salt passed to the key derivation function. If not provided, will be
                          generated randomly (recommended).

      -padding        The padding method, one of "standard" (default),
                         "space", "oneandzeroes", "rijndael_compat",
                         "null", or "none" (default "standard").

      -literal_key    [deprected, use -pbkdf=>'none']
                          If true, the key provided by "-key" or "-pass" is used 
                          directly for encryption/decryption without salting or
                          hashing. The key must be the right length for the chosen
                          cipher. 
                          [default false)

      -pcbc           [deprecated, use -chaining_mode=>'pcbc']
                        Whether to use the PCBC chaining algorithm rather than
                        the standard CBC algorithm (default false).

      -add_header     [deprecated; use -header instead]
                       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 -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 secure Crypt::Cipher::AES algorithm. You may use any
    compatible block encryption algorithm that you have installed.
    Currently, this includes Crypt::Cipher::AES, 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 -pass argument provides 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), -pass can be any number of
    characters; the actual key will be derived by passing the passphrase
    through a series of hashing 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. For backward compatibility, you may
    also refer to this argument using -key.

    To skip this hashing operation and specify the key directly, provide the
    actual key as a string to -key and specify a key derivation function of
    "none" to the -pbkdf argument. Alternatively, you may pass a true value
    to the -literal_key argument. When you manually specify the key in this
    way, should choose a key of length exactly equal to the cipher's key
    length. You will also have to specify an IV equal in length to the
    cipher's blocksize. These choices imply a header mode of "none."

    If you pass an existing Crypt::* object to new(), then the -pass/-key
    argument is ignored and the module will generate a warning.

    The -pbkdf argument specifies the algorithm used to derive the true key
    and IV from the provided passphrase (PBKDF stands for "passphrase-based
    key derivation function"). Valid values are:

       "opensslv1" -- [default] A fast algorithm that derives the key by 
                      combining a random salt values with the passphrase via
                      a series of MD5 hashes.

       "opensslv2" -- an improved version that uses SHA-256 rather
                      than MD5, and has been OpenSSL's default since v1.1.0. 
                      However, it has been deprecated in favor of pbkdf2 
                      since OpenSSL v1.1.1.

       "pbkdf2"    -- a better algorithm implemented in OpenSSL v1.1.1,
                      described in RFC 2898 L<https://tools.ietf.org/html/rfc2898>

       "none"      -- don't use a derivation function, but treat the passphrase
                      as the literal key. This is the same as B<-literal_key> true.

       "nosalt"    -- an insecure key derivation method used by prehistoric versions
                      of OpenSSL, provided for backward compatibility. Don't use.

    "opensslv1" was OpenSSL's default key derivation algorithm through
    version 1.0.2, but is susceptible to dictionary attacks and is no longer
    supported. It remains the default for Crypt::CBC in order to avoid
    breaking compatibility with previously-encrypted messages. Using this
    option will issue a deprecation warning when initiating encryption. You
    can suppress the warning by passing a true value to the -nodeprecate
    option.

README  view on Meta::CPAN

    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.

Comparison to Crypt::Mode::CBC
    The CryptX modules Crypt::Mode::CBC, Crypt::Mode::OFB, Crypt::Mode::CFB,
    and Crypt::Mode::CTR provide fast implementations of the respective
    cipherblock chaining modes (roughly 5x the speed of Crypt::CBC).
    Crypt::CBC was designed to encrypt and decrypt messages in a manner
    compatible with OpenSSL's "enc" function. Hence it handles the
    derivation of the key and IV from a passphrase using the same
    conventions as OpenSSL, and it writes out an OpenSSL-compatible header
    in the encrypted message in a manner that allows the key and IV to be
    regenerated during decryption.

    In contrast, the CryptX modules do not automatically derive the key and
    IV from a passphrase or write out an encrypted header. You will need to
    derive and store the key and IV by other means (e.g. with CryptX's
    Crypt::KeyDerivation module, or with Crypt::PBKDF2).

EXAMPLES
    Three examples, aes.pl, 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 using default parameters, and should
    be compatible with recent versions of OpenSSL. Note that aes.pl uses the
    "pbkdf2" key derivation function to generate its keys. The other two
    were distributed with pre-PBKDF2 versions of Crypt::CBC, and use the
    older "opensslv1" algorithm.

LIMITATIONS
    The encryption and decryption process is about a tenth the speed of the
    equivalent OpenSSL tool and about a fifth of the Crypt::Mode::CBC module
    (both which use compiled C).

BUGS
    Please report them.

AUTHOR
    Lincoln Stein, lstein@cshl.org

LICENSE
    This module is distributed under the ARTISTIC LICENSE v2 using the same
    terms as Perl itself.

SEE ALSO
    perl(1), CryptX, Crypt::FileHandle, Crypt::Cipher::AES, Crypt::Blowfish,
    Crypt::CAST5, Crypt::DES, Crypt::IDEA, Crypt::Rijndael