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