]>
Commit | Line | Data |
---|---|---|
997358a6 MW |
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_ecb3_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_ecb3_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_ecb3_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_ecb3_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@cryptsoft.com) |