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                                   -key         => $key,
31                                   -iv          => $iv);
32
33         $ciphertext = $cipher->encrypt("This data is hush hush");
34         $plaintext  = $cipher->decrypt($ciphertext);
35
36         # encrypting via a filehandle (requires Crypt::FileHandle>
37         $fh = Crypt::CBC->filehandle(-pass => 'secret');
38         open $fh,'>','encrypted.txt" or die $!
39         print $fh "This will be encrypted\n";
40         close $fh;
41

DESCRIPTION

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

Comparison to Crypt::Mode::CBC

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

EXAMPLES

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

LIMITATIONS

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

BUGS

614       Please report them.
615

AUTHOR

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

SEE ALSO

623       perl(1), CryptX, Crypt::FileHandle, Crypt::Cipher::AES,
624       Crypt::Blowfish, Crypt::CAST5, Crypt::DES, Crypt::IDEA, Crypt::Rijndael
625
626
627
628perl v5.34.0                      2021-07-22                     Crypt::CBC(3)
Impressum