| blob | 9feb447129ebabacfe413b852cb8e4f01ed805de |
1 .TH DES_CRYPT 3
2 .SH NAME
3 des_read_password, des_read_2password,
4 des_string_to_key, des_string_to_2key, des_read_pw_string,
5 des_random_key, des_set_key,
6 des_key_sched, des_ecb_encrypt, des_3ecb_encrypt, des_cbc_encrypt,
7 des_3cbc_encrypt,
8 des_pcbc_encrypt, des_cfb_encrypt, des_ofb_encrypt,
9 des_cbc_cksum, des_quad_cksum,
10 des_enc_read, des_enc_write, des_set_odd_parity,
11 des_is_weak_key, crypt \- (non USA) DES encryption
12 .SH SYNOPSIS
13 .nf
14 .nj
15 .ft B
16 #include <des.h>
17 .PP
18 .B int des_read_password(key,prompt,verify)
19 des_cblock *key;
20 char *prompt;
21 int verify;
22 .PP
23 .B int des_read_2password(key1,key2,prompt,verify)
24 des_cblock *key1,*key2;
25 char *prompt;
26 int verify;
27 .PP
28 .B int des_string_to_key(str,key)
29 char *str;
30 des_cblock *key;
31 .PP
32 .B int des_string_to_2keys(str,key1,key2)
33 char *str;
34 des_cblock *key1,*key2;
35 .PP
36 .B int des_read_pw_string(buf,length,prompt,verify)
37 char *buf;
38 int length;
39 char *prompt;
40 int verify;
41 .PP
42 .B int des_random_key(key)
43 des_cblock *key;
44 .PP
45 .B int des_set_key(key,schedule)
46 des_cblock *key;
47 des_key_schedule schedule;
48 .PP
49 .B int des_key_sched(key,schedule)
50 des_cblock *key;
51 des_key_schedule schedule;
52 .PP
53 .B int des_ecb_encrypt(input,output,schedule,encrypt)
54 des_cblock *input;
55 des_cblock *output;
56 des_key_schedule schedule;
57 int encrypt;
58 .PP
59 .B int des_3ecb_encrypt(input,output,ks1,ks2,encrypt)
60 des_cblock *input;
61 des_cblock *output;
62 des_key_schedule ks1,ks2;
63 int encrypt;
64 .PP
65 .B int des_cbc_encrypt(input,output,length,schedule,ivec,encrypt)
66 des_cblock *input;
67 des_cblock *output;
68 long length;
69 des_key_schedule schedule;
70 des_cblock *ivec;
71 int encrypt;
72 .PP
73 .B int des_3cbc_encrypt(input,output,length,sk1,sk2,ivec1,ivec2,encrypt)
74 des_cblock *input;
75 des_cblock *output;
76 long length;
77 des_key_schedule sk1;
78 des_key_schedule sk2;
79 des_cblock *ivec1;
80 des_cblock *ivec2;
81 int encrypt;
82 .PP
83 .B int des_pcbc_encrypt(input,output,length,schedule,ivec,encrypt)
84 des_cblock *input;
85 des_cblock *output;
86 long length;
87 des_key_schedule schedule;
88 des_cblock *ivec;
89 int encrypt;
90 .PP
91 .B int des_cfb_encrypt(input,output,numbits,length,schedule,ivec,encrypt)
92 unsigned char *input;
93 unsigned char *output;
94 int numbits;
95 long length;
96 des_key_schedule schedule;
97 des_cblock *ivec;
98 int encrypt;
99 .PP
100 .B int des_ofb_encrypt(input,output,numbits,length,schedule,ivec)
101 unsigned char *input,*output;
102 int numbits;
103 long length;
104 des_key_schedule schedule;
105 des_cblock *ivec;
106 .PP
107 .B unsigned long des_cbc_cksum(input,output,length,schedule,ivec)
108 des_cblock *input;
109 des_cblock *output;
110 long length;
111 des_key_schedule schedule;
112 des_cblock *ivec;
113 .PP
114 .B unsigned long des_quad_cksum(input,output,length,out_count,seed)
115 des_cblock *input;
116 des_cblock *output;
117 long length;
118 int out_count;
119 des_cblock *seed;
120 .PP
121 .B int des_check_key;
122 .PP
123 .B int des_enc_read(fd,buf,len,sched,iv)
124 int fd;
125 char *buf;
126 int len;
127 des_key_schedule sched;
128 des_cblock *iv;
129 .PP
130 .B int des_enc_write(fd,buf,len,sched,iv)
131 int fd;
132 char *buf;
133 int len;
134 des_key_schedule sched;
135 des_cblock *iv;
136 .PP
137 .B extern int des_rw_mode;
138 .PP
139 .B void des_set_odd_parity(key)
140 des_cblock *key;
141 .PP
142 .B int des_is_weak_key(key)
143 des_cblock *key;
144 .PP
145 .B char *crypt(passwd,salt)
146 char *passwd;
147 char *salt;
148 .PP
149 .fi
150 .SH DESCRIPTION
151 This library contains a fast implementation of the DES encryption
152 algorithm.
153 .PP
154 There are two phases to the use of DES encryption.
155 The first is the generation of a
156 .I des_key_schedule
157 from a key,
158 the second is the actual encryption.
159 A des key is of type
160 .I des_cblock.
161 This type is made from 8 characters with odd parity.
162 The least significant bit in the character is the parity bit.
163 The key schedule is an expanded form of the key; it is used to speed the
164 encryption process.
165 .PP
166 .I des_read_password
167 writes the string specified by prompt to the standard output,
168 turns off echo and reads an input string from standard input
169 until terminated with a newline.
170 If verify is non-zero, it prompts and reads the input again and verifies
171 that both entered passwords are the same.
172 The entered string is converted into a des key by using the
173 .I des_string_to_key
174 routine.
175 The new key is placed in the
176 .I des_cblock
177 that was passed (by reference) to the routine.
178 If there were no errors,
179 .I des_read_password
180 returns 0,
181 -1 is returned if there was a terminal error and 1 is returned for
182 any other error.
183 .PP
184 .I des_read_2password
185 operates in the same way as
186 .I des_read_password
187 except that it generates 2 keys by using the
188 .I des_string_to_2key
189 function.
190 .PP
191 .I des_read_pw_string
192 is called by
193 .I des_read_password
194 to read and verify a string from a terminal device.
195 The string is returned in
196 .I buf.
197 The size of
198 .I buf
199 is passed to the routine via the
200 .I length
201 parameter.
202 .PP
203 .I des_string_to_key
204 converts a string into a valid des key.
205 .PP
206 .I des_string_to_2key
207 converts a string into 2 valid des keys.
208 This routine is best suited for used to generate keys for use with
209 .I des_3ecb_encrypt.
210 .PP
211 .I des_random_key
212 returns a random key that is made of a combination of process id,
213 time and an increasing counter.
214 .PP
215 Before a des key can be used it is converted into a
216 .I des_key_schedule
217 via the
218 .I des_set_key
219 routine.
220 If the
221 .I des_check_key
222 flag is non-zero,
223 .I des_set_key
224 will check that the key passed is of odd parity and is not a week or
225 semi-weak key.
226 If the parity is wrong,
227 then -1 is returned.
228 If the key is a weak key,
229 then -2 is returned.
230 If an error is returned,
231 the key schedule is not generated.
232 .PP
233 .I des_key_sched
234 is another name for the
235 .I des_set_key
236 function.
237 .PP
238 The following routines mostly operate on an input and output stream of
239 .I des_cblock's.
240 .PP
241 .I des_ecb_encrypt
242 is the basic DES encryption routine that encrypts or decrypts a single 8-byte
243 .I des_cblock
244 in
245 .I electronic code book
246 mode.
247 It always transforms the input data, pointed to by
248 .I input,
249 into the output data,
250 pointed to by the
251 .I output
252 argument.
253 If the
254 .I encrypt
255 argument is non-zero (DES_ENCRYPT),
256 the
257 .I input
258 (cleartext) is encrypted in to the
259 .I output
260 (ciphertext) using the key_schedule specified by the
261 .I schedule
262 argument,
263 previously set via
264 .I des_set_key.
265 If
266 .I encrypt
267 is zero (DES_DECRYPT),
268 the
269 .I input
270 (now ciphertext)
271 is decrypted into the
272 .I output
273 (now cleartext).
274 Input and output may overlap.
275 No meaningful value is returned.
276 .PP
277 .I des_3ecb_encrypt
278 encrypts/decrypts the
279 .I input
280 block by using triple ecb DES encryption.
281 This involves encrypting the input with
282 .I ks1,
283 decryption with the key schedule
284 .I ks2,
285 and then encryption with the first again.
286 This routine greatly reduces the chances of brute force breaking of
287 DES and has the advantage of if
288 .I ks1
289 and
290 .I ks2
291 are the same, it is equivalent to just encryption using ecb mode and
292 .I ks1
293 as the key.
294 .PP
295 .I des_cbc_encrypt
296 encrypts/decrypts using the
297 .I cipher-block-chaining
298 mode of DES.
299 If the
300 .I encrypt
301 argument is non-zero,
302 the routine cipher-block-chain encrypts the cleartext data pointed to by the
303 .I input
304 argument into the ciphertext pointed to by the
305 .I output
306 argument,
307 using the key schedule provided by the
308 .I schedule
309 argument,
310 and initialisation vector provided by the
311 .I ivec
312 argument.
313 If the
314 .I length
315 argument is not an integral multiple of eight bytes,
316 the last block is copied to a temporary area and zero filled.
317 The output is always
318 an integral multiple of eight bytes.
319 To make multiple cbc encrypt calls on a large amount of data appear to
320 be one
321 .I des_cbc_encrypt
322 call, the
323 .I ivec
324 of subsequent calls should be the last 8 bytes of the output.
325 .PP
326 .I des_3cbc_encrypt
327 encrypts/decrypts the
328 .I input
329 block by using triple cbc DES encryption.
330 This involves encrypting the input with key schedule
331 .I ks1,
332 decryption with the key schedule
333 .I ks2,
334 and then encryption with the first again.
335 2 initialisation vectors are required,
336 .I ivec1
337 and
338 .I ivec2.
339 Unlike
340 .I des_cbc_encrypt,
341 these initialisation vectors are modified by the subroutine.
342 This routine greatly reduces the chances of brute force breaking of
343 DES and has the advantage of if
344 .I ks1
345 and
346 .I ks2
347 are the same, it is equivalent to just encryption using cbc mode and
348 .I ks1
349 as the key.
350 .PP
351 .I des_pcbc_encrypt
352 encrypt/decrypts using a modified block chaining mode.
353 It provides better error propagation characteristics than cbc
354 encryption.
355 .PP
356 .I des_cfb_encrypt
357 encrypt/decrypts using cipher feedback mode. This method takes an
358 array of characters as input and outputs and array of characters. It
359 does not require any padding to 8 character groups. Note: the ivec
360 variable is changed and the new changed value needs to be passed to
361 the next call to this function. Since this function runs a complete
362 DES ecb encryption per numbits, this function is only suggested for
363 use when sending small numbers of characters.
364 .PP
365 .I des_ofb_encrypt
366 encrypt using output feedback mode. This method takes an
367 array of characters as input and outputs and array of characters. It
368 does not require any padding to 8 character groups. Note: the ivec
369 variable is changed and the new changed value needs to be passed to
370 the next call to this function. Since this function runs a complete
371 DES ecb encryption per numbits, this function is only suggested for
372 use when sending small numbers of characters.
373 .PP
374 .I des_cbc_cksum
375 produces an 8 byte checksum based on the input stream (via cbc encryption).
376 The last 4 bytes of the checksum is returned and the complete 8 bytes is
377 placed in
378 .I output.
379 .PP
380 .I des_quad_cksum
381 returns a 4 byte checksum from the input bytes.
382 The algorithm can be iterated over the input,
383 depending on
384 .I out_count,
385 1, 2, 3 or 4 times.
386 If
387 .I output
388 is non-NULL,
389 the 8 bytes generated by each pass are written into
390 .I output.
391 .PP
392 .I des_enc_write
393 is used to write
394 .I len
395 bytes
396 to file descriptor
397 .I fd
398 from buffer
399 .I buf.
400 The data is encrypted via
401 .I pcbc_encrypt
402 (default) using
403 .I sched
404 for the key and
405 .I iv
406 as a starting vector.
407 The actual data send down
408 .I fd
409 consists of 4 bytes (in network byte order) containing the length of the
410 following encrypted data. The encrypted data then follows, padded with random
411 data out to a multiple of 8 bytes.
412 .PP
413 .I des_enc_read
414 is used to read
415 .I len
416 bytes
417 from file descriptor
418 .I fd
419 into buffer
420 .I buf.
421 The data being read from
422 .I fd
423 is assumed to have come from
424 .I des_enc_write
425 and is decrypted using
426 .I sched
427 for the key schedule and
428 .I iv
429 for the initial vector.
430 The
431 .I des_enc_read/des_enc_write
432 pair can be used to read/write to files, pipes and sockets.
433 I have used them in implementing a version of rlogin in which all
434 data is encrypted.
435 .PP
436 .I des_rw_mode
437 is used to specify the encryption mode to use with
438 .I des_enc_read
439 and
440 .I des_end_write.
441 If set to
442 .I DES_PCBC_MODE
443 (the default), des_pcbc_encrypt is used.
444 If set to
445 .I DES_CBC_MODE
446 des_cbc_encrypt is used.
447 These two routines and the variable are not part of the normal MIT library.
448 .PP
449 .I des_set_odd_parity
450 sets the parity of the passed
451 .I key
452 to odd. This routine is not part of the standard MIT library.
453 .PP
454 .I des_is_weak_key
455 returns 1 is the passed key is a weak key (pick again :-),
456 0 if it is ok.
457 This routine is not part of the standard MIT library.
458 .PP
459 .I crypt
460 is a replacement for the normal system crypt.
461 It is much faster than the system crypt.
462 .PP
463 .SH FILES
464 /usr/include/des.h
465 .br
466 /usr/lib/libdes.a
467 .PP
468 The encryption routines have been tested on 16bit, 32bit and 64bit
469 machines of various endian and even works under VMS.
470 .PP
471 .SH BUGS
472 .PP
473 If you think this manual is sparse,
474 read the des_crypt(3) manual from the MIT kerberos (or bones outside
475 of the USA) distribution.
476 .PP
477 .I des_cfb_encrypt
478 and
479 .I des_ofb_encrypt
480 operates on input of 8 bits. What this means is that if you set
481 numbits to 12, and length to 2, the first 12 bits will come from the 1st
482 input byte and the low half of the second input byte. The second 12
483 bits will have the low 8 bits taken from the 3rd input byte and the
484 top 4 bits taken from the 4th input byte. The same holds for output.
485 This function has been implemented this way because most people will
486 be using a multiple of 8 and because once you get into pulling bytes input
487 bytes apart things get ugly!
488 .PP
489 .I des_read_pw_string
490 is the most machine/OS dependent function and normally generates the
491 most problems when porting this code.
492 .PP
493 .I des_string_to_key
494 is probably different from the MIT version since there are lots
495 of fun ways to implement one-way encryption of a text string.
496 .PP
497 The routines are optimised for 32 bit machines and so are not efficient
498 on IBM PCs.
499 .PP
500 NOTE: extensive work has been done on this library since this document
501 was origionally written. Please try to read des.doc from the libdes
502 distribution since it is far more upto date and documents more of the
503 functions. Libdes is now also being shipped as part of SSLeay, a
504 general cryptographic library that amonst other things implements
505 netscapes SSL protocoll. The most recent version can be found in
506 SSLeay distributions.
507 .SH AUTHOR
508 Eric Young (eay@mincom.oz.au or eay@psych.psy.uq.oz.au)