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