1Crypt::CBC(3)         User Contributed Perl Documentation        Crypt::CBC(3)
2
3
4

NAME

6       Crypt::CBC - Encrypt Data with Cipher Block Chaining Mode
7

SYNOPSIS

9         use Crypt::CBC;
10         $cipher = Crypt::CBC->new( -pass   => 'my secret password',
11                                    -cipher => 'Cipher::AES'
12                                   );
13
14         # one shot mode
15         $ciphertext = $cipher->encrypt("This data is hush hush");
16         $plaintext  = $cipher->decrypt($ciphertext);
17
18         # stream mode
19         $cipher->start('encrypting');
20         open(F,"./BIG_FILE");
21         while (read(F,$buffer,1024)) {
22             print $cipher->crypt($buffer);
23         }
24         print $cipher->finish;
25
26         # do-it-yourself mode -- specify key && initialization vector yourself
27         $key    = Crypt::CBC->random_bytes(8);  # assuming a 8-byte block cipher
28         $iv     = Crypt::CBC->random_bytes(8);
29         $cipher = Crypt::CBC->new(-pbkdf       => 'none',
30                                   -header      => 'none',
31                                   -key         => $key,
32                                   -iv          => $iv);
33
34         $ciphertext = $cipher->encrypt("This data is hush hush");
35         $plaintext  = $cipher->decrypt($ciphertext);
36
37         # encrypting via a filehandle (requires Crypt::FileHandle>
38         $fh = Crypt::CBC->filehandle(-pass => 'secret');
39         open $fh,'>','encrypted.txt" or die $!
40         print $fh "This will be encrypted\n";
41         close $fh;
42

DESCRIPTION

44       This module is a Perl-only implementation of the cryptographic cipher
45       block chaining mode (CBC).  In combination with a block cipher such as
46       AES or Blowfish, you can encrypt and decrypt messages of arbitrarily
47       long length.  The encrypted messages are compatible with the encryption
48       format used by the OpenSSL package.
49
50       To use this module, you will first create a Crypt::CBC cipher object
51       with new().  At the time of cipher creation, you specify an encryption
52       key to use and, optionally, a block encryption algorithm.  You will
53       then call the start() method to initialize the encryption or decryption
54       process, crypt() to encrypt or decrypt one or more blocks of data, and
55       lastly finish(), to pad and encrypt the final block.  For your
56       convenience, you can call the encrypt() and decrypt() methods to
57       operate on a whole data value at once.
58
59   new()
60         $cipher = Crypt::CBC->new( -pass   => 'my secret key',
61                                    -cipher => 'Cipher::AES',
62                                  );
63
64         # or (for compatibility with versions prior to 2.0)
65         $cipher = new Crypt::CBC('my secret key' => 'Cipher::AES');
66
67       The new() method creates a new Crypt::CBC object. It accepts a list of
68       -argument => value pairs selected from the following list:
69
70         Argument        Description
71         --------        -----------
72
73         -pass,-key      The encryption/decryption passphrase. These arguments
74                            are interchangeable, but -pass is preferred
75                            ("key" is a misnomer, as it is not the literal
76                            encryption key).
77
78         -cipher         The cipher algorithm (defaults to Crypt::Cipher:AES), or
79                            a previously created cipher object reference. For
80                            convenience, you may omit the initial "Crypt::" part
81                            of the classname and use the basename, e.g. "Blowfish"
82                            instead of "Crypt::Blowfish".
83
84         -keysize        Force the cipher keysize to the indicated number of bytes. This can be used
85                            to set the keysize for variable keylength ciphers such as AES.
86
87         -chain_mode     The block chaining mode to use. Current options are:
88                            'cbc'  -- cipher-block chaining mode [default]
89                            'pcbc' -- plaintext cipher-block chaining mode
90                            'cfb'  -- cipher feedback mode
91                            'ofb'  -- output feedback mode
92                            'ctr'  -- counter mode
93
94         -pbkdf         The passphrase-based key derivation function used to derive
95                           the encryption key and initialization vector from the
96                           provided passphrase. For backward compatibility, Crypt::CBC
97                           will default to "opensslv1", but it is recommended to use
98                           the standard "pbkdf2"algorithm instead. If you wish to interoperate
99                           with OpenSSL, be aware that different versions of the software
100                           support a series of derivation functions.
101
102                           'none'       -- The value provided in -pass/-key is used directly.
103                                             This is the same as passing true to -literal_key.
104                                             You must also manually specify the IV with -iv.
105                                             The key and the IV must match the keylength
106                                             and blocklength of the chosen cipher.
107                           'randomiv'   -- Use insecure key derivation method found
108                                            in prehistoric versions of OpenSSL (dangerous)
109                           'opensslv1'  -- [default] Use the salted MD5 method that was default
110                                            in versions of OpenSSL through v1.0.2.
111                           'opensslv2'  -- [better] Use the salted SHA-256 method that was
112                                            the default in versions of OpenSSL through v1.1.0.
113                           'pbkdf2'     -- [best] Use the PBKDF2 method that was first
114                                            introduced in OpenSSL v1.1.1.
115
116                            More derivation functions may be added in the future. To see the
117                            supported list, use the command
118                              perl -MCrypt::CBC::PBKDF -e 'print join "\n",Crypt::CBC::PBKDF->list'
119
120         -iter           If the 'pbkdf2' key derivation algorithm is used, this specifies the number of
121                            hashing cycles to be applied to the passphrase+salt (longer is more secure).
122                            [default 10,000]
123
124         -hasher         If the 'pbkdf2' key derivation algorithm is chosen, you can use this to provide
125                            an initialized Crypt::PBKDF2::Hash object.
126                            [default HMACSHA2 for OpenSSL compatability]
127
128         -header         What type of header to prepend to the ciphertext. One of
129                           'salt'     -- use OpenSSL-compatible salted header (default)
130                           'randomiv' -- Randomiv-compatible "RandomIV" header
131                           'none'     -- prepend no header at all
132                                         (compatible with prehistoric versions
133                                          of OpenSSL)
134
135         -iv             The initialization vector (IV). If not provided, it will be generated
136                             by the key derivation function.
137
138         -salt           The salt passed to the key derivation function. If not provided, will be
139                             generated randomly (recommended).
140
141         -padding        The padding method, one of "standard" (default),
142                            "space", "oneandzeroes", "rijndael_compat",
143                            "null", or "none" (default "standard").
144
145         -literal_key    [deprected, use -pbkdf=>'none']
146                             If true, the key provided by "-key" or "-pass" is used
147                             directly for encryption/decryption without salting or
148                             hashing. The key must be the right length for the chosen
149                             cipher.
150                             [default false)
151
152         -pcbc           [deprecated, use -chaining_mode=>'pcbc']
153                           Whether to use the PCBC chaining algorithm rather than
154                           the standard CBC algorithm (default false).
155
156         -add_header     [deprecated; use -header instead]
157                          Whether to add the salt and IV to the header of the output
158                           cipher text.
159
160         -regenerate_key [deprecated; use -literal_key instead]
161                         Whether to use a hash of the provided key to generate
162                           the actual encryption key (default true)
163
164         -prepend_iv     [deprecated; use -header instead]
165                         Whether to prepend the IV to the beginning of the
166                           encrypted stream (default true)
167
168       Crypt::CBC requires three pieces of information to do its job. First it
169       needs the name of the block cipher algorithm that will encrypt or
170       decrypt the data in blocks of fixed length known as the cipher's
171       "blocksize." Second, it needs an encryption/decryption key to pass to
172       the block cipher. Third, it needs an initialization vector (IV) that
173       will be used to propagate information from one encrypted block to the
174       next. Both the key and the IV must be exactly the same length as the
175       chosen cipher's blocksize.
176
177       Crypt::CBC can derive the key and the IV from a passphrase that you
178       provide, or can let you specify the true key and IV manually. In
179       addition, you have the option of embedding enough information to
180       regenerate the IV in a short header that is emitted at the start of the
181       encrypted stream, or outputting a headerless encryption stream. In the
182       first case, Crypt::CBC will be able to decrypt the stream given just
183       the original key or passphrase. In the second case, you will have to
184       provide the original IV as well as the key/passphrase.
185
186       The -cipher option specifies which block cipher algorithm to use to
187       encode each section of the message.  This argument is optional and will
188       default to the secure Crypt::Cipher::AES algorithm.  You may use any
189       compatible block encryption algorithm that you have installed.
190       Currently, this includes Crypt::Cipher::AES, Crypt::DES,
191       Crypt::DES_EDE3, Crypt::IDEA, Crypt::Blowfish, Crypt::CAST5 and
192       Crypt::Rijndael. You may refer to them using their full names
193       ("Crypt::IDEA") or in abbreviated form ("IDEA").
194
195       Instead of passing the name of a cipher class, you may pass an already-
196       created block cipher object. This allows you to take advantage of
197       cipher algorithms that have parameterized new() methods, such as
198       Crypt::Eksblowfish:
199
200         my $eksblowfish = Crypt::Eksblowfish->new(8,$salt,$key);
201         my $cbc         = Crypt::CBC->new(-cipher=>$eksblowfish);
202
203       The -pass argument provides a passphrase to use to generate the
204       encryption key or the literal value of the block cipher key. If used in
205       passphrase mode (which is the default), -pass can be any number of
206       characters; the actual key will be derived by passing the passphrase
207       through a series of hashing operations. To take full advantage of a
208       given block cipher, the length of the passphrase should be at least
209       equal to the cipher's blocksize. For backward compatibility, you may
210       also refer to this argument using -key.
211
212       To skip this hashing operation and specify the key directly, provide
213       the actual key as a string to -key and specify a key derivation
214       function of "none" to the -pbkdf argument. Alternatively, you may pass
215       a true value to the -literal_key argument. When you manually specify
216       the key in this way, should choose a key of length exactly equal to the
217       cipher's key length. You will also have to specify an IV equal in
218       length to the cipher's blocksize. These choices imply a header mode of
219       "none."
220
221       If you pass an existing Crypt::* object to new(), then the -pass/-key
222       argument is ignored and the module will generate a warning.
223
224       The -pbkdf argument specifies the algorithm used to derive the true key
225       and IV from the provided passphrase (PBKDF stands for "passphrase-based
226       key derivation function"). Valid values are:
227
228          "opensslv1" -- [default] A fast algorithm that derives the key by
229                         combining a random salt values with the passphrase via
230                         a series of MD5 hashes.
231
232          "opensslv2" -- an improved version that uses SHA-256 rather
233                         than MD5, and has been OpenSSL's default since v1.1.0.
234                         However, it has been deprecated in favor of pbkdf2
235                         since OpenSSL v1.1.1.
236
237          "pbkdf2"    -- a better algorithm implemented in OpenSSL v1.1.1,
238                         described in RFC 2898 L<https://tools.ietf.org/html/rfc2898>
239
240          "none"      -- don't use a derivation function, but treat the passphrase
241                         as the literal key. This is the same as B<-literal_key> true.
242
243          "nosalt"    -- an insecure key derivation method used by prehistoric versions
244                         of OpenSSL, provided for backward compatibility. Don't use.
245
246       "opensslv1" was OpenSSL's default key derivation algorithm through
247       version 1.0.2, but is susceptible to dictionary attacks and is no
248       longer supported. It remains the default for Crypt::CBC in order to
249       avoid breaking compatibility with previously-encrypted messages. Using
250       this option will issue a deprecation warning when initiating
251       encryption. You can suppress the warning by passing a true value to the
252       -nodeprecate option.
253
254       It is recommended to specify the "pbkdf2" key derivation algorithm when
255       compatibility with older versions of Crypt::CBC is not needed. This
256       algorithm is deliberately computationally expensive in order to make
257       dictionary-based attacks harder. As a result, it introduces a slight
258       delay before an encryption or decryption operation starts.
259
260       The -iter argument is used in conjunction with the "pbkdf2" key
261       derivation option. Its value indicates the number of hashing cycles
262       used to derive the key. Larger values are more secure, but impose a
263       longer delay before encryption/decryption starts. The default is 10,000
264       for compatibility with OpenSSL's default.
265
266       The -hasher argument is used in conjunction with the "pbkdf2" key
267       derivation option to pass the reference to an initialized
268       Crypt::PBKDF2::Hash object. If not provided, it defaults to the
269       OpenSSL-compatible hash function HMACSHA2 initialized with its default
270       options (SHA-256 hash).
271
272       The -header argument specifies what type of header, if any, to prepend
273       to the beginning of the encrypted data stream. The header allows
274       Crypt::CBC to regenerate the original IV and correctly decrypt the data
275       without your having to provide the same IV used to encrypt the data.
276       Valid values for the -header are:
277
278        "salt" -- Combine the passphrase with an 8-byte random value to
279                  generate both the block cipher key and the IV from the
280                  provided passphrase. The salt will be appended to the
281                  beginning of the data stream allowing decryption to
282                  regenerate both the key and IV given the correct passphrase.
283                  This method is compatible with current versions of OpenSSL.
284
285        "randomiv" -- Generate the block cipher key from the passphrase, and
286                  choose a random 8-byte value to use as the IV. The IV will
287                  be prepended to the data stream. This method is compatible
288                  with ciphertext produced by versions of the library prior to
289                  2.17, but is incompatible with block ciphers that have non
290                  8-byte block sizes, such as Rijndael. Crypt::CBC will exit
291                  with a fatal error if you try to use this header mode with a
292                  non 8-byte cipher. This header type is NOT secure and NOT
293                  recommended.
294
295        "none"   -- Do not generate a header. To decrypt a stream encrypted
296                  in this way, you will have to provide the true key and IV
297                  manually.
298
299       The "salt" header is now the default as of Crypt::CBC version 2.17. In
300       all earlier versions "randomiv" was the default.
301
302       When using a "salt" header, you may specify your own value of the salt,
303       by passing the desired 8-byte character string to the -salt argument.
304       Otherwise, the module will generate a random salt for you. Crypt::CBC
305       will generate a fatal error if you specify a salt value that isn't
306       exactly 8 bytes long. For backward compatibility reasons, passing a
307       value of "1" will generate a random salt, the same as if no -salt
308       argument was provided.
309
310       The -padding argument controls how the last few bytes of the encrypted
311       stream are dealt with when they not an exact multiple of the cipher
312       block length. The default is "standard", the method specified in
313       PKCS#5.
314
315       The -chaining_mode argument will select among several different block
316       chaining modes. Values are:
317
318         'cbc'  -- [default] traditional Cipher-Block Chaining mode. It has
319                     the property that if one block in the ciphertext message
320                     is damaged, only that block and the next one will be
321                     rendered un-decryptable.
322
323         'pcbc' -- Plaintext Cipher-Block Chaining mode. This has the property
324                     that one damaged ciphertext block will render the
325                     remainder of the message unreadable
326
327         'cfb'  -- Cipher Feedback Mode. In this mode, both encryption and decryption
328                     are performed using the block cipher's "encrypt" algorithm.
329                     The error propagation behaviour is similar to CBC's.
330
331         'ofb'  -- Output Feedback Mode. Similar to CFB, the block cipher's encrypt
332                     algorithm is used for both encryption and decryption. If one bit
333                     of the plaintext or ciphertext message is damaged, the damage is
334                     confined to a single block of the corresponding ciphertext or
335                     plaintext, and error correction algorithms can be used to reconstruct
336                     the damaged part.
337
338          'ctr' -- Counter Mode. This mode uses a one-time "nonce" instead of
339                     an IV. The nonce is incremented by one for each block of
340                     plain or ciphertext, encrypted using the chosen
341                     algorithm, and then applied to the block of text. If one
342                     bit of the input text is damaged, it only affects 1 bit
343                     of the output text. To use CTR mode you will need to
344                     install the Perl Math::Int128 module. This chaining method
345                     is roughly half the speed of the others due to integer
346                     arithmetic.
347
348       Passing a -pcbc argument of true will have the same effect as
349       -chaining_mode=>'pcbc', and is included for backward compatibility.
350       [deprecated].
351
352       For more information on chaining modes, see
353       <http://www.crypto-it.net/eng/theory/modes-of-block-ciphers.html>.
354
355       The -keysize argument can be used to force the cipher's keysize. This
356       is useful for several of the newer algorithms, including AES, ARIA,
357       Blowfish, and CAMELLIA. If -keysize is not specified, then Crypt::CBC
358       will use the value returned by the cipher's max_keylength() method.
359       Note that versions of CBC::Crypt prior to 2.36 could also allow you to
360       set the blocksie, but this was never supported by any ciphers and has
361       been removed.
362
363       For compatibility with earlier versions of this module, you can provide
364       new() with a hashref containing key/value pairs. The key names are the
365       same as the arguments described earlier, but without the initial
366       hyphen.  You may also call new() with one or two positional arguments,
367       in which case the first argument is taken to be the key and the second
368       to be the optional block cipher algorithm.
369
370   start()
371          $cipher->start('encrypting');
372          $cipher->start('decrypting');
373
374       The start() method prepares the cipher for a series of encryption or
375       decryption steps, resetting the internal state of the cipher if
376       necessary.  You must provide a string indicating whether you wish to
377       encrypt or decrypt.  "E" or any word that begins with an "e" indicates
378       encryption.  "D" or any word that begins with a "d" indicates
379       decryption.
380
381   crypt()
382          $ciphertext = $cipher->crypt($plaintext);
383
384       After calling start(), you should call crypt() as many times as
385       necessary to encrypt the desired data.
386
387   finish()
388          $ciphertext = $cipher->finish();
389
390       The CBC algorithm must buffer data blocks internally until they are
391       even multiples of the encryption algorithm's blocksize (typically 8
392       bytes).  After the last call to crypt() you should call finish().  This
393       flushes the internal buffer and returns any leftover ciphertext.
394
395       In a typical application you will read the plaintext from a file or
396       input stream and write the result to standard output in a loop that
397       might look like this:
398
399         $cipher = new Crypt::CBC('hey jude!');
400         $cipher->start('encrypting');
401         print $cipher->crypt($_) while <>;
402         print $cipher->finish();
403
404   encrypt()
405         $ciphertext = $cipher->encrypt($plaintext)
406
407       This convenience function runs the entire sequence of start(), crypt()
408       and finish() for you, processing the provided plaintext and returning
409       the corresponding ciphertext.
410
411   decrypt()
412         $plaintext = $cipher->decrypt($ciphertext)
413
414       This convenience function runs the entire sequence of start(), crypt()
415       and finish() for you, processing the provided ciphertext and returning
416       the corresponding plaintext.
417
418   encrypt_hex(), decrypt_hex()
419         $ciphertext = $cipher->encrypt_hex($plaintext)
420         $plaintext  = $cipher->decrypt_hex($ciphertext)
421
422       These are convenience functions that operate on ciphertext in a
423       hexadecimal representation.  encrypt_hex($plaintext) is exactly
424       equivalent to unpack('H*',encrypt($plaintext)).  These functions can be
425       useful if, for example, you wish to place the encrypted in an email
426       message.
427
428   filehandle()
429       This method returns a filehandle for transparent encryption or
430       decryption using Christopher Dunkle's excellent Crypt::FileHandle
431       module. This module must be installed in order to use this method.
432
433       filehandle() can be called as a class method using the same arguments
434       as new():
435
436         $fh = Crypt::CBC->filehandle(-cipher=> 'Blowfish',
437                                      -pass  => "You'll never guess");
438
439       or on a previously-created Crypt::CBC object:
440
441          $cbc = Crypt::CBC->new(-cipher=> 'Blowfish',
442                                 -pass  => "You'll never guess");
443          $fh  = $cbc->filehandle;
444
445       The filehandle can then be opened using the familiar open() syntax.
446       Printing to a filehandle opened for writing will encrypt the data.
447       Filehandles opened for input will be decrypted.
448
449       Here is an example:
450
451         # transparent encryption
452         open $fh,'>','encrypted.out' or die $!;
453         print $fh "You won't be able to read me!\n";
454         close $fh;
455
456         # transparent decryption
457         open $fh,'<','encrypted.out' or die $!;
458         while (<$fh>) { print $_ }
459         close $fh;
460
461   get_initialization_vector()
462         $iv = $cipher->get_initialization_vector()
463
464       This function will return the IV used in encryption and or decryption.
465       The IV is not guaranteed to be set when encrypting until start() is
466       called, and when decrypting until crypt() is called the first time.
467       Unless the IV was manually specified in the new() call, the IV will
468       change with every complete encryption operation.
469
470   set_initialization_vector()
471         $cipher->set_initialization_vector('76543210')
472
473       This function sets the IV used in encryption and/or decryption. This
474       function may be useful if the IV is not contained within the ciphertext
475       string being decrypted, or if a particular IV is desired for
476       encryption.  Note that the IV must match the chosen cipher's blocksize
477       bytes in length.
478
479   iv()
480         $iv = $cipher->iv();
481         $cipher->iv($new_iv);
482
483       As above, but using a single method call.
484
485   key()
486         $key = $cipher->key();
487         $cipher->key($new_key);
488
489       Get or set the block cipher key used for encryption/decryption.  When
490       encrypting, the key is not guaranteed to exist until start() is called,
491       and when decrypting, the key is not guaranteed to exist until after the
492       first call to crypt(). The key must match the length required by the
493       underlying block cipher.
494
495       When salted headers are used, the block cipher key will change after
496       each complete sequence of encryption operations.
497
498   salt()
499         $salt = $cipher->salt();
500         $cipher->salt($new_salt);
501
502       Get or set the salt used for deriving the encryption key and IV when in
503       OpenSSL compatibility mode.
504
505   passphrase()
506         $passphrase = $cipher->passphrase();
507         $cipher->passphrase($new_passphrase);
508
509       This gets or sets the value of the passphrase passed to new() when
510       literal_key is false.
511
512   $data = random_bytes($numbytes)
513       Return $numbytes worth of random data. On systems that support the
514       "/dev/urandom" device file, this data will be read from the device.
515       Otherwise, it will be generated by repeated calls to the Perl rand()
516       function.
517
518   cipher(), pbkdf(), padding(), keysize(), blocksize(), chain_mode()
519       These read-only methods return the identity of the chosen block cipher
520       algorithm, the key derivation function (e.g. "opensslv1"), padding
521       method, key and block size of the chosen block cipher, and what
522       chaining mode ("cbc", "ofb" ,etc) is being used.
523
524   Padding methods
525       Use the 'padding' option to change the padding method.
526
527       When the last block of plaintext is shorter than the block size, it
528       must be padded. Padding methods include: "standard" (i.e., PKCS#5),
529       "oneandzeroes", "space", "rijndael_compat", "null", and "none".
530
531          standard: (default) Binary safe
532             pads with the number of bytes that should be truncated. So, if
533             blocksize is 8, then "0A0B0C" will be padded with "05", resulting
534             in "0A0B0C0505050505". If the final block is a full block of 8
535             bytes, then a whole block of "0808080808080808" is appended.
536
537          oneandzeroes: Binary safe
538             pads with "80" followed by as many "00" necessary to fill the
539             block. If the last block is a full block and blocksize is 8, a
540             block of "8000000000000000" will be appended.
541
542          rijndael_compat: Binary safe, with caveats
543             similar to oneandzeroes, except that no padding is performed if
544             the last block is a full block. This is provided for
545             compatibility with Crypt::Rijndael's buit-in MODE_CBC.
546             Note that Crypt::Rijndael's implementation of CBC only
547             works with messages that are even multiples of 16 bytes.
548
549          null: text only
550             pads with as many "00" necessary to fill the block. If the last
551             block is a full block and blocksize is 8, a block of
552             "0000000000000000" will be appended.
553
554          space: text only
555             same as "null", but with "20".
556
557          none:
558             no padding added. Useful for special-purpose applications where
559             you wish to add custom padding to the message.
560
561       Both the standard and oneandzeroes paddings are binary safe.  The space
562       and null paddings are recommended only for text data.  Which type of
563       padding you use depends on whether you wish to communicate with an
564       external (non Crypt::CBC library).  If this is the case, use whatever
565       padding method is compatible.
566
567       You can also pass in a custom padding function.  To do this, create a
568       function that takes the arguments:
569
570          $padded_block = function($block,$blocksize,$direction);
571
572       where $block is the current block of data, $blocksize is the size to
573       pad it to, $direction is "e" for encrypting and "d" for decrypting, and
574       $padded_block is the result after padding or depadding.
575
576       When encrypting, the function should always return a string of
577       <blocksize> length, and when decrypting, can expect the string coming
578       in to always be that length. See _standard_padding(), _space_padding(),
579       _null_padding(), or _oneandzeroes_padding() in the source for examples.
580
581       Standard and oneandzeroes padding are recommended, as both space and
582       null padding can potentially truncate more characters than they should.
583

Comparison to Crypt::Mode::CBC

585       The CryptX modules Crypt::Mode::CBC, Crypt::Mode::OFB,
586       Crypt::Mode::CFB, and Crypt::Mode::CTR provide fast implementations of
587       the respective cipherblock chaining modes (roughly 5x the speed of
588       Crypt::CBC). Crypt::CBC was designed to encrypt and decrypt messages in
589       a manner compatible with OpenSSL's "enc" function. Hence it handles the
590       derivation of the key and IV from a passphrase using the same
591       conventions as OpenSSL, and it writes out an OpenSSL-compatible header
592       in the encrypted message in a manner that allows the key and IV to be
593       regenerated during decryption.
594
595       In contrast, the CryptX modules do not automatically derive the key and
596       IV from a passphrase or write out an encrypted header. You will need to
597       derive and store the key and IV by other means (e.g. with CryptX's
598       Crypt::KeyDerivation module, or with Crypt::PBKDF2).
599

EXAMPLES

601       Three examples, aes.pl, des.pl and idea.pl can be found in the eg/
602       subdirectory of the Crypt-CBC distribution.  These implement command-
603       line DES and IDEA encryption algorithms using default parameters, and
604       should be compatible with recent versions of OpenSSL. Note that aes.pl
605       uses the "pbkdf2" key derivation function to generate its keys. The
606       other two were distributed with pre-PBKDF2 versions of Crypt::CBC, and
607       use the older "opensslv1" algorithm.
608

LIMITATIONS

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

BUGS

615       Please report them.
616

AUTHOR

618       Lincoln Stein, lstein@cshl.org
619
620       This module is distributed under the ARTISTIC LICENSE v2 using the same
621       terms as Perl itself.
622

SEE ALSO

624       perl(1), CryptX, Crypt::FileHandle, Crypt::Cipher::AES,
625       Crypt::Blowfish, Crypt::CAST5, Crypt::DES, Crypt::IDEA, Crypt::Rijndael
626
627
628
629perl v5.34.0                      2022-03-02                     Crypt::CBC(3)
Impressum