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