view release on metacpan or  search on metacpan

lib/Crypt/CBC.pm  view on Meta::CPAN

                    '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 B<-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 B<-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), B<-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 B<-key>.

To skip this hashing operation and specify the key directly, provide
the actual key as a string to B<-key> and specify a key derivation
function of "none" to the B<-pbkdf> argument. Alternatively, you may
pass a true value to the B<-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
B<-pass>/B<-key> argument is ignored and the module will generate a
warning.

The B<-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

lib/Crypt/CBC.pm  view on Meta::CPAN

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. 

=head1 Comparison to Crypt::Mode::CBC

The L<CryptX> modules L<Crypt::Mode::CBC>, L<Crypt::Mode::OFB>,
L<Crypt::Mode::CFB>, and L<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).

=head1 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.

=head1 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).

=head1 BUGS

Please report them.

=head1 AUTHOR

Lincoln Stein, lstein@cshl.org

=head1 LICENSE

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

=head1 SEE ALSO

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

=cut