Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Crypt::CBC.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CBC 3"
.TH CBC 3 "2002-09-11" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
Crypt::CBC \- Encrypt Data with Cipher Block Chaining Mode
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 8
\&  use Crypt::CBC;
\&  $cipher = Crypt::CBC->new( {'key'             => 'my secret key',
\&                              'cipher'          => 'Blowfish',
\&                              'iv'              => '$KJh#(}q',
\&                              'regenerate_key'  => 0,   # default true
\&                              'padding'         => 'space',
\&                              'prepend_iv'      => 0
\&                           });
.Ve
.PP
.Vb 2
\&  $ciphertext = $cipher->encrypt("This data is hush hush");
\&  $plaintext = $cipher->decrypt($ciphertext);
.Ve
.PP
.Vb 6
\&  $cipher->start('encrypting');
\&  open(F,"./BIG_FILE");
\&  while (read(F,$buffer,1024)) {
\&      print $cipher->crypt($buffer);
\&  }
\&  print $cipher->finish;
.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-1DES\s0 or \s-1IDEA\s0, you can encrypt and decrypt messages of arbitrarily long
length.  The encrypted messages are compatible with the encryption
format used by \fBSSLeay\fR.
.PP
To use this module, you will first create a Crypt::CBC cipher object with
\&\fInew()\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 \fIstart()\fR method to initialize the encryption or decryption
process, \fIcrypt()\fR to encrypt or decrypt one or more blocks of data, and
lastly \fIfinish()\fR, to pad and encrypt the final block.  For your
convenience, you can call the \fIencrypt()\fR and \fIdecrypt()\fR methods to
operate on a whole data value at once.
.Sh "\fInew()\fP"
.IX Subsection "new()"
.Vb 7
\&  $cipher = Crypt::CBC->new( {'key'             => 'my secret key',
\&                              'cipher'          => 'Blowfish',
\&                              'iv'              => '$KJh#(}q',
\&                              'regenerate_key'  => 0,   # default true
\&                              'padding'         => 'space',
\&                              'prepend_iv'      => 0
\&                           });
.Ve
.PP
.Vb 2
\&  # or (for compatibility with earlier versions)
\&  $cipher = new Crypt::CBC($key,$algorithm);
.Ve
.PP
The \fInew()\fR method creates a new Crypt::CBC object.  
.PP
You must provide an encryption/decryption key, which can be any series
of characters of any length.  If regenerate_key is not specified as a
false value, the actual key used is derived from the \s-1MD5\s0 hash of the
key you provide.  The cipher is optional and will default to \s-1DES\s0 unless
specified otherwise. You may use any compatible block encryption
algorithm that you have installed. Currently, this includes Crypt::DES,
Crypt::DES_EDE3, Crypt::IDEA, Crypt::Blowfish, and Crypt::Rijndael. You
may refer to them using their full names (\*(L"Crypt::IDEA\*(R") or in 
abbreviated form (\*(L"\s-1IDEA\s0\*(R").  
.PP
An initialization vector may be specified, either by passing in a key of
\&'iv' as an option to new, or by calling 
\&\f(CW$cipher\fR\->set_initialization_key($iv) before calling \f(CW$cipher\fR\->\fIstart()\fR.  
The \s-1IV\s0 will be ignored in decryption if the ciphertext is prepended by 
text which matches the regex /^RandomIV.{8}/, in which case the 8 
characters following \*(L"RandomIV\*(R" will be used as the \s-1IV\s0. When encrypting,
by default the ciphertext will be prepended with "RandomIV<\s-1IV\s0>\*(L"
(16 bytes). To disable this, set 'prepend_iv' to a false value. The 
padding method can be specified by the 'padding' option. If no padding 
method is specified, PKCS#5 (\*(R"standard") padding is assumed.
.Sh "\fIstart()\fP"
.IX Subsection "start()"
.Vb 2
\&   $cipher->start('encrypting');
\&   $cipher->start('decrypting');
.Ve
.PP
The \fIstart()\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.
.Sh "\fIcrypt()\fP"
.IX Subsection "crypt()"
.Vb 1
\&   $ciphertext = $cipher->crypt($plaintext);
.Ve
.PP
After calling \fIstart()\fR, you should call \fIcrypt()\fR as many times as
necessary to encrypt the desired data.  
.Sh "\fIfinish()\fP"
.IX Subsection "finish()"
.Vb 1
\&   $ciphertext = $cipher->finish();
.Ve
.PP
The \s-1CBC\s0 algorithm must buffer data blocks inernally until they are
even multiples of the encryption algorithm's blocksize (typically 8
bytes).  After the last call to \fIcrypt()\fR you should call \fIfinish()\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('hey jude!');
\&  $cipher->start('encrypting');
\&  print $cipher->crypt($_) while <>;
\&  print $cipher->finish();
.Ve
.Sh "\fIencrypt()\fP"
.IX Subsection "encrypt()"
.Vb 1
\&  $ciphertext = $cipher->encrypt($plaintext)
.Ve
.PP
This convenience function runs the entire sequence of \fIstart()\fR, \fIcrypt()\fR
and \fIfinish()\fR for you, processing the provided plaintext and returning
the corresponding ciphertext.
.Sh "\fIdecrypt()\fP"
.IX Subsection "decrypt()"
.Vb 1
\&  $plaintext = $cipher->decrypt($ciphertext)
.Ve
.PP
This convenience function runs the entire sequence of \fIstart()\fR, \fIcrypt()\fR
and \fIfinish()\fR for you, processing the provided ciphertext and returning
the corresponding plaintext.
.Sh "\fIencrypt_hex()\fP, \fIdecrypt_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
.Sh "\fIget_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.
This function may be useful to determine the random \s-1IV\s0 used when 
encrypting if none is specified in \fInew()\fR. The \s-1IV\s0 is not guaranteed to
be set when encrypting until \fIstart()\fR is called, and when decrypting 
until \fIcrypt()\fR is called the first time.
.Sh "\fIset_initialization_vector()\fP"
.IX Subsection "set_initialization_vector()"
.Vb 1
\&  $cipher->set_initialization_vector('76543210')
.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.
If not set, a random \s-1IV\s0 will be generated. The \s-1IV\s0 is not guaranteed to
be set when encrypting until \fIstart()\fR is called, and when decrypting
until \fIcrypt()\fR is called the first time.
.Sh "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", and \*(L"null\*(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.
.Ve
.PP
.Vb 4
\&   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.
.Ve
.PP
.Vb 4
\&   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.
.Ve
.PP
.Vb 2
\&   space: text only
\&      same as "null", but with "20".
.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 \fI_standard_padding()\fR, \fI_space_padding()\fR,
\&\fI_null_padding()\fR, or \fI_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 "EXAMPLES"
.IX Header "EXAMPLES"
Two examples, 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.
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
The encryption and decryption process is about a tenth the speed of
the equivalent SSLeay programs (compiled C).  This could be improved
by implementing this module in C.  It may also be worthwhile to
optimize the \s-1DES\s0 and \s-1IDEA\s0 block algorithms further.
.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\s0 \s-1LICENSE\s0 using the same
terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), \fICrypt::DES\fR\|(3), \fICrypt::IDEA\fR\|(3), rfc2898 (PKCS#5)