{ "content": [ { "type": "text", "text": "# Crypt::CBC (perldoc)\n\n## NAME\n\nCrypt::CBC - Encrypt Data with Cipher Block Chaining Mode\n\n## SYNOPSIS\n\nuse Crypt::CBC;\n$cipher = Crypt::CBC->new( -pass => 'my secret password',\n-cipher => 'Cipher::AES'\n);\n# one shot mode\n$ciphertext = $cipher->encrypt(\"This data is hush hush\");\n$plaintext = $cipher->decrypt($ciphertext);\n# stream mode\n$cipher->start('encrypting');\nopen(F,\"./BIGFILE\");\nwhile (read(F,$buffer,1024)) {\nprint $cipher->crypt($buffer);\n}\nprint $cipher->finish;\n# do-it-yourself mode -- specify key && initialization vector yourself\n$key = Crypt::CBC->randombytes(8); # assuming a 8-byte block cipher\n$iv = Crypt::CBC->randombytes(8);\n$cipher = Crypt::CBC->new(-pbkdf => 'none',\n-key => $key,\n-iv => $iv);\n$ciphertext = $cipher->encrypt(\"This data is hush hush\");\n$plaintext = $cipher->decrypt($ciphertext);\n# encrypting via a filehandle (requires Crypt::FileHandle>\n$fh = Crypt::CBC->filehandle(-pass => 'secret');\nopen $fh,'>','encrypted.txt\" or die $!\nprint $fh \"This will be encrypted\\n\";\nclose $fh;\n\n## DESCRIPTION\n\nThis module is a Perl-only implementation of the cryptographic cipher block chaining mode (CBC).\nIn combination with a block cipher such as AES or Blowfish, you can encrypt and decrypt messages\nof arbitrarily long length. The encrypted messages are compatible with the encryption format\nused by the OpenSSL package.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (6 subsections)\n- **Comparison to Crypt::Mode::CBC**\n- **EXAMPLES**\n- **LIMITATIONS**\n- **BUGS**\n- **AUTHOR**\n- **SEE ALSO** (1 subsections)\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Crypt::CBC", "section": "", "mode": "perldoc", "summary": "Crypt::CBC - Encrypt Data with Cipher Block Chaining Mode", "synopsis": "use Crypt::CBC;\n$cipher = Crypt::CBC->new( -pass => 'my secret password',\n-cipher => 'Cipher::AES'\n);\n# one shot mode\n$ciphertext = $cipher->encrypt(\"This data is hush hush\");\n$plaintext = $cipher->decrypt($ciphertext);\n# stream mode\n$cipher->start('encrypting');\nopen(F,\"./BIGFILE\");\nwhile (read(F,$buffer,1024)) {\nprint $cipher->crypt($buffer);\n}\nprint $cipher->finish;\n# do-it-yourself mode -- specify key && initialization vector yourself\n$key = Crypt::CBC->randombytes(8); # assuming a 8-byte block cipher\n$iv = Crypt::CBC->randombytes(8);\n$cipher = Crypt::CBC->new(-pbkdf => 'none',\n-key => $key,\n-iv => $iv);\n$ciphertext = $cipher->encrypt(\"This data is hush hush\");\n$plaintext = $cipher->decrypt($ciphertext);\n# encrypting via a filehandle (requires Crypt::FileHandle>\n$fh = Crypt::CBC->filehandle(-pass => 'secret');\nopen $fh,'>','encrypted.txt\" or die $!\nprint $fh \"This will be encrypted\\n\";\nclose $fh;", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [ { "flag": "", "long": null, "arg": null, "description": "Whether to add the salt and IV to the header of the output cipher text." }, { "flag": "", "long": null, "arg": null, "description": "Whether to use a hash of the provided key to generate the actual encryption key (default true)" }, { "flag": "", "long": null, "arg": null, "description": "Whether to prepend the IV to the beginning of the encrypted stream (default true) Crypt::CBC requires three pieces of information to do its job. First it needs the name of the block cipher algorithm that will encrypt or decrypt the data in blocks of fixed length known as the cipher's \"blocksize.\" Second, it needs an encryption/decryption key to pass to the block cipher. Third, it needs an initialization vector (IV) that will be used to propagate information from one encrypted block to the next. Both the key and the IV must be exactly the same length as the chosen cipher's blocksize. Crypt::CBC can derive the key and the IV from a passphrase that you provide, or can let you specify the true key and IV manually. In addition, you have the option of embedding enough information to regenerate the IV in a short header that is emitted at the start of the encrypted stream, or outputting a headerless encryption stream. In the first case, Crypt::CBC will be able to decrypt the stream given just the original key or passphrase. In the second case, you will have to provide the original IV as well as the key/passphrase. The -cipher option specifies which block cipher algorithm to use to encode each section of the message. This argument is optional and will default to the secure Crypt::Cipher::AES algorithm. You may use any compatible block encryption algorithm that you have installed. Currently, this includes Crypt::Cipher::AES, Crypt::DES, Crypt::DESEDE3, Crypt::IDEA, Crypt::Blowfish, Crypt::CAST5 and Crypt::Rijndael. You may refer to them using their full names (\"Crypt::IDEA\") or in abbreviated form (\"IDEA\"). Instead of passing the name of a cipher class, you may pass an already-created block cipher object. This allows you to take advantage of cipher algorithms that have parameterized new() methods, such as Crypt::Eksblowfish: my $eksblowfish = Crypt::Eksblowfish->new(8,$salt,$key); my $cbc = Crypt::CBC->new(-cipher=>$eksblowfish); The -pass argument provides a passphrase to use to generate the encryption key or the literal value of the block cipher key. If used in passphrase mode (which is the default), -pass can be any number of characters; the actual key will be derived by passing the passphrase through a series of hashing operations. To take full advantage of a given block cipher, the length of the passphrase should be at least equal to the cipher's blocksize. For backward compatibility, you may also refer to this argument using -key. To skip this hashing operation and specify the key directly, provide the actual key as a string to -key and specify a key derivation function of \"none\" to the -pbkdf argument. Alternatively, you may pass a true value to the -literalkey argument. When you manually specify the key in this way, should choose a key of length exactly equal to the cipher's key length. You will also have to specify an IV equal in length to the cipher's blocksize. These choices imply a header mode of \"none.\" If you pass an existing Crypt::* object to new(), then the -pass/-key argument is ignored and the module will generate a warning. The -pbkdf argument specifies the algorithm used to derive the true key and IV from the provided passphrase (PBKDF stands for \"passphrase-based key derivation function\"). Valid values are: \"opensslv1\" -- [default] A fast algorithm that derives the key by combining a random salt values with the passphrase via a series of MD5 hashes. \"opensslv2\" -- an improved version that uses SHA-256 rather than MD5, and has been OpenSSL's default since v1.1.0. However, it has been deprecated in favor of pbkdf2 since OpenSSL v1.1.1. \"pbkdf2\" -- a better algorithm implemented in OpenSSL v1.1.1, described in RFC 2898 L \"none\" -- don't use a derivation function, but treat the passphrase as the literal key. This is the same as B<-literalkey> true. \"nosalt\" -- an insecure key derivation method used by prehistoric versions of OpenSSL, provided for backward compatibility. Don't use. \"opensslv1\" was OpenSSL's default key derivation algorithm through version 1.0.2, but is susceptible to dictionary attacks and is no longer supported. It remains the default for Crypt::CBC in order to avoid breaking compatibility with previously-encrypted messages. Using this option will issue a deprecation warning when initiating encryption. You can suppress the warning by passing a true value to the -nodeprecate option. It is recommended to specify the \"pbkdf2\" key derivation algorithm when compatibility with older versions of Crypt::CBC is not needed. This algorithm is deliberately computationally expensive in order to make dictionary-based attacks harder. As a result, it introduces a slight delay before an encryption or decryption operation starts. The -iter argument is used in conjunction with the \"pbkdf2\" key derivation option. Its value indicates the number of hashing cycles used to derive the key. Larger values are more secure, but impose a longer delay before encryption/decryption starts. The default is 10,000 for compatibility with OpenSSL's default. The -hasher argument is used in conjunction with the \"pbkdf2\" key derivation option to pass the reference to an initialized Crypt::PBKDF2::Hash object. If not provided, it defaults to the OpenSSL-compatible hash function HMACSHA2 initialized with its default options (SHA-256 hash). The -header argument specifies what type of header, if any, to prepend to the beginning of the encrypted data stream. The header allows Crypt::CBC to regenerate the original IV and correctly decrypt the data without your having to provide the same IV used to encrypt the data. Valid values for the -header are: \"salt\" -- Combine the passphrase with an 8-byte random value to generate both the block cipher key and the IV from the provided passphrase. The salt will be appended to the beginning of the data stream allowing decryption to regenerate both the key and IV given the correct passphrase. This method is compatible with current versions of OpenSSL. \"randomiv\" -- Generate the block cipher key from the passphrase, and choose a random 8-byte value to use as the IV. The IV will be prepended to the data stream. This method is compatible with ciphertext produced by versions of the library prior to 2.17, but is incompatible with block ciphers that have non 8-byte block sizes, such as Rijndael. Crypt::CBC will exit with a fatal error if you try to use this header mode with a non 8-byte cipher. This header type is NOT secure and NOT recommended. \"none\" -- Do not generate a header. To decrypt a stream encrypted in this way, you will have to provide the true key and IV manually. The \"salt\" header is now the default as of Crypt::CBC version 2.17. In all earlier versions \"randomiv\" was the default. When using a \"salt\" header, you may specify your own value of the salt, by passing the desired 8-byte character string to the -salt argument. Otherwise, the module will generate a random salt for you. Crypt::CBC will generate a fatal error if you specify a salt value that isn't exactly 8 bytes long. For backward compatibility reasons, passing a value of \"1\" will generate a random salt, the same as if no -salt argument was provided. The -padding argument controls how the last few bytes of the encrypted stream are dealt with when they not an exact multiple of the cipher block length. The default is \"standard\", the method specified in PKCS#5. The -chainingmode argument will select among several different block chaining modes. Values are: 'cbc' -- [default] traditional Cipher-Block Chaining mode. It has the property that if one block in the ciphertext message is damaged, only that block and the next one will be rendered un-decryptable. 'pcbc' -- Plaintext Cipher-Block Chaining mode. This has the property that one damaged ciphertext block will render the remainder of the message unreadable 'cfb' -- Cipher Feedback Mode. In this mode, both encryption and decryption are performed using the block cipher's \"encrypt\" algorithm. The error propagation behaviour is similar to CBC's. 'ofb' -- Output Feedback Mode. Similar to CFB, the block cipher's encrypt algorithm is used for both encryption and decryption. If one bit of the plaintext or ciphertext message is damaged, the damage is confined to a single block of the corresponding ciphertext or plaintext, and error correction algorithms can be used to reconstruct the damaged part. 'ctr' -- Counter Mode. This mode uses a one-time \"nonce\" instead of an IV. The nonce is incremented by one for each block of plain or ciphertext, encrypted using the chosen algorithm, and then applied to the block of text. If one bit of the input text is damaged, it only affects 1 bit of the output text. To use CTR mode you will need to install the Perl Math::Int128 module. This chaining method is roughly half the speed of the others due to integer arithmetic. Passing a -pcbc argument of true will have the same effect as -chainingmode=>'pcbc', and is included for backward compatibility. [deprecated]. For more information on chaining modes, see . The -keysize argument can be used to force the cipher's keysize. This is useful for several of the newer algorithms, including AES, ARIA, Blowfish, and CAMELLIA. If -keysize is not specified, then Crypt::CBC will use the value returned by the cipher's maxkeylength() method. Note that versions of CBC::Crypt prior to 2.36 could also allow you to set the blocksie, but this was never supported by any ciphers and has been removed. For compatibility with earlier versions of this module, you can provide new() with a hashref containing key/value pairs. The key names are the same as the arguments described earlier, but without the initial hyphen. You may also call new() with one or two positional arguments, in which case the first argument is taken to be the key and the second to be the optional block cipher algorithm. start() $cipher->start('encrypting'); $cipher->start('decrypting'); The start() method prepares the cipher for a series of encryption or decryption steps, resetting the internal state of the cipher if necessary. You must provide a string indicating whether you wish to encrypt or decrypt. \"E\" or any word that begins with an \"e\" indicates encryption. \"D\" or any word that begins with a \"d\" indicates decryption. crypt() $ciphertext = $cipher->crypt($plaintext); After calling start(), you should call crypt() as many times as necessary to encrypt the desired data. finish() $ciphertext = $cipher->finish(); The CBC algorithm must buffer data blocks internally until they are even multiples of the encryption algorithm's blocksize (typically 8 bytes). After the last call to crypt() you should call finish(). This flushes the internal buffer and returns any leftover ciphertext. In a typical application you will read the plaintext from a file or input stream and write the result to standard output in a loop that might look like this: $cipher = new Crypt::CBC('hey jude!'); $cipher->start('encrypting'); print $cipher->crypt($) while <>; print $cipher->finish(); encrypt() $ciphertext = $cipher->encrypt($plaintext) This convenience function runs the entire sequence of start(), crypt() and finish() for you, processing the provided plaintext and returning the corresponding ciphertext. decrypt() $plaintext = $cipher->decrypt($ciphertext) This convenience function runs the entire sequence of start(), crypt() and finish() for you, processing the provided ciphertext and returning the corresponding plaintext. encrypthex(), decrypthex() $ciphertext = $cipher->encrypthex($plaintext) $plaintext = $cipher->decrypthex($ciphertext) These are convenience functions that operate on ciphertext in a hexadecimal representation." } ], "examples": [ "Three examples, aes.pl, des.pl and idea.pl can be found in the eg/ subdirectory of the Crypt-CBC", "distribution. These implement command-line DES and IDEA encryption algorithms using default", "parameters, and should be compatible with recent versions of OpenSSL. Note that aes.pl uses the", "\"pbkdf2\" key derivation function to generate its keys. The other two were distributed with", "pre-PBKDF2 versions of Crypt::CBC, and use the older \"opensslv1\" algorithm." ], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 33, "subsections": [] }, { "name": "DESCRIPTION", "lines": 109, "subsections": [ { "name": "-add_header [deprecated; use -header instead]", "lines": 3 }, { "name": "-regenerate_key [deprecated; use -literal_key instead]", "lines": 3 }, { "name": "-prepend_iv [deprecated; use -header instead]", "lines": 226 }, { "name": "encrypt_hex", "lines": 7 }, { "name": "filehandle", "lines": 81 }, { "name": "Padding methods", "lines": 57 } ] }, { "name": "Comparison to Crypt::Mode::CBC", "lines": 12, "subsections": [] }, { "name": "EXAMPLES", "lines": 6, "subsections": [] }, { "name": "LIMITATIONS", "lines": 3, "subsections": [] }, { "name": "BUGS", "lines": 2, "subsections": [] }, { "name": "AUTHOR", "lines": 4, "subsections": [] }, { "name": "SEE ALSO", "lines": 1, "subsections": [ { "name": "perl", "lines": 2 } ] } ], "sections": { "NAME": { "content": "Crypt::CBC - Encrypt Data with Cipher Block Chaining Mode\n", "subsections": [] }, "SYNOPSIS": { "content": "use Crypt::CBC;\n$cipher = Crypt::CBC->new( -pass => 'my secret password',\n-cipher => 'Cipher::AES'\n);\n\n# one shot mode\n$ciphertext = $cipher->encrypt(\"This data is hush hush\");\n$plaintext = $cipher->decrypt($ciphertext);\n\n# stream mode\n$cipher->start('encrypting');\nopen(F,\"./BIGFILE\");\nwhile (read(F,$buffer,1024)) {\nprint $cipher->crypt($buffer);\n}\nprint $cipher->finish;\n\n# do-it-yourself mode -- specify key && initialization vector yourself\n$key = Crypt::CBC->randombytes(8); # assuming a 8-byte block cipher\n$iv = Crypt::CBC->randombytes(8);\n$cipher = Crypt::CBC->new(-pbkdf => 'none',\n-key => $key,\n-iv => $iv);\n\n$ciphertext = $cipher->encrypt(\"This data is hush hush\");\n$plaintext = $cipher->decrypt($ciphertext);\n\n# encrypting via a filehandle (requires Crypt::FileHandle>\n$fh = Crypt::CBC->filehandle(-pass => 'secret');\nopen $fh,'>','encrypted.txt\" or die $!\nprint $fh \"This will be encrypted\\n\";\nclose $fh;\n", "subsections": [] }, "DESCRIPTION": { "content": "This module is a Perl-only implementation of the cryptographic cipher block chaining mode (CBC).\nIn combination with a block cipher such as AES or Blowfish, you can encrypt and decrypt messages\nof arbitrarily long length. The encrypted messages are compatible with the encryption format\nused by the OpenSSL package.\n\nTo use this module, you will first create a Crypt::CBC cipher object with new(). At the time of\ncipher creation, you specify an encryption key to use and, optionally, a block encryption\nalgorithm. You will then call the start() method to initialize the encryption or decryption\nprocess, crypt() to encrypt or decrypt one or more blocks of data, and lastly finish(), to pad\nand encrypt the final block. For your convenience, you can call the encrypt() and decrypt()\nmethods to operate on a whole data value at once.\n\nnew()\n$cipher = Crypt::CBC->new( -pass => 'my secret key',\n-cipher => 'Cipher::AES',\n);\n\n# or (for compatibility with versions prior to 2.0)\n$cipher = new Crypt::CBC('my secret key' => 'Cipher::AES');\n\nThe new() method creates a new Crypt::CBC object. It accepts a list of -argument => value pairs\nselected from the following list:\n\nArgument Description\n-------- -----------\n\n-pass,-key The encryption/decryption passphrase. These arguments\nare interchangeable, but -pass is preferred\n(\"key\" is a misnomer, as it is not the literal\nencryption key).\n\n-cipher The cipher algorithm (defaults to Crypt::Cipher:AES), or\na previously created cipher object reference. For\nconvenience, you may omit the initial \"Crypt::\" part\nof the classname and use the basename, e.g. \"Blowfish\"\ninstead of \"Crypt::Blowfish\".\n\n-keysize Force the cipher keysize to the indicated number of bytes. This can be used\nto set the keysize for variable keylength ciphers such as AES.\n\n-chainmode The block chaining mode to use. Current options are:\n'cbc' -- cipher-block chaining mode [default]\n'pcbc' -- plaintext cipher-block chaining mode\n'cfb' -- cipher feedback mode\n'ofb' -- output feedback mode\n'ctr' -- counter mode\n\n-pbkdf The passphrase-based key derivation function used to derive\nthe encryption key and initialization vector from the\nprovided passphrase. For backward compatibility, Crypt::CBC\nwill default to \"opensslv1\", but it is recommended to use\nthe standard \"pbkdf2\"algorithm instead. If you wish to interoperate\nwith OpenSSL, be aware that different versions of the software\nsupport a series of derivation functions.\n\n'none' -- The value provided in -pass/-key is used directly.\nThis is the same as passing true to -literalkey.\nYou must also manually specify the IV with -iv.\nThe key and the IV must match the keylength\nand blocklength of the chosen cipher.\n'randomiv' -- Use insecure key derivation method found\nin prehistoric versions of OpenSSL (dangerous)\n'opensslv1' -- [default] Use the salted MD5 method that was default\nin versions of OpenSSL through v1.0.2.\n'opensslv2' -- [better] Use the salted SHA-256 method that was\nthe default in versions of OpenSSL through v1.1.0.\n'pbkdf2' -- [best] Use the PBKDF2 method that was first\nintroduced in OpenSSL v1.1.1.\n\nMore derivation functions may be added in the future. To see the\nsupported list, use the command\nperl -MCrypt::CBC::PBKDF -e 'print join \"\\n\",Crypt::CBC::PBKDF->list'\n\n-iter If the 'pbkdf2' key derivation algorithm is used, this specifies the number of\nhashing cycles to be applied to the passphrase+salt (longer is more secure).\n[default 10,000]\n\n-hasher If the 'pbkdf2' key derivation algorithm is chosen, you can use this to provide\nan initialized Crypt::PBKDF2::Hash object.\n[default HMACSHA2 for OpenSSL compatability]\n\n-header What type of header to prepend to the ciphertext. One of\n'salt' -- use OpenSSL-compatible salted header (default)\n'randomiv' -- Randomiv-compatible \"RandomIV\" header\n'none' -- prepend no header at all\n(compatible with prehistoric versions\nof OpenSSL)\n\n-iv The initialization vector (IV). If not provided, it will be generated\nby the key derivation function.\n\n-salt The salt passed to the key derivation function. If not provided, will be\ngenerated randomly (recommended).\n\n-padding The padding method, one of \"standard\" (default),\n\"space\", \"oneandzeroes\", \"rijndaelcompat\",\n\"null\", or \"none\" (default \"standard\").\n\n-literalkey [deprected, use -pbkdf=>'none']\nIf true, the key provided by \"-key\" or \"-pass\" is used\ndirectly for encryption/decryption without salting or\nhashing. The key must be the right length for the chosen\ncipher.\n[default false)\n\n-pcbc [deprecated, use -chainingmode=>'pcbc']\nWhether to use the PCBC chaining algorithm rather than\nthe standard CBC algorithm (default false).\n", "subsections": [ { "name": "-add_header [deprecated; use -header instead]", "content": "Whether to add the salt and IV to the header of the output\ncipher text.\n" }, { "name": "-regenerate_key [deprecated; use -literal_key instead]", "content": "Whether to use a hash of the provided key to generate\nthe actual encryption key (default true)\n" }, { "name": "-prepend_iv [deprecated; use -header instead]", "content": "Whether to prepend the IV to the beginning of the\nencrypted stream (default true)\n\nCrypt::CBC requires three pieces of information to do its job. First it needs the name of the\nblock cipher algorithm that will encrypt or decrypt the data in blocks of fixed length known as\nthe cipher's \"blocksize.\" Second, it needs an encryption/decryption key to pass to the block\ncipher. Third, it needs an initialization vector (IV) that will be used to propagate information\nfrom one encrypted block to the next. Both the key and the IV must be exactly the same length as\nthe chosen cipher's blocksize.\n\nCrypt::CBC can derive the key and the IV from a passphrase that you provide, or can let you\nspecify the true key and IV manually. In addition, you have the option of embedding enough\ninformation to regenerate the IV in a short header that is emitted at the start of the encrypted\nstream, or outputting a headerless encryption stream. In the first case, Crypt::CBC will be able\nto decrypt the stream given just the original key or passphrase. In the second case, you will\nhave to provide the original IV as well as the key/passphrase.\n\nThe -cipher option specifies which block cipher algorithm to use to encode each section of the\nmessage. This argument is optional and will default to the secure Crypt::Cipher::AES algorithm.\nYou may use any compatible block encryption algorithm that you have installed. Currently, this\nincludes Crypt::Cipher::AES, Crypt::DES, Crypt::DESEDE3, Crypt::IDEA, Crypt::Blowfish,\nCrypt::CAST5 and Crypt::Rijndael. You may refer to them using their full names (\"Crypt::IDEA\")\nor in abbreviated form (\"IDEA\").\n\nInstead of passing the name of a cipher class, you may pass an already-created block cipher\nobject. This allows you to take advantage of cipher algorithms that have parameterized new()\nmethods, such as Crypt::Eksblowfish:\n\nmy $eksblowfish = Crypt::Eksblowfish->new(8,$salt,$key);\nmy $cbc = Crypt::CBC->new(-cipher=>$eksblowfish);\n\nThe -pass argument provides a passphrase to use to generate the encryption key or the literal\nvalue of the block cipher key. If used in passphrase mode (which is the default), -pass can be\nany number of characters; the actual key will be derived by passing the passphrase through a\nseries of hashing operations. To take full advantage of a given block cipher, the length of the\npassphrase should be at least equal to the cipher's blocksize. For backward compatibility, you\nmay also refer to this argument using -key.\n\nTo skip this hashing operation and specify the key directly, provide the actual key as a string\nto -key and specify a key derivation function of \"none\" to the -pbkdf argument. Alternatively,\nyou may pass a true value to the -literalkey argument. When you manually specify the key in\nthis way, should choose a key of length exactly equal to the cipher's key length. You will also\nhave to specify an IV equal in length to the cipher's blocksize. These choices imply a header\nmode of \"none.\"\n\nIf you pass an existing Crypt::* object to new(), then the -pass/-key argument is ignored and\nthe module will generate a warning.\n\nThe -pbkdf argument specifies the algorithm used to derive the true key and IV from the provided\npassphrase (PBKDF stands for \"passphrase-based key derivation function\"). Valid values are:\n\n\"opensslv1\" -- [default] A fast algorithm that derives the key by\ncombining a random salt values with the passphrase via\na series of MD5 hashes.\n\n\"opensslv2\" -- an improved version that uses SHA-256 rather\nthan MD5, and has been OpenSSL's default since v1.1.0.\nHowever, it has been deprecated in favor of pbkdf2\nsince OpenSSL v1.1.1.\n\n\"pbkdf2\" -- a better algorithm implemented in OpenSSL v1.1.1,\ndescribed in RFC 2898 L\n\n\"none\" -- don't use a derivation function, but treat the passphrase\nas the literal key. This is the same as B<-literalkey> true.\n\n\"nosalt\" -- an insecure key derivation method used by prehistoric versions\nof OpenSSL, provided for backward compatibility. Don't use.\n\n\"opensslv1\" was OpenSSL's default key derivation algorithm through version 1.0.2, but is\nsusceptible to dictionary attacks and is no longer supported. It remains the default for\nCrypt::CBC in order to avoid breaking compatibility with previously-encrypted messages. Using\nthis option will issue a deprecation warning when initiating encryption. You can suppress the\nwarning by passing a true value to the -nodeprecate option.\n\nIt is recommended to specify the \"pbkdf2\" key derivation algorithm when compatibility with older\nversions of Crypt::CBC is not needed. This algorithm is deliberately computationally expensive\nin order to make dictionary-based attacks harder. As a result, it introduces a slight delay\nbefore an encryption or decryption operation starts.\n\nThe -iter argument is used in conjunction with the \"pbkdf2\" key derivation option. Its value\nindicates the number of hashing cycles used to derive the key. Larger values are more secure,\nbut impose a longer delay before encryption/decryption starts. The default is 10,000 for\ncompatibility with OpenSSL's default.\n\nThe -hasher argument is used in conjunction with the \"pbkdf2\" key derivation option to pass the\nreference to an initialized Crypt::PBKDF2::Hash object. If not provided, it defaults to the\nOpenSSL-compatible hash function HMACSHA2 initialized with its default options (SHA-256 hash).\n\nThe -header argument specifies what type of header, if any, to prepend to the beginning of the\nencrypted data stream. The header allows Crypt::CBC to regenerate the original IV and correctly\ndecrypt the data without your having to provide the same IV used to encrypt the data. Valid\nvalues for the -header are:\n\n\"salt\" -- Combine the passphrase with an 8-byte random value to\ngenerate both the block cipher key and the IV from the\nprovided passphrase. The salt will be appended to the\nbeginning of the data stream allowing decryption to\nregenerate both the key and IV given the correct passphrase.\nThis method is compatible with current versions of OpenSSL.\n\n\"randomiv\" -- Generate the block cipher key from the passphrase, and\nchoose a random 8-byte value to use as the IV. The IV will\nbe prepended to the data stream. This method is compatible\nwith ciphertext produced by versions of the library prior to\n2.17, but is incompatible with block ciphers that have non\n8-byte block sizes, such as Rijndael. Crypt::CBC will exit\nwith a fatal error if you try to use this header mode with a\nnon 8-byte cipher. This header type is NOT secure and NOT\nrecommended.\n\n\"none\" -- Do not generate a header. To decrypt a stream encrypted\nin this way, you will have to provide the true key and IV\nmanually.\n\nThe \"salt\" header is now the default as of Crypt::CBC version 2.17. In all earlier versions\n\"randomiv\" was the default.\n\nWhen using a \"salt\" header, you may specify your own value of the salt, by passing the desired\n8-byte character string to the -salt argument. Otherwise, the module will generate a random salt\nfor you. Crypt::CBC will generate a fatal error if you specify a salt value that isn't exactly 8\nbytes long. For backward compatibility reasons, passing a value of \"1\" will generate a random\nsalt, the same as if no -salt argument was provided.\n\nThe -padding argument controls how the last few bytes of the encrypted stream are dealt with\nwhen they not an exact multiple of the cipher block length. The default is \"standard\", the\nmethod specified in PKCS#5.\n\nThe -chainingmode argument will select among several different block chaining modes. Values\nare:\n\n'cbc' -- [default] traditional Cipher-Block Chaining mode. It has\nthe property that if one block in the ciphertext message\nis damaged, only that block and the next one will be\nrendered un-decryptable.\n\n'pcbc' -- Plaintext Cipher-Block Chaining mode. This has the property\nthat one damaged ciphertext block will render the\nremainder of the message unreadable\n\n'cfb' -- Cipher Feedback Mode. In this mode, both encryption and decryption\nare performed using the block cipher's \"encrypt\" algorithm.\nThe error propagation behaviour is similar to CBC's.\n\n'ofb' -- Output Feedback Mode. Similar to CFB, the block cipher's encrypt\nalgorithm is used for both encryption and decryption. If one bit\nof the plaintext or ciphertext message is damaged, the damage is\nconfined to a single block of the corresponding ciphertext or\nplaintext, and error correction algorithms can be used to reconstruct\nthe damaged part.\n\n'ctr' -- Counter Mode. This mode uses a one-time \"nonce\" instead of\nan IV. The nonce is incremented by one for each block of\nplain or ciphertext, encrypted using the chosen\nalgorithm, and then applied to the block of text. If one\nbit of the input text is damaged, it only affects 1 bit\nof the output text. To use CTR mode you will need to\ninstall the Perl Math::Int128 module. This chaining method\nis roughly half the speed of the others due to integer\narithmetic.\n\nPassing a -pcbc argument of true will have the same effect as -chainingmode=>'pcbc', and is\nincluded for backward compatibility. [deprecated].\n\nFor more information on chaining modes, see\n.\n\nThe -keysize argument can be used to force the cipher's keysize. This is useful for several of\nthe newer algorithms, including AES, ARIA, Blowfish, and CAMELLIA. If -keysize is not specified,\nthen Crypt::CBC will use the value returned by the cipher's maxkeylength() method. Note that\nversions of CBC::Crypt prior to 2.36 could also allow you to set the blocksie, but this was\nnever supported by any ciphers and has been removed.\n\nFor compatibility with earlier versions of this module, you can provide new() with a hashref\ncontaining key/value pairs. The key names are the same as the arguments described earlier, but\nwithout the initial hyphen. You may also call new() with one or two positional arguments, in\nwhich case the first argument is taken to be the key and the second to be the optional block\ncipher algorithm.\n\nstart()\n$cipher->start('encrypting');\n$cipher->start('decrypting');\n\nThe start() method prepares the cipher for a series of encryption or decryption steps, resetting\nthe internal state of the cipher if necessary. You must provide a string indicating whether you\nwish to encrypt or decrypt. \"E\" or any word that begins with an \"e\" indicates encryption. \"D\" or\nany word that begins with a \"d\" indicates decryption.\n\ncrypt()\n$ciphertext = $cipher->crypt($plaintext);\n\nAfter calling start(), you should call crypt() as many times as necessary to encrypt the desired\ndata.\n\nfinish()\n$ciphertext = $cipher->finish();\n\nThe CBC algorithm must buffer data blocks internally until they are even multiples of the\nencryption algorithm's blocksize (typically 8 bytes). After the last call to crypt() you should\ncall finish(). This flushes the internal buffer and returns any leftover ciphertext.\n\nIn a typical application you will read the plaintext from a file or input stream and write the\nresult to standard output in a loop that might look like this:\n\n$cipher = new Crypt::CBC('hey jude!');\n$cipher->start('encrypting');\nprint $cipher->crypt($) while <>;\nprint $cipher->finish();\n\nencrypt()\n$ciphertext = $cipher->encrypt($plaintext)\n\nThis convenience function runs the entire sequence of start(), crypt() and finish() for you,\nprocessing the provided plaintext and returning the corresponding ciphertext.\n\ndecrypt()\n$plaintext = $cipher->decrypt($ciphertext)\n\nThis convenience function runs the entire sequence of start(), crypt() and finish() for you,\nprocessing the provided ciphertext and returning the corresponding plaintext.\n\nencrypthex(), decrypthex()\n$ciphertext = $cipher->encrypthex($plaintext)\n$plaintext = $cipher->decrypthex($ciphertext)\n\nThese are convenience functions that operate on ciphertext in a hexadecimal representation." }, { "name": "encrypt_hex", "content": "functions can be useful if, for example, you wish to place the encrypted in an email message.\n\nfilehandle()\nThis method returns a filehandle for transparent encryption or decryption using Christopher\nDunkle's excellent Crypt::FileHandle module. This module must be installed in order to use this\nmethod.\n" }, { "name": "filehandle", "content": "$fh = Crypt::CBC->filehandle(-cipher=> 'Blowfish',\n-pass => \"You'll never guess\");\n\nor on a previously-created Crypt::CBC object:\n\n$cbc = Crypt::CBC->new(-cipher=> 'Blowfish',\n-pass => \"You'll never guess\");\n$fh = $cbc->filehandle;\n\nThe filehandle can then be opened using the familiar open() syntax. Printing to a filehandle\nopened for writing will encrypt the data. Filehandles opened for input will be decrypted.\n\nHere is an example:\n\n# transparent encryption\nopen $fh,'>','encrypted.out' or die $!;\nprint $fh \"You won't be able to read me!\\n\";\nclose $fh;\n\n# transparent decryption\nopen $fh,'<','encrypted.out' or die $!;\nwhile (<$fh>) { print $ }\nclose $fh;\n\ngetinitializationvector()\n$iv = $cipher->getinitializationvector()\n\nThis function will return the IV used in encryption and or decryption. The IV is not guaranteed\nto be set when encrypting until start() is called, and when decrypting until crypt() is called\nthe first time. Unless the IV was manually specified in the new() call, the IV will change with\nevery complete encryption operation.\n\nsetinitializationvector()\n$cipher->setinitializationvector('76543210')\n\nThis function sets the IV used in encryption and/or decryption. This function may be useful if\nthe IV is not contained within the ciphertext string being decrypted, or if a particular IV is\ndesired for encryption. Note that the IV must match the chosen cipher's blocksize bytes in\nlength.\n\niv()\n$iv = $cipher->iv();\n$cipher->iv($newiv);\n\nAs above, but using a single method call.\n\nkey()\n$key = $cipher->key();\n$cipher->key($newkey);\n\nGet or set the block cipher key used for encryption/decryption. When encrypting, the key is not\nguaranteed to exist until start() is called, and when decrypting, the key is not guaranteed to\nexist until after the first call to crypt(). The key must match the length required by the\nunderlying block cipher.\n\nWhen salted headers are used, the block cipher key will change after each complete sequence of\nencryption operations.\n\nsalt()\n$salt = $cipher->salt();\n$cipher->salt($newsalt);\n\nGet or set the salt used for deriving the encryption key and IV when in OpenSSL compatibility\nmode.\n\npassphrase()\n$passphrase = $cipher->passphrase();\n$cipher->passphrase($newpassphrase);\n\nThis gets or sets the value of the passphrase passed to new() when literalkey is false.\n\n$data = randombytes($numbytes)\nReturn $numbytes worth of random data. On systems that support the \"/dev/urandom\" device file,\nthis data will be read from the device. Otherwise, it will be generated by repeated calls to the\nPerl rand() function.\n\ncipher(), pbkdf(), padding(), keysize(), blocksize(), chainmode()\nThese read-only methods return the identity of the chosen block cipher algorithm, the key\nderivation function (e.g. \"opensslv1\"), padding method, key and block size of the chosen block\ncipher, and what chaining mode (\"cbc\", \"ofb\" ,etc) is being used.\n" }, { "name": "Padding methods", "content": "Use the 'padding' option to change the padding method.\n\nWhen the last block of plaintext is shorter than the block size, it must be padded. Padding\nmethods include: \"standard\" (i.e., PKCS#5), \"oneandzeroes\", \"space\", \"rijndaelcompat\", \"null\",\nand \"none\".\n\nstandard: (default) Binary safe\npads with the number of bytes that should be truncated. So, if\nblocksize is 8, then \"0A0B0C\" will be padded with \"05\", resulting\nin \"0A0B0C0505050505\". If the final block is a full block of 8\nbytes, then a whole block of \"0808080808080808\" is appended.\n\noneandzeroes: Binary safe\npads with \"80\" followed by as many \"00\" necessary to fill the\nblock. If the last block is a full block and blocksize is 8, a\nblock of \"8000000000000000\" will be appended.\n\nrijndaelcompat: Binary safe, with caveats\nsimilar to oneandzeroes, except that no padding is performed if\nthe last block is a full block. This is provided for\ncompatibility with Crypt::Rijndael's buit-in MODECBC.\nNote that Crypt::Rijndael's implementation of CBC only\nworks with messages that are even multiples of 16 bytes.\n\nnull: text only\npads with as many \"00\" necessary to fill the block. If the last\nblock is a full block and blocksize is 8, a block of\n\"0000000000000000\" will be appended.\n\nspace: text only\nsame as \"null\", but with \"20\".\n\nnone:\nno padding added. Useful for special-purpose applications where\nyou wish to add custom padding to the message.\n\nBoth the standard and oneandzeroes paddings are binary safe. The space and null paddings are\nrecommended only for text data. Which type of padding you use depends on whether you wish to\ncommunicate with an external (non Crypt::CBC library). If this is the case, use whatever padding\nmethod is compatible.\n\nYou can also pass in a custom padding function. To do this, create a function that takes the\narguments:\n\n$paddedblock = function($block,$blocksize,$direction);\n\nwhere $block is the current block of data, $blocksize is the size to pad it to, $direction is\n\"e\" for encrypting and \"d\" for decrypting, and $paddedblock is the result after padding or\ndepadding.\n\nWhen encrypting, the function should always return a string of length, and when\ndecrypting, can expect the string coming in to always be that length. See standardpadding(),\nspacepadding(), nullpadding(), or oneandzeroespadding() in the source for examples.\n\nStandard and oneandzeroes padding are recommended, as both space and null padding can\npotentially truncate more characters than they should.\n" } ] }, "Comparison to Crypt::Mode::CBC": { "content": "The CryptX modules Crypt::Mode::CBC, Crypt::Mode::OFB, Crypt::Mode::CFB, and Crypt::Mode::CTR\nprovide fast implementations of the respective cipherblock chaining modes (roughly 5x the speed\nof Crypt::CBC). Crypt::CBC was designed to encrypt and decrypt messages in a manner compatible\nwith OpenSSL's \"enc\" function. Hence it handles the derivation of the key and IV from a\npassphrase using the same conventions as OpenSSL, and it writes out an OpenSSL-compatible header\nin the encrypted message in a manner that allows the key and IV to be regenerated during\ndecryption.\n\nIn contrast, the CryptX modules do not automatically derive the key and IV from a passphrase or\nwrite out an encrypted header. You will need to derive and store the key and IV by other means\n(e.g. with CryptX's Crypt::KeyDerivation module, or with Crypt::PBKDF2).\n", "subsections": [] }, "EXAMPLES": { "content": "Three examples, aes.pl, des.pl and idea.pl can be found in the eg/ subdirectory of the Crypt-CBC\ndistribution. These implement command-line DES and IDEA encryption algorithms using default\nparameters, and should be compatible with recent versions of OpenSSL. Note that aes.pl uses the\n\"pbkdf2\" key derivation function to generate its keys. The other two were distributed with\npre-PBKDF2 versions of Crypt::CBC, and use the older \"opensslv1\" algorithm.\n", "subsections": [] }, "LIMITATIONS": { "content": "The encryption and decryption process is about a tenth the speed of the equivalent OpenSSL tool\nand about a fifth of the Crypt::Mode::CBC module (both which use compiled C).\n", "subsections": [] }, "BUGS": { "content": "Please report them.\n", "subsections": [] }, "AUTHOR": { "content": "Lincoln Stein, lstein@cshl.org\n\nThis module is distributed under the ARTISTIC LICENSE v2 using the same terms as Perl itself.\n", "subsections": [] }, "SEE ALSO": { "content": "", "subsections": [ { "name": "perl", "content": "Crypt::DES, Crypt::IDEA, Crypt::Rijndael\n" } ] } } } }