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