secure/lib/libcrypto/man/des.3

   1 .\" Automatically generated by Pod::Man version 1.15
   2 .\" Wed Feb 19 16:43:04 2003
   3 .\"
   4 .\" Standard preamble:
   5 .\" ======================================================================
   6 .de Sh \" Subsection heading
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp \" Vertical space (when we can't use .PP)
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip \" List item
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb \" Begin verbatim text
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve \" End verbatim text
  30 .ft R
  31
  32 .fi
  33 ..
  34 .\" Set up some character translations and predefined strings.  \*(-- will
  35 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  36 .\" double quote, and \*(R" will give a right double quote.  | will give a
  37 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
  38 .\" to do unbreakable dashes and therefore won't be available.  \*(C` and
  39 .\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
  40 .tr \(*W-|\(bv\*(Tr
  41 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  42 .ie n \{\
  43 .    ds -- \(*W-
  44 .    ds PI pi
  45 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  46 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  47 .    ds L" ""
  48 .    ds R" ""
  49 .    ds C` ""
  50 .    ds C' ""
  51 'br\}
  52 .el\{\
  53 .    ds -- \|\(em\|
  54 .    ds PI \(*p
  55 .    ds L" ``
  56 .    ds R" ''
  57 'br\}
  58 .\"
  59 .\" If the F register is turned on, we'll generate index entries on stderr
  60 .\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
  61 .\" index entries marked with X<> in POD.  Of course, you'll have to process
  62 .\" the output yourself in some meaningful fashion.
  63 .if \nF \{\
  64 .    de IX
  65 .    tm Index:\\$1\t\\n%\t"\\$2"
  66 ..
  67 .    nr % 0
  68 .    rr F
  69 .\}
  70 .\"
  71 .\" For nroff, turn off justification.  Always turn off hyphenation; it
  72 .\" makes way too many mistakes in technical documents.
  73 .hy 0
  74 .if n .na
  75 .\"
  76 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  77 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  78 .bd B 3
  79 .    \" fudge factors for nroff and troff
  80 .if n \{\
  81 .    ds #H 0
  82 .    ds #V .8m
  83 .    ds #F .3m
  84 .    ds #[ \f1
  85 .    ds #] \fP
  86 .\}
  87 .if t \{\
  88 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  89 .    ds #V .6m
  90 .    ds #F 0
  91 .    ds #[ \&
  92 .    ds #] \&
  93 .\}
  94 .    \" simple accents for nroff and troff
  95 .if n \{\
  96 .    ds ' \&
  97 .    ds ` \&
  98 .    ds ^ \&
  99 .    ds , \&
 100 .    ds ~ ~
 101 .    ds /
 102 .\}
 103 .if t \{\
 104 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 105 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 106 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 107 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 108 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 109 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 110 .\}
 111 .    \" troff and (daisy-wheel) nroff accents
 112 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 113 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 114 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 115 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 116 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 117 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 118 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 119 .ds ae a\h'-(\w'a'u*4/10)'e
 120 .ds Ae A\h'-(\w'A'u*4/10)'E
 121 .    \" corrections for vroff
 122 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 123 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 124 .    \" for low resolution devices (crt and lpr)
 125 .if \n(.H>23 .if \n(.V>19 \
 126 \{\
 127 .    ds : e
 128 .    ds 8 ss
 129 .    ds o a
 130 .    ds d- d\h'-1'\(ga
 131 .    ds D- D\h'-1'\(hy
 132 .    ds th \o'bp'
 133 .    ds Th \o'LP'
 134 .    ds ae ae
 135 .    ds Ae AE
 136 .\}
 137 .rm #[ #] #H #V #F C
 138 .\" ======================================================================
 139 .\"
 140 .IX Title "des 3"
 141 .TH des 3 "0.9.7a" "2003-02-19" "OpenSSL"
 142 .UC
 143 .SH "NAME"
 144 DES_random_key, DES_set_key, DES_key_sched, DES_set_key_checked,
 145 DES_set_key_unchecked, DES_set_odd_parity, DES_is_weak_key,
 146 DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt,
 147 DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt,
 148 DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt,
 149 DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt,
 150 DES_ede3_cbcm_encrypt, DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt,
 151 DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys,
 152 DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write \- \s-1DES\s0 encryption
 153 .SH "SYNOPSIS"
 154 .IX Header "SYNOPSIS"
 155 .Vb 1
 156 \& #include <openssl/des.h>
 157 .Ve
 158 .Vb 1
 159 \& void DES_random_key(DES_cblock *ret);
 160 .Ve
 161 .Vb 6
 162 \& int DES_set_key(const_DES_cblock *key, DES_key_schedule *schedule);
 163 \& int DES_key_sched(const_DES_cblock *key, DES_key_schedule *schedule);
 164 \& int DES_set_key_checked(const_DES_cblock *key,
 165 \&        DES_key_schedule *schedule);
 166 \& void DES_set_key_unchecked(const_DES_cblock *key,
 167 \&        DES_key_schedule *schedule);
 168 .Ve
 169 .Vb 2
 170 \& void DES_set_odd_parity(DES_cblock *key);
 171 \& int DES_is_weak_key(const_DES_cblock *key);
 172 .Ve
 173 .Vb 7
 174 \& void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output,
 175 \&        DES_key_schedule *ks, int enc);
 176 \& void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output,
 177 \&        DES_key_schedule *ks1, DES_key_schedule *ks2, int enc);
 178 \& void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output,
 179 \&        DES_key_schedule *ks1, DES_key_schedule *ks2,
 180 \&        DES_key_schedule *ks3, int enc);
 181 .Ve
 182 .Vb 18
 183 \& void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output,
 184 \&        long length, DES_key_schedule *schedule, DES_cblock *ivec,
 185 \&        int enc);
 186 \& void DES_cfb_encrypt(const unsigned char *in, unsigned char *out,
 187 \&        int numbits, long length, DES_key_schedule *schedule,
 188 \&        DES_cblock *ivec, int enc);
 189 \& void DES_ofb_encrypt(const unsigned char *in, unsigned char *out,
 190 \&        int numbits, long length, DES_key_schedule *schedule,
 191 \&        DES_cblock *ivec);
 192 \& void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output,
 193 \&        long length, DES_key_schedule *schedule, DES_cblock *ivec,
 194 \&        int enc);
 195 \& void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out,
 196 \&        long length, DES_key_schedule *schedule, DES_cblock *ivec,
 197 \&        int *num, int enc);
 198 \& void DES_ofb64_encrypt(const unsigned char *in, unsigned char *out,
 199 \&        long length, DES_key_schedule *schedule, DES_cblock *ivec,
 200 \&        int *num);
 201 .Ve
 202 .Vb 3
 203 \& void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output,
 204 \&        long length, DES_key_schedule *schedule, DES_cblock *ivec,
 205 \&        const_DES_cblock *inw, const_DES_cblock *outw, int enc);
 206 .Ve
 207 .Vb 9
 208 \& void DES_ede2_cbc_encrypt(const unsigned char *input,
 209 \&        unsigned char *output, long length, DES_key_schedule *ks1,
 210 \&        DES_key_schedule *ks2, DES_cblock *ivec, int enc);
 211 \& void DES_ede2_cfb64_encrypt(const unsigned char *in,
 212 \&        unsigned char *out, long length, DES_key_schedule *ks1,
 213 \&        DES_key_schedule *ks2, DES_cblock *ivec, int *num, int enc);
 214 \& void DES_ede2_ofb64_encrypt(const unsigned char *in,
 215 \&        unsigned char *out, long length, DES_key_schedule *ks1,
 216 \&        DES_key_schedule *ks2, DES_cblock *ivec, int *num);
 217 .Ve
 218 .Vb 15
 219 \& void DES_ede3_cbc_encrypt(const unsigned char *input,
 220 \&        unsigned char *output, long length, DES_key_schedule *ks1,
 221 \&        DES_key_schedule *ks2, DES_key_schedule *ks3, DES_cblock *ivec,
 222 \&        int enc);
 223 \& void DES_ede3_cbcm_encrypt(const unsigned char *in, unsigned char *out,
 224 \&        long length, DES_key_schedule *ks1, DES_key_schedule *ks2,
 225 \&        DES_key_schedule *ks3, DES_cblock *ivec1, DES_cblock *ivec2,
 226 \&        int enc);
 227 \& void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out,
 228 \&        long length, DES_key_schedule *ks1, DES_key_schedule *ks2,
 229 \&        DES_key_schedule *ks3, DES_cblock *ivec, int *num, int enc);
 230 \& void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out,
 231 \&        long length, DES_key_schedule *ks1,
 232 \&        DES_key_schedule *ks2, DES_key_schedule *ks3,
 233 \&        DES_cblock *ivec, int *num);
 234 .Ve
 235 .Vb 8
 236 \& DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output,
 237 \&        long length, DES_key_schedule *schedule,
 238 \&        const_DES_cblock *ivec);
 239 \& DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[],
 240 \&        long length, int out_count, DES_cblock *seed);
 241 \& void DES_string_to_key(const char *str, DES_cblock *key);
 242 \& void DES_string_to_2keys(const char *str, DES_cblock *key1,
 243 \&        DES_cblock *key2);
 244 .Ve
 245 .Vb 2
 246 \& char *DES_fcrypt(const char *buf, const char *salt, char *ret);
 247 \& char *DES_crypt(const char *buf, const char *salt);
 248 .Ve
 249 .Vb 4
 250 \& int DES_enc_read(int fd, void *buf, int len, DES_key_schedule *sched,
 251 \&        DES_cblock *iv);
 252 \& int DES_enc_write(int fd, const void *buf, int len,
 253 \&        DES_key_schedule *sched, DES_cblock *iv);
 254 .Ve
 255 .SH "DESCRIPTION"
 256 .IX Header "DESCRIPTION"
 257 This library contains a fast implementation of the \s-1DES\s0 encryption
 258 algorithm.
 259 .PP
 260 There are two phases to the use of \s-1DES\s0 encryption.  The first is the
 261 generation of a \fIDES_key_schedule\fR from a key, the second is the
 262 actual encryption.  A \s-1DES\s0 key is of type \fIDES_cblock\fR. This type is
 263 consists of 8 bytes with odd parity.  The least significant bit in
 264 each byte is the parity bit.  The key schedule is an expanded form of
 265 the key; it is used to speed the encryption process.
 266 .PP
 267 \&\fIDES_random_key()\fR generates a random key.  The \s-1PRNG\s0 must be seeded
 268 prior to using this function (see rand(3)).  If the \s-1PRNG\s0
 269 could not generate a secure key, 0 is returned.
 270 .PP
 271 Before a \s-1DES\s0 key can be used, it must be converted into the
 272 architecture dependent \fIDES_key_schedule\fR via the
 273 \&\fIDES_set_key_checked()\fR or \fIDES_set_key_unchecked()\fR function.
 274 .PP
 275 \&\fIDES_set_key_checked()\fR will check that the key passed is of odd parity
 276 and is not a week or semi-weak key.  If the parity is wrong, then \-1
 277 is returned.  If the key is a weak key, then \-2 is returned.  If an
 278 error is returned, the key schedule is not generated.
 279 .PP
 280 \&\fIDES_set_key()\fR works like
 281 \&\fIDES_set_key_checked()\fR if the \fIDES_check_key\fR flag is non-zero,
 282 otherwise like \fIDES_set_key_unchecked()\fR.  These functions are available
 283 for compatibility; it is recommended to use a function that does not
 284 depend on a global variable.
 285 .PP
 286 \&\fIDES_set_odd_parity()\fR sets the parity of the passed \fIkey\fR to odd.
 287 .PP
 288 \&\fIDES_is_weak_key()\fR returns 1 is the passed key is a weak key, 0 if it
 289 is ok.  The probability that a randomly generated key is weak is
 290 1/2^52, so it is not really worth checking for them.
 291 .PP
 292 The following routines mostly operate on an input and output stream of
 293 \&\fIDES_cblock\fRs.
 294 .PP
 295 \&\fIDES_ecb_encrypt()\fR is the basic \s-1DES\s0 encryption routine that encrypts or
 296 decrypts a single 8\-byte \fIDES_cblock\fR in \fIelectronic code book\fR
 297 (\s-1ECB\s0) mode.  It always transforms the input data, pointed to by
 298 \&\fIinput\fR, into the output data, pointed to by the \fIoutput\fR argument.
 299 If the \fIencrypt\fR argument is non-zero (\s-1DES_ENCRYPT\s0), the \fIinput\fR
 300 (cleartext) is encrypted in to the \fIoutput\fR (ciphertext) using the
 301 key_schedule specified by the \fIschedule\fR argument, previously set via
 302 \&\fIDES_set_key\fR. If \fIencrypt\fR is zero (\s-1DES_DECRYPT\s0), the \fIinput\fR (now
 303 ciphertext) is decrypted into the \fIoutput\fR (now cleartext).  Input
 304 and output may overlap.  \fIDES_ecb_encrypt()\fR does not return a value.
 305 .PP
 306 \&\fIDES_ecb3_encrypt()\fR encrypts/decrypts the \fIinput\fR block by using
 307 three-key Triple-DES encryption in \s-1ECB\s0 mode.  This involves encrypting
 308 the input with \fIks1\fR, decrypting with the key schedule \fIks2\fR, and
 309 then encrypting with \fIks3\fR.  This routine greatly reduces the chances
 310 of brute force breaking of \s-1DES\s0 and has the advantage of if \fIks1\fR,
 311 \&\fIks2\fR and \fIks3\fR are the same, it is equivalent to just encryption
 312 using \s-1ECB\s0 mode and \fIks1\fR as the key.
 313 .PP
 314 The macro \fIDES_ecb2_encrypt()\fR is provided to perform two-key Triple-DES
 315 encryption by using \fIks1\fR for the final encryption.
 316 .PP
 317 \&\fIDES_ncbc_encrypt()\fR encrypts/decrypts using the \fIcipher-block-chaining\fR
 318 (\s-1CBC\s0) mode of \s-1DES\s0.  If the \fIencrypt\fR argument is non-zero, the
 319 routine cipher-block-chain encrypts the cleartext data pointed to by
 320 the \fIinput\fR argument into the ciphertext pointed to by the \fIoutput\fR
 321 argument, using the key schedule provided by the \fIschedule\fR argument,
 322 and initialization vector provided by the \fIivec\fR argument.  If the
 323 \&\fIlength\fR argument is not an integral multiple of eight bytes, the
 324 last block is copied to a temporary area and zero filled.  The output
 325 is always an integral multiple of eight bytes.
 326 .PP
 327 \&\fIDES_xcbc_encrypt()\fR is \s-1RSA\s0's \s-1DESX\s0 mode of \s-1DES\s0.  It uses \fIinw\fR and
 328 \&\fIoutw\fR to 'whiten' the encryption.  \fIinw\fR and \fIoutw\fR are secret
 329 (unlike the iv) and are as such, part of the key.  So the key is sort
 330 of 24 bytes.  This is much better than \s-1CBC\s0 \s-1DES\s0.
 331 .PP
 332 \&\fIDES_ede3_cbc_encrypt()\fR implements outer triple \s-1CBC\s0 \s-1DES\s0 encryption with
 333 three keys. This means that each \s-1DES\s0 operation inside the \s-1CBC\s0 mode is
 334 really an \f(CW\*(C`C=E(ks3,D(ks2,E(ks1,M)))\*(C'\fR.  This mode is used by \s-1SSL\s0.
 335 .PP
 336 The \fIDES_ede2_cbc_encrypt()\fR macro implements two-key Triple-DES by
 337 reusing \fIks1\fR for the final encryption.  \f(CW\*(C`C=E(ks1,D(ks2,E(ks1,M)))\*(C'\fR.
 338 This form of Triple-DES is used by the \s-1RSAREF\s0 library.
 339 .PP
 340 \&\fIDES_pcbc_encrypt()\fR encrypt/decrypts using the propagating cipher block
 341 chaining mode used by Kerberos v4. Its parameters are the same as
 342 \&\fIDES_ncbc_encrypt()\fR.
 343 .PP
 344 \&\fIDES_cfb_encrypt()\fR encrypt/decrypts using cipher feedback mode.  This
 345 method takes an array of characters as input and outputs and array of
 346 characters.  It does not require any padding to 8 character groups.
 347 Note: the \fIivec\fR variable is changed and the new changed value needs to
 348 be passed to the next call to this function.  Since this function runs
 349 a complete \s-1DES\s0 \s-1ECB\s0 encryption per \fInumbits\fR, this function is only
 350 suggested for use when sending small numbers of characters.
 351 .PP
 352 \&\fIDES_cfb64_encrypt()\fR
 353 implements \s-1CFB\s0 mode of \s-1DES\s0 with 64bit feedback.  Why is this
 354 useful you ask?  Because this routine will allow you to encrypt an
 355 arbitrary number of bytes, no 8 byte padding.  Each call to this
 356 routine will encrypt the input bytes to output and then update ivec
 357 and num.  num contains 'how far' we are though ivec.  If this does
 358 not make much sense, read more about cfb mode of \s-1DES\s0 :\-).
 359 .PP
 360 \&\fIDES_ede3_cfb64_encrypt()\fR and \fIDES_ede2_cfb64_encrypt()\fR is the same as
 361 \&\fIDES_cfb64_encrypt()\fR except that Triple-DES is used.
 362 .PP
 363 \&\fIDES_ofb_encrypt()\fR encrypts using output feedback mode.  This method
 364 takes an array of characters as input and outputs and array of
 365 characters.  It does not require any padding to 8 character groups.
 366 Note: the \fIivec\fR variable is changed and the new changed value needs to
 367 be passed to the next call to this function.  Since this function runs
 368 a complete \s-1DES\s0 \s-1ECB\s0 encryption per numbits, this function is only
 369 suggested for use when sending small numbers of characters.
 370 .PP
 371 \&\fIDES_ofb64_encrypt()\fR is the same as \fIDES_cfb64_encrypt()\fR using Output
 372 Feed Back mode.
 373 .PP
 374 \&\fIDES_ede3_ofb64_encrypt()\fR and \fIDES_ede2_ofb64_encrypt()\fR is the same as
 375 \&\fIDES_ofb64_encrypt()\fR, using Triple-DES.
 376 .PP
 377 The following functions are included in the \s-1DES\s0 library for
 378 compatibility with the \s-1MIT\s0 Kerberos library.
 379 .PP
 380 \&\fIDES_cbc_cksum()\fR produces an 8 byte checksum based on the input stream
 381 (via \s-1CBC\s0 encryption).  The last 4 bytes of the checksum are returned
 382 and the complete 8 bytes are placed in \fIoutput\fR. This function is
 383 used by Kerberos v4.  Other applications should use
 384 EVP_DigestInit(3) etc. instead.
 385 .PP
 386 \&\fIDES_quad_cksum()\fR is a Kerberos v4 function.  It returns a 4 byte
 387 checksum from the input bytes.  The algorithm can be iterated over the
 388 input, depending on \fIout_count\fR, 1, 2, 3 or 4 times.  If \fIoutput\fR is
 389 non-NULL, the 8 bytes generated by each pass are written into
 390 \&\fIoutput\fR.
 391 .PP
 392 The following are DES-based transformations:
 393 .PP
 394 \&\fIDES_fcrypt()\fR is a fast version of the Unix \fIcrypt\fR\|(3) function.  This
 395 version takes only a small amount of space relative to other fast
 396 \&\fIcrypt()\fR implementations.  This is different to the normal crypt in
 397 that the third parameter is the buffer that the return value is
 398 written into.  It needs to be at least 14 bytes long.  This function
 399 is thread safe, unlike the normal crypt.
 400 .PP
 401 \&\fIDES_crypt()\fR is a faster replacement for the normal system \fIcrypt()\fR.
 402 This function calls \fIDES_fcrypt()\fR with a static array passed as the
 403 third parameter.  This emulates the normal non-thread safe semantics
 404 of \fIcrypt\fR\|(3).
 405 .PP
 406 \&\fIDES_enc_write()\fR writes \fIlen\fR bytes to file descriptor \fIfd\fR from
 407 buffer \fIbuf\fR. The data is encrypted via \fIpcbc_encrypt\fR (default)
 408 using \fIsched\fR for the key and \fIiv\fR as a starting vector.  The actual
 409 data send down \fIfd\fR consists of 4 bytes (in network byte order)
 410 containing the length of the following encrypted data.  The encrypted
 411 data then follows, padded with random data out to a multiple of 8
 412 bytes.
 413 .PP
 414 \&\fIDES_enc_read()\fR is used to read \fIlen\fR bytes from file descriptor
 415 \&\fIfd\fR into buffer \fIbuf\fR. The data being read from \fIfd\fR is assumed to
 416 have come from \fIDES_enc_write()\fR and is decrypted using \fIsched\fR for
 417 the key schedule and \fIiv\fR for the initial vector.
 418 .PP
 419 \&\fBWarning:\fR The data format used by \fIDES_enc_write()\fR and \fIDES_enc_read()\fR
 420 has a cryptographic weakness: When asked to write more than \s-1MAXWRITE\s0
 421 bytes, \fIDES_enc_write()\fR will split the data into several chunks that
 422 are all encrypted using the same \s-1IV\s0.  So don't use these functions
 423 unless you are sure you know what you do (in which case you might not
 424 want to use them anyway).  They cannot handle non-blocking sockets.
 425 \&\fIDES_enc_read()\fR uses an internal state and thus cannot be used on
 426 multiple files.
 427 .PP
 428 \&\fIDES_rw_mode\fR is used to specify the encryption mode to use with
 429 \&\fIDES_enc_read()\fR and \fIDES_end_write()\fR.  If set to \fI\s-1DES_PCBC_MODE\s0\fR (the
 430 default), DES_pcbc_encrypt is used.  If set to \fI\s-1DES_CBC_MODE\s0\fR
 431 DES_cbc_encrypt is used.
 432 .SH "NOTES"
 433 .IX Header "NOTES"
 434 Single-key \s-1DES\s0 is insecure due to its short key size.  \s-1ECB\s0 mode is
 435 not suitable for most applications; see DES_modes(7).
 436 .PP
 437 The evp(3) library provides higher-level encryption functions.
 438 .SH "BUGS"
 439 .IX Header "BUGS"
 440 \&\fIDES_3cbc_encrypt()\fR is flawed and must not be used in applications.
 441 .PP
 442 \&\fIDES_cbc_encrypt()\fR does not modify \fBivec\fR; use \fIDES_ncbc_encrypt()\fR
 443 instead.
 444 .PP
 445 \&\fIDES_cfb_encrypt()\fR and \fIDES_ofb_encrypt()\fR operates on input of 8 bits.
 446 What this means is that if you set numbits to 12, and length to 2, the
 447 first 12 bits will come from the 1st input byte and the low half of
 448 the second input byte.  The second 12 bits will have the low 8 bits
 449 taken from the 3rd input byte and the top 4 bits taken from the 4th
 450 input byte.  The same holds for output.  This function has been
 451 implemented this way because most people will be using a multiple of 8
 452 and because once you get into pulling bytes input bytes apart things
 453 get ugly!
 454 .PP
 455 \&\fIDES_string_to_key()\fR is available for backward compatibility with the
 456 \&\s-1MIT\s0 library.  New applications should use a cryptographic hash function.
 457 The same applies for \fIDES_string_to_2key()\fR.
 458 .SH "CONFORMING TO"
 459 .IX Header "CONFORMING TO"
 460 \&\s-1ANSI\s0 X3.106
 461 .PP
 462 The \fBdes\fR library was written to be source code compatible with
 463 the \s-1MIT\s0 Kerberos library.
 464 .SH "SEE ALSO"
 465 .IX Header "SEE ALSO"
 466 \&\fIcrypt\fR\|(3), des_modes(7), evp(3), rand(3)
 467 .SH "HISTORY"
 468 .IX Header "HISTORY"
 469 In OpenSSL 0.9.7, all des_ functions were renamed to \s-1DES_\s0 to avoid
 470 clashes with older versions of libdes.  Compatibility des_ functions
 471 are provided for a short while, as well as \fIcrypt()\fR.
 472 Declarations for these are in <openssl/des_old.h>. There is no \s-1DES_\s0
 473 variant for \fIdes_random_seed()\fR.
 474 This will happen to other functions
 475 as well if they are deemed redundant (\fIdes_random_seed()\fR just calls
 476 \&\fIRAND_seed()\fR and is present for backward compatibility only), buggy or
 477 already scheduled for removal.
 478 .PP
 479 \&\fIdes_cbc_cksum()\fR, \fIdes_cbc_encrypt()\fR, \fIdes_ecb_encrypt()\fR,
 480 \&\fIdes_is_weak_key()\fR, \fIdes_key_sched()\fR, \fIdes_pcbc_encrypt()\fR,
 481 \&\fIdes_quad_cksum()\fR, \fIdes_random_key()\fR and \fIdes_string_to_key()\fR
 482 are available in the \s-1MIT\s0 Kerberos library;
 483 \&\fIdes_check_key_parity()\fR, \fIdes_fixup_key_parity()\fR and \fIdes_is_weak_key()\fR
 484 are available in newer versions of that library.
 485 .PP
 486 \&\fIdes_set_key_checked()\fR and \fIdes_set_key_unchecked()\fR were added in
 487 OpenSSL 0.9.5.
 488 .PP
 489 \&\fIdes_generate_random_block()\fR, \fIdes_init_random_number_generator()\fR,
 490 \&\fIdes_new_random_key()\fR, \fIdes_set_random_generator_seed()\fR and
 491 \&\fIdes_set_sequence_number()\fR and \fIdes_rand_data()\fR are used in newer
 492 versions of Kerberos but are not implemented here.
 493 .PP
 494 \&\fIdes_random_key()\fR generated cryptographically weak random data in
 495 SSLeay and in OpenSSL prior version 0.9.5, as well as in the original
 496 \&\s-1MIT\s0 library.
 497 .SH "AUTHOR"
 498 .IX Header "AUTHOR"
 499 Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project
 500 (http://www.openssl.org).