.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 "Convert::PEM::CBC 3pm"
.TH Convert::PEM::CBC 3pm "2021-01-04" "perl v5.32.0" "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"
Convert::PEM::CBC \- Cipher Block Chaining Mode implementation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&    use Convert::PEM::CBC;
\&    my $cbc = Convert::PEM::CBC\->new(
\&                         Cipher     => \*(AqCrypt::DES_EDE3\*(Aq,
\&                         Passphrase => \*(Aqfoo\*(Aq
\&           );
\&
\&    my $plaintext = \*(Aqfoo bar baz\*(Aq;
\&    $cbc\->encrypt($plaintext);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIConvert::PEM::CBC\fR implements the \s-1CBC\s0 (Cipher Block Chaining)
mode for encryption/decryption ciphers; the \s-1CBC\s0 is designed for
compatability with OpenSSL and may not be compatible with other
implementations (such as \s-1SSH\s0).
.SH "USAGE"
.IX Header "USAGE"
.ie n .SS "$cbc = Convert::PEM::CBC\->new(%args)"
.el .SS "\f(CW$cbc\fP = Convert::PEM::CBC\->new(%args)"
.IX Subsection "$cbc = Convert::PEM::CBC->new(%args)"
Creates a new \fIConvert::PEM::CBC\fR object and initializes it.
Returns the new object.
.PP
\&\fI\f(CI%args\fI\fR can contain:
.IP "\(bu" 4
Cipher
.Sp
Either the name of an encryption cipher class (eg. \fICrypt::DES\fR),
or an object already blessed into such a class. The class must
support the \fIkeysize\fR, \fIblocksize\fR, \fIencrypt\fR, and \fIdecrypt\fR
methods. If the value is a blessed object, it is assumed that the
object has already been initialized with a key.
.Sp
This argument is mandatory.
.IP "\(bu" 4
Passphrase
.Sp
A passphrase to encrypt/decrypt the content. This is different in
implementation from a key (\fIKey\fR), because it is assumed that a
passphrase comes directly from a user, and must be munged into the
correct form for a key. This \*(L"munging\*(R" is done by repeatedly
computing an \s-1MD5\s0 hash of the passphrase, the \s-1IV,\s0 and the existing
hash, until the generated key is longer than the keysize for the
cipher (\fICipher\fR).
.Sp
Because of this \*(L"munging\*(R", this argument can be any length (even
an empty string).
.Sp
If you give the \fICipher\fR argument an object, this argument is
ignored. If the \fICipher\fR argument is a cipher class, either this
argument or \fIKey\fR must be provided.
.IP "\(bu" 4
Key
.Sp
A raw key, to be passed directly to the new cipher object. Because
this is passed directly to the cipher itself, the length of the
key must be equal to or greater than the keysize for the \fICipher\fR.
.Sp
As with the \fIPassphrase\fR argument, if you give the \fICipher\fR
argument an already-constructed cipher object, this argument is
ignored. If the \fICipher\fR argument is a cipher class, either this
argument or \fIPassphrase\fR must be provided.
.IP "\(bu" 4
\&\s-1IV\s0
.Sp
The initialization vector for \s-1CBC\s0 mode.
.Sp
This argument is optional; if not provided, a random \s-1IV\s0 will be
generated. Obviously, if you're decrypting data, you should provide
this argument, because your \s-1IV\s0 should match the \s-1IV\s0 used to encrypt
the data.
.ie n .SS "$cbc\->encrypt($plaintext)"
.el .SS "\f(CW$cbc\fP\->encrypt($plaintext)"
.IX Subsection "$cbc->encrypt($plaintext)"
Encrypts the plaintext \fI\f(CI$plaintext\fI\fR using the underlying cipher
implementation in \s-1CBC\s0 mode, and returns the ciphertext.
.PP
If any errors occur, returns \fIundef\fR, and you should check the
\&\fIerrstr\fR method to find out what went wrong.
.ie n .SS "$cbc\->decrypt($ciphertext)"
.el .SS "\f(CW$cbc\fP\->decrypt($ciphertext)"
.IX Subsection "$cbc->decrypt($ciphertext)"
Decrypts the ciphertext \fI\f(CI$ciphertext\fI\fR using the underlying
cipher implementation in \s-1CBC\s0 mode, and returns the plaintext.
.PP
If any errors occur, returns \fIundef\fR, and you should check the
\&\fIerrstr\fR method to find out what went wrong.
.ie n .SS "$cbc\->iv"
.el .SS "\f(CW$cbc\fP\->iv"
.IX Subsection "$cbc->iv"
Returns the current initialization vector. One use for this might be
to grab the initial value of the \s-1IV\s0 if it's created randomly (ie.
you haven't provided an \fI\s-1IV\s0\fR argument to \fInew\fR):
.PP
.Vb 2
\&    my $cbc = Convert::PEM::CBC\->new( Cipher => $cipher );
\&    my $iv = $cbc\->iv;   ## Generated randomly in \*(Aqnew\*(Aq.
.Ve
.PP
\&\fIConvert::PEM\fR uses this to write the \s-1IV\s0 to the \s-1PEM\s0 file when
encrypting, so that it can be known when trying to decrypt the
file.
.ie n .SS "$cbc\->errstr"
.el .SS "\f(CW$cbc\fP\->errstr"
.IX Subsection "$cbc->errstr"
Returns the value of the last error that occurred. This should only
be considered meaningful when you've received \fIundef\fR from one of
the functions above; in all other cases its relevance is undefined.
.SH "AUTHOR & COPYRIGHTS"
.IX Header "AUTHOR & COPYRIGHTS"
Please see the Convert::PEM manpage for author, copyright, and
license information.