File: //usr/local/share/man/man3/Crypt::CBC.3pm
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Crypt::CBC 3"
.TH Crypt::CBC 3 "2021-05-17" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Crypt::CBC \- Encrypt Data with Cipher Block Chaining Mode
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\& use Crypt::CBC;
\& $cipher = Crypt::CBC\->new( \-pass => \*(Aqmy secret password\*(Aq,
\& \-cipher => \*(AqCipher::AES\*(Aq
\& );
\&
\& # one shot mode
\& $ciphertext = $cipher\->encrypt("This data is hush hush");
\& $plaintext = $cipher\->decrypt($ciphertext);
\&
\& # stream mode
\& $cipher\->start(\*(Aqencrypting\*(Aq);
\& open(F,"./BIG_FILE");
\& while (read(F,$buffer,1024)) {
\& print $cipher\->crypt($buffer);
\& }
\& print $cipher\->finish;
\&
\& # do\-it\-yourself mode \-\- specify key && initialization vector yourself
\& $key = Crypt::CBC\->random_bytes(8); # assuming a 8\-byte block cipher
\& $iv = Crypt::CBC\->random_bytes(8);
\& $cipher = Crypt::CBC\->new(\-pbkdf => \*(Aqnone\*(Aq,
\& \-key => $key,
\& \-iv => $iv);
\&
\& $ciphertext = $cipher\->encrypt("This data is hush hush");
\& $plaintext = $cipher\->decrypt($ciphertext);
\&
\& # encrypting via a filehandle (requires Crypt::FileHandle>
\& $fh = Crypt::CBC\->filehandle(\-pass => \*(Aqsecret\*(Aq);
\& open $fh,\*(Aq>\*(Aq,\*(Aqencrypted.txt" or die $!
\& print $fh "This will be encrypted\en";
\& close $fh;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is a Perl-only implementation of the cryptographic cipher
block chaining mode (\s-1CBC\s0). In combination with a block cipher such as
\&\s-1AES\s0 or Blowfish, you can encrypt and decrypt messages of arbitrarily
long length. The encrypted messages are compatible with the
encryption format used by the \fBOpenSSL\fR package.
.PP
To use this module, you will first create a Crypt::CBC cipher object
with \fBnew()\fR. At the time of cipher creation, you specify an encryption
key to use and, optionally, a block encryption algorithm. You will
then call the \fBstart()\fR method to initialize the encryption or
decryption process, \fBcrypt()\fR to encrypt or decrypt one or more blocks
of data, and lastly \fBfinish()\fR, to pad and encrypt the final block. For
your convenience, you can call the \fBencrypt()\fR and \fBdecrypt()\fR methods to
operate on a whole data value at once.
.SS "\fBnew()\fP"
.IX Subsection "new()"
.Vb 3
\& $cipher = Crypt::CBC\->new( \-pass => \*(Aqmy secret key\*(Aq,
\& \-cipher => \*(AqCipher::AES\*(Aq,
\& );
\&
\& # or (for compatibility with versions prior to 2.0)
\& $cipher = new Crypt::CBC(\*(Aqmy secret key\*(Aq => \*(AqCipher::AES\*(Aq);
.Ve
.PP
The \fBnew()\fR method creates a new Crypt::CBC object. It accepts a list of
\&\-argument => value pairs selected from the following list:
.PP
.Vb 2
\& Argument Description
\& \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-
\&
\& \-pass,\-key The encryption/decryption passphrase. These arguments
\& are interchangeable, but \-pass is preferred
\& ("key" is a misnomer, as it is not the literal
\& encryption key).
\&
\& \-cipher The cipher algorithm (defaults to Crypt::Cipher:AES), or
\& a previously created cipher object reference. For
\& convenience, you may omit the initial "Crypt::" part
\& of the classname and use the basename, e.g. "Blowfish"
\& instead of "Crypt::Blowfish".
\&
\& \-keysize Force the cipher keysize to the indicated number of bytes. This can be used
\& to set the keysize for variable keylength ciphers such as AES.
\&
\& \-chain_mode The block chaining mode to use. Current options are:
\& \*(Aqcbc\*(Aq \-\- cipher\-block chaining mode [default]
\& \*(Aqpcbc\*(Aq \-\- plaintext cipher\-block chaining mode
\& \*(Aqcfb\*(Aq \-\- cipher feedback mode
\& \*(Aqofb\*(Aq \-\- output feedback mode
\& \*(Aqctr\*(Aq \-\- counter mode
\&
\& \-pbkdf The passphrase\-based key derivation function used to derive
\& the encryption key and initialization vector from the
\& provided passphrase. For backward compatibility, Crypt::CBC
\& will default to "opensslv1", but it is recommended to use
\& the standard "pbkdf2"algorithm instead. If you wish to interoperate
\& with OpenSSL, be aware that different versions of the software
\& support a series of derivation functions.
\&
\& \*(Aqnone\*(Aq \-\- The value provided in \-pass/\-key is used directly.
\& This is the same as passing true to \-literal_key.
\& You must also manually specify the IV with \-iv.
\& The key and the IV must match the keylength
\& and blocklength of the chosen cipher.
\& \*(Aqrandomiv\*(Aq \-\- Use insecure key derivation method found
\& in prehistoric versions of OpenSSL (dangerous)
\& \*(Aqopensslv1\*(Aq \-\- [default] Use the salted MD5 method that was default
\& in versions of OpenSSL through v1.0.2.
\& \*(Aqopensslv2\*(Aq \-\- [better] Use the salted SHA\-256 method that was
\& the default in versions of OpenSSL through v1.1.0.
\& \*(Aqpbkdf2\*(Aq \-\- [best] Use the PBKDF2 method that was first
\& introduced in OpenSSL v1.1.1.
\&
\& More derivation functions may be added in the future. To see the
\& supported list, use the command
\& perl \-MCrypt::CBC::PBKDF \-e \*(Aqprint join "\en",Crypt::CBC::PBKDF\->list\*(Aq
\&
\& \-iter If the \*(Aqpbkdf2\*(Aq key derivation algorithm is used, this specifies the number of
\& hashing cycles to be applied to the passphrase+salt (longer is more secure).
\& [default 10,000]
\&
\& \-hasher If the \*(Aqpbkdf2\*(Aq key derivation algorithm is chosen, you can use this to provide
\& an initialized Crypt::PBKDF2::Hash object.
\& [default HMACSHA2 for OpenSSL compatability]
\&
\& \-header What type of header to prepend to the ciphertext. One of
\& \*(Aqsalt\*(Aq \-\- use OpenSSL\-compatible salted header (default)
\& \*(Aqrandomiv\*(Aq \-\- Randomiv\-compatible "RandomIV" header
\& \*(Aqnone\*(Aq \-\- prepend no header at all
\& (compatible with prehistoric versions
\& of OpenSSL)
\&
\& \-iv The initialization vector (IV). If not provided, it will be generated
\& by the key derivation function.
\&
\& \-salt The salt passed to the key derivation function. If not provided, will be
\& generated randomly (recommended).
\&
\& \-padding The padding method, one of "standard" (default),
\& "space", "oneandzeroes", "rijndael_compat",
\& "null", or "none" (default "standard").
\&
\& \-literal_key [deprected, use \-pbkdf=>\*(Aqnone\*(Aq]
\& If true, the key provided by "\-key" or "\-pass" is used
\& directly for encryption/decryption without salting or
\& hashing. The key must be the right length for the chosen
\& cipher.
\& [default false)
\&
\& \-pcbc [deprecated, use \-chaining_mode=>\*(Aqpcbc\*(Aq]
\& Whether to use the PCBC chaining algorithm rather than
\& the standard CBC algorithm (default false).
\&
\& \-add_header [deprecated; use \-header instead]
\& Whether to add the salt and IV to the header of the output
\& cipher text.
\&
\& \-regenerate_key [deprecated; use \-literal_key instead]
\& Whether to use a hash of the provided key to generate
\& the actual encryption key (default true)
\&
\& \-prepend_iv [deprecated; use \-header instead]
\& Whether to prepend the IV to the beginning of the
\& encrypted stream (default true)
.Ve
.PP
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
\&\*(L"blocksize.\*(R" Second, it needs an encryption/decryption key to pass to
the block cipher. Third, it needs an initialization vector (\s-1IV\s0) that
will be used to propagate information from one encrypted block to the
next. Both the key and the \s-1IV\s0 must be exactly the same length as the
chosen cipher's blocksize.
.PP
Crypt::CBC can derive the key and the \s-1IV\s0 from a passphrase that you
provide, or can let you specify the true key and \s-1IV\s0 manually. In
addition, you have the option of embedding enough information to
regenerate the \s-1IV\s0 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 \s-1IV\s0 as well as the key/passphrase.
.PP
The \fB\-cipher\fR option specifies which block cipher algorithm to use to
encode each section of the message. This argument is optional and
will default to the secure Crypt::Cipher::AES algorithm.
You may use any compatible block encryption
algorithm that you have installed. Currently, this includes
Crypt::Cipher::AES, Crypt::DES, Crypt::DES_EDE3, Crypt::IDEA, Crypt::Blowfish,
Crypt::CAST5 and Crypt::Rijndael. You may refer to them using their
full names (\*(L"Crypt::IDEA\*(R") or in abbreviated form (\*(L"\s-1IDEA\*(R"\s0).
.PP
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 \fBnew()\fR methods, such as
Crypt::Eksblowfish:
.PP
.Vb 2
\& my $eksblowfish = Crypt::Eksblowfish\->new(8,$salt,$key);
\& my $cbc = Crypt::CBC\->new(\-cipher=>$eksblowfish);
.Ve
.PP
The \fB\-pass\fR 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), \fB\-pass\fR 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 \fB\-key\fR.
.PP
To skip this hashing operation and specify the key directly, provide
the actual key as a string to \fB\-key\fR and specify a key derivation
function of \*(L"none\*(R" to the \fB\-pbkdf\fR argument. Alternatively, you may
pass a true value to the \fB\-literal_key\fR 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 \s-1IV\s0
equal in length to the cipher's blocksize. These choices imply a
header mode of \*(L"none.\*(R"
.PP
If you pass an existing Crypt::* object to \fBnew()\fR, then the
\&\fB\-pass\fR/\fB\-key\fR argument is ignored and the module will generate a
warning.
.PP
The \fB\-pbkdf\fR argument specifies the algorithm used to derive the true
key and \s-1IV\s0 from the provided passphrase (\s-1PBKDF\s0 stands for
\&\*(L"passphrase-based key derivation function\*(R"). Valid values are:
.PP
.Vb 3
\& "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\*(Aqs default since v1.1.0.
\& However, it has been deprecated in favor of pbkdf2
\& since OpenSSL v1.1.1.
\&
\& "pbkdf2" \-\- a better algorithm implemented in OpenSSL v1.1.1,
\& described in RFC 2898 L<https://tools.ietf.org/html/rfc2898>
\&
\& "none" \-\- don\*(Aqt use a derivation function, but treat the passphrase
\& as the literal key. This is the same as B<\-literal_key> true.
\&
\& "nosalt" \-\- an insecure key derivation method used by prehistoric versions
\& of OpenSSL, provided for backward compatibility. Don\*(Aqt use.
.Ve
.PP
\&\*(L"opensslv1\*(R" 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 \fB\-nodeprecate\fR option.
.PP
It is recommended to specify the \*(L"pbkdf2\*(R" 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.
.PP
The \fB\-iter\fR argument is used in conjunction with the \*(L"pbkdf2\*(R" 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.
.PP
The \fB\-hasher\fR argument is used in conjunction with the \*(L"pbkdf2\*(R" 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 \s-1HMACSHA2\s0 initialized with its default
options (\s-1SHA\-256\s0 hash).
.PP
The \fB\-header\fR 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 \s-1IV\s0 and correctly decrypt
the data without your having to provide the same \s-1IV\s0 used to encrypt
the data. Valid values for the \fB\-header\fR are:
.PP
.Vb 6
\& "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.
.Ve
.PP
\&\fBThe \*(L"salt\*(R" header is now the default as of Crypt::CBC version 2.17. In
all earlier versions \*(L"randomiv\*(R" was the default.\fR
.PP
When using a \*(L"salt\*(R" header, you may specify your own value of the
salt, by passing the desired 8\-byte character string to the \fB\-salt\fR
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 \*(L"1\*(R" will generate a random salt, the same
as if no \fB\-salt\fR argument was provided.
.PP
The \fB\-padding\fR 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 \*(L"standard\*(R", the method specified
in PKCS#5.
.PP
The \fB\-chaining_mode\fR argument will select among several different
block chaining modes. Values are:
.PP
.Vb 4
\& \*(Aqcbc\*(Aq \-\- [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.
\&
\& \*(Aqpcbc\*(Aq \-\- Plaintext Cipher\-Block Chaining mode. This has the property
\& that one damaged ciphertext block will render the
\& remainder of the message unreadable
\&
\& \*(Aqcfb\*(Aq \-\- Cipher Feedback Mode. In this mode, both encryption and decryption
\& are performed using the block cipher\*(Aqs "encrypt" algorithm.
\& The error propagation behaviour is similar to CBC\*(Aqs.
\&
\& \*(Aqofb\*(Aq \-\- Output Feedback Mode. Similar to CFB, the block cipher\*(Aqs 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.
\&
\& \*(Aqctr\*(Aq \-\- 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.
.Ve
.PP
Passing a \fB\-pcbc\fR argument of true will have the same effect as
\&\-chaining_mode=>'pcbc', and is included for backward
compatibility. [deprecated].
.PP
For more information on chaining modes, see
<http://www.crypto\-it.net/eng/theory/modes\-of\-block\-ciphers.html>.
.PP
The \fB\-keysize\fR argument can be used to force the cipher's
keysize. This is useful for several of the newer algorithms, including
\&\s-1AES, ARIA,\s0 Blowfish, and \s-1CAMELLIA.\s0 If \-keysize is not specified, then
Crypt::CBC will use the value returned by the cipher's \fBmax_keylength()\fR
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.
.PP
For compatibility with earlier versions of this module, you can
provide \fBnew()\fR 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 \fBnew()\fR 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.
.SS "\fBstart()\fP"
.IX Subsection "start()"
.Vb 2
\& $cipher\->start(\*(Aqencrypting\*(Aq);
\& $cipher\->start(\*(Aqdecrypting\*(Aq);
.Ve
.PP
The \fBstart()\fR 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. \*(L"E\*(R" or any word that begins with an \*(L"e\*(R" indicates
encryption. \*(L"D\*(R" or any word that begins with a \*(L"d\*(R" indicates
decryption.
.SS "\fBcrypt()\fP"
.IX Subsection "crypt()"
.Vb 1
\& $ciphertext = $cipher\->crypt($plaintext);
.Ve
.PP
After calling \fBstart()\fR, you should call \fBcrypt()\fR as many times as
necessary to encrypt the desired data.
.SS "\fBfinish()\fP"
.IX Subsection "finish()"
.Vb 1
\& $ciphertext = $cipher\->finish();
.Ve
.PP
The \s-1CBC\s0 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 \fBcrypt()\fR you should call \fBfinish()\fR.
This flushes the internal buffer and returns any leftover ciphertext.
.PP
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:
.PP
.Vb 4
\& $cipher = new Crypt::CBC(\*(Aqhey jude!\*(Aq);
\& $cipher\->start(\*(Aqencrypting\*(Aq);
\& print $cipher\->crypt($_) while <>;
\& print $cipher\->finish();
.Ve
.SS "\fBencrypt()\fP"
.IX Subsection "encrypt()"
.Vb 1
\& $ciphertext = $cipher\->encrypt($plaintext)
.Ve
.PP
This convenience function runs the entire sequence of \fBstart()\fR, \fBcrypt()\fR
and \fBfinish()\fR for you, processing the provided plaintext and returning
the corresponding ciphertext.
.SS "\fBdecrypt()\fP"
.IX Subsection "decrypt()"
.Vb 1
\& $plaintext = $cipher\->decrypt($ciphertext)
.Ve
.PP
This convenience function runs the entire sequence of \fBstart()\fR, \fBcrypt()\fR
and \fBfinish()\fR for you, processing the provided ciphertext and returning
the corresponding plaintext.
.SS "\fBencrypt_hex()\fP, \fBdecrypt_hex()\fP"
.IX Subsection "encrypt_hex(), decrypt_hex()"
.Vb 2
\& $ciphertext = $cipher\->encrypt_hex($plaintext)
\& $plaintext = $cipher\->decrypt_hex($ciphertext)
.Ve
.PP
These are convenience functions that operate on ciphertext in a
hexadecimal representation. \fBencrypt_hex($plaintext)\fR is exactly
equivalent to \fBunpack('H*',encrypt($plaintext))\fR. These functions
can be useful if, for example, you wish to place the encrypted in an
email message.
.SS "\fBfilehandle()\fP"
.IX Subsection "filehandle()"
This method returns a filehandle for transparent encryption or
decryption using Christopher Dunkle's excellent Crypt::FileHandle
module. This module must be installed in order to use this method.
.PP
\&\fBfilehandle()\fR can be called as a class method using the same arguments
as \fBnew()\fR:
.PP
.Vb 2
\& $fh = Crypt::CBC\->filehandle(\-cipher=> \*(AqBlowfish\*(Aq,
\& \-pass => "You\*(Aqll never guess");
.Ve
.PP
or on a previously-created Crypt::CBC object:
.PP
.Vb 3
\& $cbc = Crypt::CBC\->new(\-cipher=> \*(AqBlowfish\*(Aq,
\& \-pass => "You\*(Aqll never guess");
\& $fh = $cbc\->filehandle;
.Ve
.PP
The filehandle can then be opened using the familiar \fBopen()\fR syntax.
Printing to a filehandle opened for writing will encrypt the
data. Filehandles opened for input will be decrypted.
.PP
Here is an example:
.PP
.Vb 4
\& # transparent encryption
\& open $fh,\*(Aq>\*(Aq,\*(Aqencrypted.out\*(Aq or die $!;
\& print $fh "You won\*(Aqt be able to read me!\en";
\& close $fh;
\&
\& # transparent decryption
\& open $fh,\*(Aq<\*(Aq,\*(Aqencrypted.out\*(Aq or die $!;
\& while (<$fh>) { print $_ }
\& close $fh;
.Ve
.SS "\fBget_initialization_vector()\fP"
.IX Subsection "get_initialization_vector()"
.Vb 1
\& $iv = $cipher\->get_initialization_vector()
.Ve
.PP
This function will return the \s-1IV\s0 used in encryption and or decryption.
The \s-1IV\s0 is not guaranteed to be set when encrypting until \fBstart()\fR is
called, and when decrypting until \fBcrypt()\fR is called the first
time. Unless the \s-1IV\s0 was manually specified in the \fBnew()\fR call, the \s-1IV\s0
will change with every complete encryption operation.
.SS "\fBset_initialization_vector()\fP"
.IX Subsection "set_initialization_vector()"
.Vb 1
\& $cipher\->set_initialization_vector(\*(Aq76543210\*(Aq)
.Ve
.PP
This function sets the \s-1IV\s0 used in encryption and/or decryption. This
function may be useful if the \s-1IV\s0 is not contained within the
ciphertext string being decrypted, or if a particular \s-1IV\s0 is desired
for encryption. Note that the \s-1IV\s0 must match the chosen cipher's
blocksize bytes in length.
.SS "\fBiv()\fP"
.IX Subsection "iv()"
.Vb 2
\& $iv = $cipher\->iv();
\& $cipher\->iv($new_iv);
.Ve
.PP
As above, but using a single method call.
.SS "\fBkey()\fP"
.IX Subsection "key()"
.Vb 2
\& $key = $cipher\->key();
\& $cipher\->key($new_key);
.Ve
.PP
Get or set the block cipher key used for encryption/decryption. When
encrypting, the key is not guaranteed to exist until \fBstart()\fR is
called, and when decrypting, the key is not guaranteed to exist until
after the first call to \fBcrypt()\fR. The key must match the length
required by the underlying block cipher.
.PP
When salted headers are used, the block cipher key will change after
each complete sequence of encryption operations.
.SS "\fBsalt()\fP"
.IX Subsection "salt()"
.Vb 2
\& $salt = $cipher\->salt();
\& $cipher\->salt($new_salt);
.Ve
.PP
Get or set the salt used for deriving the encryption key and \s-1IV\s0 when
in OpenSSL compatibility mode.
.SS "\fBpassphrase()\fP"
.IX Subsection "passphrase()"
.Vb 2
\& $passphrase = $cipher\->passphrase();
\& $cipher\->passphrase($new_passphrase);
.Ve
.PP
This gets or sets the value of the \fBpassphrase\fR passed to \fBnew()\fR when
\&\fBliteral_key\fR is false.
.ie n .SS "$data = random_bytes($numbytes)"
.el .SS "\f(CW$data\fP = random_bytes($numbytes)"
.IX Subsection "$data = random_bytes($numbytes)"
Return \f(CW$numbytes\fR worth of random data. On systems that support the
\&\*(L"/dev/urandom\*(R" device file, this data will be read from the
device. Otherwise, it will be generated by repeated calls to the Perl
\&\fBrand()\fR function.
.SS "\fBcipher()\fP, \fBpbkdf()\fP, \fBpadding()\fP, \fBkeysize()\fP, \fBblocksize()\fP, \fBchain_mode()\fP"
.IX Subsection "cipher(), pbkdf(), padding(), keysize(), blocksize(), chain_mode()"
These read-only methods return the identity of the chosen block cipher
algorithm, the key derivation function (e.g. \*(L"opensslv1\*(R"), padding
method, key and block size of the chosen block cipher, and what
chaining mode (\*(L"cbc\*(R", \*(L"ofb\*(R" ,etc) is being used.
.SS "Padding methods"
.IX Subsection "Padding methods"
Use the 'padding' option to change the padding method.
.PP
When the last block of plaintext is shorter than the block size,
it must be padded. Padding methods include: \*(L"standard\*(R" (i.e., PKCS#5),
\&\*(L"oneandzeroes\*(R", \*(L"space\*(R", \*(L"rijndael_compat\*(R", \*(L"null\*(R", and \*(L"none\*(R".
.PP
.Vb 5
\& standard: (default) Binary safe
\& pads with the number of bytes that should be truncated. So, if
\& blocksize is 8, then "0A0B0C" will be padded with "05", resulting
\& in "0A0B0C0505050505". If the final block is a full block of 8
\& bytes, then a whole block of "0808080808080808" is appended.
\&
\& oneandzeroes: Binary safe
\& pads with "80" followed by as many "00" necessary to fill the
\& block. If the last block is a full block and blocksize is 8, a
\& block of "8000000000000000" will be appended.
\&
\& rijndael_compat: Binary safe, with caveats
\& similar to oneandzeroes, except that no padding is performed if
\& the last block is a full block. This is provided for
\& compatibility with Crypt::Rijndael\*(Aqs buit\-in MODE_CBC.
\& Note that Crypt::Rijndael\*(Aqs implementation of CBC only
\& works with messages that are even multiples of 16 bytes.
\&
\& null: text only
\& pads with as many "00" necessary to fill the block. If the last
\& block is a full block and blocksize is 8, a block of
\& "0000000000000000" will be appended.
\&
\& space: text only
\& same as "null", but with "20".
\&
\& none:
\& no padding added. Useful for special\-purpose applications where
\& you wish to add custom padding to the message.
.Ve
.PP
Both the standard and oneandzeroes paddings are binary safe. The
space and null paddings are recommended only for text data. Which
type of padding you use depends on whether you wish to communicate
with an external (non Crypt::CBC library). If this is the case, use
whatever padding method is compatible.
.PP
You can also pass in a custom padding function. To do this, create a
function that takes the arguments:
.PP
.Vb 1
\& $padded_block = function($block,$blocksize,$direction);
.Ve
.PP
where \f(CW$block\fR is the current block of data, \f(CW$blocksize\fR is the size to
pad it to, \f(CW$direction\fR is \*(L"e\*(R" for encrypting and \*(L"d\*(R" for decrypting,
and \f(CW$padded_block\fR is the result after padding or depadding.
.PP
When encrypting, the function should always return a string of
<blocksize> length, and when decrypting, can expect the string coming
in to always be that length. See \fB_standard_padding()\fR, \fB_space_padding()\fR,
\&\fB_null_padding()\fR, or \fB_oneandzeroes_padding()\fR in the source for examples.
.PP
Standard and oneandzeroes padding are recommended, as both space and
null padding can potentially truncate more characters than they should.
.SH "Comparison to Crypt::Mode::CBC"
.IX Header "Comparison to Crypt::Mode::CBC"
The CryptX modules Crypt::Mode::CBC, Crypt::Mode::OFB,
Crypt::Mode::CFB, and Crypt::Mode::CTR provide fast
implementations of the respective cipherblock chaining modes (roughly
5x the speed of Crypt::CBC). Crypt::CBC was designed to encrypt and
decrypt messages in a manner compatible with OpenSSL's \*(L"enc\*(R"
function. Hence it handles the derivation of the key and \s-1IV\s0 from a
passphrase using the same conventions as OpenSSL, and it writes out an
OpenSSL-compatible header in the encrypted message in a manner that
allows the key and \s-1IV\s0 to be regenerated during decryption.
.PP
In contrast, the CryptX modules do not automatically derive the key
and \s-1IV\s0 from a passphrase or write out an encrypted header. You will
need to derive and store the key and \s-1IV\s0 by other means (e.g. with
CryptX's Crypt::KeyDerivation module, or with Crypt::PBKDF2).
.SH "EXAMPLES"
.IX Header "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 \s-1DES\s0 and \s-1IDEA\s0 encryption algorithms using default
parameters, and should be compatible with recent versions of
OpenSSL. Note that aes.pl uses the \*(L"pbkdf2\*(R" key derivation function to
generate its keys. The other two were distributed with pre\-PBKDF2
versions of Crypt::CBC, and use the older \*(L"opensslv1\*(R" algorithm.
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
The encryption and decryption process is about a tenth the speed of
the equivalent OpenSSL tool and about a fifth of the Crypt::Mode::CBC
module (both which use compiled C).
.SH "BUGS"
.IX Header "BUGS"
Please report them.
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein, lstein@cshl.org
.PP
This module is distributed under the \s-1ARTISTIC LICENSE\s0 v2 using the
same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), CryptX, Crypt::FileHandle, Crypt::Cipher::AES,
Crypt::Blowfish, Crypt::CAST5, Crypt::DES, Crypt::IDEA,
Crypt::Rijndael