]>
Commit | Line | Data |
---|---|---|
997358a6 MW |
1 | The DES library. |
2 | ||
3 | Please note that this library was originally written to operate with | |
4 | eBones, a version of Kerberos that had had encryption removed when it left | |
5 | the USA and then put back in. As such there are some routines that I will | |
6 | advise not using but they are still in the library for historical reasons. | |
7 | For all calls that have an 'input' and 'output' variables, they can be the | |
8 | same. | |
9 | ||
10 | This library requires the inclusion of 'des.h'. | |
11 | ||
12 | All of the encryption functions take what is called a des_key_schedule as an | |
13 | argument. A des_key_schedule is an expanded form of the des key. | |
14 | A des_key is 8 bytes of odd parity, the type used to hold the key is a | |
15 | des_cblock. A des_cblock is an array of 8 bytes, often in this library | |
16 | description I will refer to input bytes when the function specifies | |
17 | des_cblock's as input or output, this just means that the variable should | |
18 | be a multiple of 8 bytes. | |
19 | ||
20 | The define DES_ENCRYPT is passed to specify encryption, DES_DECRYPT to | |
21 | specify decryption. The functions and global variable are as follows: | |
22 | ||
23 | int des_check_key; | |
24 | DES keys are supposed to be odd parity. If this variable is set to | |
25 | a non-zero value, des_set_key() will check that the key has odd | |
26 | parity and is not one of the known weak DES keys. By default this | |
27 | variable is turned off; | |
28 | ||
29 | void des_set_odd_parity( | |
30 | des_cblock *key ); | |
31 | This function takes a DES key (8 bytes) and sets the parity to odd. | |
32 | ||
33 | int des_is_weak_key( | |
34 | des_cblock *key ); | |
35 | This function returns a non-zero value if the DES key passed is a | |
36 | weak, DES key. If it is a weak key, don't use it, try a different | |
37 | one. If you are using 'random' keys, the chances of hitting a weak | |
38 | key are 1/2^52 so it is probably not worth checking for them. | |
39 | ||
40 | int des_set_key( | |
41 | des_cblock *key, | |
42 | des_key_schedule schedule); | |
43 | Des_set_key converts an 8 byte DES key into a des_key_schedule. | |
44 | A des_key_schedule is an expanded form of the key which is used to | |
45 | perform actual encryption. It can be regenerated from the DES key | |
46 | so it only needs to be kept when encryption or decryption is about | |
47 | to occur. Don't save or pass around des_key_schedule's since they | |
48 | are CPU architecture dependent, DES keys are not. If des_check_key | |
49 | is non zero, zero is returned if the key has the wrong parity or | |
50 | the key is a weak key, else 1 is returned. | |
51 | ||
52 | int des_key_sched( | |
53 | des_cblock *key, | |
54 | des_key_schedule schedule); | |
55 | An alternative name for des_set_key(). | |
56 | ||
57 | int des_rw_mode; /* defaults to DES_PCBC_MODE */ | |
58 | This flag holds either DES_CBC_MODE or DES_PCBC_MODE (default). | |
59 | This specifies the function to use in the enc_read() and enc_write() | |
60 | functions. | |
61 | ||
62 | void des_encrypt( | |
63 | unsigned long *data, | |
64 | des_key_schedule ks, | |
65 | int enc); | |
66 | This is the DES encryption function that gets called by just about | |
67 | every other DES routine in the library. You should not use this | |
68 | function except to implement 'modes' of DES. I say this because the | |
69 | functions that call this routine do the conversion from 'char *' to | |
70 | long, and this needs to be done to make sure 'non-aligned' memory | |
71 | access do not occur. The characters are loaded 'little endian', | |
72 | have a look at my source code for more details on how I use this | |
73 | function. | |
74 | Data is a pointer to 2 unsigned long's and ks is the | |
75 | des_key_schedule to use. enc, is non zero specifies encryption, | |
76 | zero if decryption. | |
77 | ||
78 | void des_encrypt2( | |
79 | unsigned long *data, | |
80 | des_key_schedule ks, | |
81 | int enc); | |
82 | This functions is the same as des_encrypt() except that the DES | |
83 | initial permutation (IP) and final permutation (FP) have been left | |
84 | out. As for des_encrypt(), you should not use this function. | |
85 | It is used by the routines in my library that implement triple DES. | |
86 | IP() des_encrypt2() des_encrypt2() des_encrypt2() FP() is the same | |
87 | as des_encrypt() des_encrypt() des_encrypt() except faster :-). | |
88 | ||
89 | void des_ecb_encrypt( | |
90 | des_cblock *input, | |
91 | des_cblock *output, | |
92 | des_key_schedule ks, | |
93 | int enc); | |
94 | This is the basic Electronic Code Book form of DES, the most basic | |
95 | form. Input is encrypted into output using the key represented by | |
96 | ks. If enc is non zero (DES_ENCRYPT), encryption occurs, otherwise | |
97 | decryption occurs. Input is 8 bytes long and output is 8 bytes. | |
98 | (the des_cblock structure is 8 chars). | |
99 | ||
100 | void des_ecb3_encrypt( | |
101 | des_cblock *input, | |
102 | des_cblock *output, | |
103 | des_key_schedule ks1, | |
104 | des_key_schedule ks2, | |
105 | des_key_schedule ks3, | |
106 | int enc); | |
107 | This is the 3 key EDE mode of ECB DES. What this means is that | |
108 | the 8 bytes of input is encrypted with ks1, decrypted with ks2 and | |
109 | then encrypted again with ks3, before being put into output; | |
110 | C=E(ks3,D(ks2,E(ks1,M))). There is a macro, des_ecb2_encrypt() | |
111 | that only takes 2 des_key_schedules that implements, | |
112 | C=E(ks1,D(ks2,E(ks1,M))) in that the final encrypt is done with ks1. | |
113 | ||
114 | void des_cbc_encrypt( | |
115 | des_cblock *input, | |
116 | des_cblock *output, | |
117 | long length, | |
118 | des_key_schedule ks, | |
119 | des_cblock *ivec, | |
120 | int enc); | |
121 | This routine implements DES in Cipher Block Chaining mode. | |
122 | Input, which should be a multiple of 8 bytes is encrypted | |
123 | (or decrypted) to output which will also be a multiple of 8 bytes. | |
124 | The number of bytes is in length (and from what I've said above, | |
125 | should be a multiple of 8). If length is not a multiple of 8, I'm | |
126 | not being held responsible :-). ivec is the initialisation vector. | |
127 | This function does not modify this variable. To correctly implement | |
128 | cbc mode, you need to do one of 2 things; copy the last 8 bytes of | |
129 | cipher text for use as the next ivec in your application, | |
130 | or use des_ncbc_encrypt(). | |
131 | Only this routine has this problem with updating the ivec, all | |
132 | other routines that are implementing cbc mode update ivec. | |
133 | ||
134 | void des_ncbc_encrypt( | |
135 | des_cblock *input, | |
136 | des_cblock *output, | |
137 | long length, | |
138 | des_key_schedule sk, | |
139 | des_cblock *ivec, | |
140 | int enc); | |
141 | For historical reasons, des_cbc_encrypt() did not update the | |
142 | ivec with the value requires so that subsequent calls to | |
143 | des_cbc_encrypt() would 'chain'. This was needed so that the same | |
144 | 'length' values would not need to be used when decrypting. | |
145 | des_ncbc_encrypt() does the right thing. It is the same as | |
146 | des_cbc_encrypt accept that ivec is updates with the correct value | |
147 | to pass in subsequent calls to des_ncbc_encrypt(). I advise using | |
148 | des_ncbc_encrypt() instead of des_cbc_encrypt(); | |
149 | ||
150 | void des_xcbc_encrypt( | |
151 | des_cblock *input, | |
152 | des_cblock *output, | |
153 | long length, | |
154 | des_key_schedule sk, | |
155 | des_cblock *ivec, | |
156 | des_cblock *inw, | |
157 | des_cblock *outw, | |
158 | int enc); | |
159 | This is RSA's DESX mode of DES. It uses inw and outw to | |
160 | 'whiten' the encryption. inw and outw are secret (unlike the iv) | |
161 | and are as such, part of the key. So the key is sort of 24 bytes. | |
162 | This is much better than cbc des. | |
163 | ||
164 | void des_3cbc_encrypt( | |
165 | des_cblock *input, | |
166 | des_cblock *output, | |
167 | long length, | |
168 | des_key_schedule sk1, | |
169 | des_key_schedule sk2, | |
170 | des_cblock *ivec1, | |
171 | des_cblock *ivec2, | |
172 | int enc); | |
173 | This function is flawed, do not use it. I have left it in the | |
174 | library because it is used in my des(1) program and will function | |
175 | correctly when used by des(1). If I removed the function, people | |
176 | could end up unable to decrypt files. | |
177 | This routine implements outer triple cbc encryption using 2 ks and | |
178 | 2 ivec's. Use des_ede2_cbc_encrypt() instead. | |
179 | ||
180 | void des_ede3_cbc_encrypt( | |
181 | des_cblock *input, | |
182 | des_cblock *output, | |
183 | long length, | |
184 | des_key_schedule ks1, | |
185 | des_key_schedule ks2, | |
186 | des_key_schedule ks3, | |
187 | des_cblock *ivec, | |
188 | int enc); | |
189 | This function implements inner triple CBC DES encryption with 3 | |
190 | keys. What this means is that each 'DES' operation | |
191 | inside the cbc mode is really an C=E(ks3,D(ks2,E(ks1,M))). | |
192 | Again, this is cbc mode so an ivec is requires. | |
193 | This mode is used by SSL. | |
194 | There is also a des_ede2_cbc_encrypt() that only uses 2 | |
195 | des_key_schedule's, the first being reused for the final | |
196 | encryption. C=E(ks1,D(ks2,E(ks1,M))). This form of triple DES | |
197 | is used by the RSAref library. | |
198 | ||
199 | void des_pcbc_encrypt( | |
200 | des_cblock *input, | |
201 | des_cblock *output, | |
202 | long length, | |
203 | des_key_schedule ks, | |
204 | des_cblock *ivec, | |
205 | int enc); | |
206 | This is Propagating Cipher Block Chaining mode of DES. It is used | |
207 | by Kerberos v4. It's parameters are the same as des_ncbc_encrypt(). | |
208 | ||
209 | void des_cfb_encrypt( | |
210 | unsigned char *in, | |
211 | unsigned char *out, | |
212 | int numbits, | |
213 | long length, | |
214 | des_key_schedule ks, | |
215 | des_cblock *ivec, | |
216 | int enc); | |
217 | Cipher Feedback Back mode of DES. This implementation 'feeds back' | |
218 | in numbit blocks. The input (and output) is in multiples of numbits | |
219 | bits. numbits should to be a multiple of 8 bits. Length is the | |
220 | number of bytes input. If numbits is not a multiple of 8 bits, | |
221 | the extra bits in the bytes will be considered padding. So if | |
222 | numbits is 12, for each 2 input bytes, the 4 high bits of the | |
223 | second byte will be ignored. So to encode 72 bits when using | |
224 | a numbits of 12 take 12 bytes. To encode 72 bits when using | |
225 | numbits of 9 will take 16 bytes. To encode 80 bits when using | |
226 | numbits of 16 will take 10 bytes. etc, etc. This padding will | |
227 | apply to both input and output. | |
228 | ||
229 | ||
230 | void des_cfb64_encrypt( | |
231 | unsigned char *in, | |
232 | unsigned char *out, | |
233 | long length, | |
234 | des_key_schedule ks, | |
235 | des_cblock *ivec, | |
236 | int *num, | |
237 | int enc); | |
238 | This is one of the more useful functions in this DES library, it | |
239 | implements CFB mode of DES with 64bit feedback. Why is this | |
240 | useful you ask? Because this routine will allow you to encrypt an | |
241 | arbitrary number of bytes, no 8 byte padding. Each call to this | |
242 | routine will encrypt the input bytes to output and then update ivec | |
243 | and num. num contains 'how far' we are though ivec. If this does | |
244 | not make much sense, read more about cfb mode of DES :-). | |
245 | ||
246 | void des_ede3_cfb64_encrypt( | |
247 | unsigned char *in, | |
248 | unsigned char *out, | |
249 | long length, | |
250 | des_key_schedule ks1, | |
251 | des_key_schedule ks2, | |
252 | des_key_schedule ks3, | |
253 | des_cblock *ivec, | |
254 | int *num, | |
255 | int enc); | |
256 | Same as des_cfb64_encrypt() accept that the DES operation is | |
257 | triple DES. As usual, there is a macro for | |
258 | des_ede2_cfb64_encrypt() which reuses ks1. | |
259 | ||
260 | void des_ofb_encrypt( | |
261 | unsigned char *in, | |
262 | unsigned char *out, | |
263 | int numbits, | |
264 | long length, | |
265 | des_key_schedule ks, | |
266 | des_cblock *ivec); | |
267 | This is a implementation of Output Feed Back mode of DES. It is | |
268 | the same as des_cfb_encrypt() in that numbits is the size of the | |
269 | units dealt with during input and output (in bits). | |
270 | ||
271 | void des_ofb64_encrypt( | |
272 | unsigned char *in, | |
273 | unsigned char *out, | |
274 | long length, | |
275 | des_key_schedule ks, | |
276 | des_cblock *ivec, | |
277 | int *num); | |
278 | The same as des_cfb64_encrypt() except that it is Output Feed Back | |
279 | mode. | |
280 | ||
281 | void des_ede3_ofb64_encrypt( | |
282 | unsigned char *in, | |
283 | unsigned char *out, | |
284 | long length, | |
285 | des_key_schedule ks1, | |
286 | des_key_schedule ks2, | |
287 | des_key_schedule ks3, | |
288 | des_cblock *ivec, | |
289 | int *num); | |
290 | Same as des_ofb64_encrypt() accept that the DES operation is | |
291 | triple DES. As usual, there is a macro for | |
292 | des_ede2_ofb64_encrypt() which reuses ks1. | |
293 | ||
294 | int des_read_pw_string( | |
295 | char *buf, | |
296 | int length, | |
297 | char *prompt, | |
298 | int verify); | |
299 | This routine is used to get a password from the terminal with echo | |
300 | turned off. Buf is where the string will end up and length is the | |
301 | size of buf. Prompt is a string presented to the 'user' and if | |
302 | verify is set, the key is asked for twice and unless the 2 copies | |
303 | match, an error is returned. A return code of -1 indicates a | |
304 | system error, 1 failure due to use interaction, and 0 is success. | |
305 | ||
306 | unsigned long des_cbc_cksum( | |
307 | des_cblock *input, | |
308 | des_cblock *output, | |
309 | long length, | |
310 | des_key_schedule ks, | |
311 | des_cblock *ivec); | |
312 | This function produces an 8 byte checksum from input that it puts in | |
313 | output and returns the last 4 bytes as a long. The checksum is | |
314 | generated via cbc mode of DES in which only the last 8 byes are | |
315 | kept. I would recommend not using this function but instead using | |
316 | the EVP_Digest routines, or at least using MD5 or SHA. This | |
317 | function is used by Kerberos v4 so that is why it stays in the | |
318 | library. | |
319 | ||
320 | char *des_fcrypt( | |
321 | const char *buf, | |
322 | const char *salt | |
323 | char *ret); | |
324 | This is my fast version of the unix crypt(3) function. This version | |
325 | takes only a small amount of space relative to other fast | |
326 | crypt() implementations. This is different to the normal crypt | |
327 | in that the third parameter is the buffer that the return value | |
328 | is written into. It needs to be at least 14 bytes long. This | |
329 | function is thread safe, unlike the normal crypt. | |
330 | ||
331 | char *crypt( | |
332 | const char *buf, | |
333 | const char *salt); | |
334 | This function calls des_fcrypt() with a static array passed as the | |
335 | third parameter. This emulates the normal non-thread safe semantics | |
336 | of crypt(3). | |
337 | ||
338 | void des_string_to_key( | |
339 | char *str, | |
340 | des_cblock *key); | |
341 | This function takes str and converts it into a DES key. I would | |
342 | recommend using MD5 instead and use the first 8 bytes of output. | |
343 | When I wrote the first version of these routines back in 1990, MD5 | |
344 | did not exist but I feel these routines are still sound. This | |
345 | routines is compatible with the one in MIT's libdes. | |
346 | ||
347 | void des_string_to_2keys( | |
348 | char *str, | |
349 | des_cblock *key1, | |
350 | des_cblock *key2); | |
351 | This function takes str and converts it into 2 DES keys. | |
352 | I would recommend using MD5 and using the 16 bytes as the 2 keys. | |
353 | I have nothing against these 2 'string_to_key' routines, it's just | |
354 | that if you say that your encryption key is generated by using the | |
355 | 16 bytes of an MD5 hash, every-one knows how you generated your | |
356 | keys. | |
357 | ||
358 | int des_read_password( | |
359 | des_cblock *key, | |
360 | char *prompt, | |
361 | int verify); | |
362 | This routine combines des_read_pw_string() with des_string_to_key(). | |
363 | ||
364 | int des_read_2passwords( | |
365 | des_cblock *key1, | |
366 | des_cblock *key2, | |
367 | char *prompt, | |
368 | int verify); | |
369 | This routine combines des_read_pw_string() with des_string_to_2key(). | |
370 | ||
371 | void des_random_seed( | |
372 | des_cblock key); | |
373 | This routine sets a starting point for des_random_key(). | |
374 | ||
375 | void des_random_key( | |
376 | des_cblock ret); | |
377 | This function return a random key. Make sure to 'seed' the random | |
378 | number generator (with des_random_seed()) before using this function. | |
379 | I personally now use a MD5 based random number system. | |
380 | ||
381 | int des_enc_read( | |
382 | int fd, | |
383 | char *buf, | |
384 | int len, | |
385 | des_key_schedule ks, | |
386 | des_cblock *iv); | |
387 | This function will write to a file descriptor the encrypted data | |
388 | from buf. This data will be preceded by a 4 byte 'byte count' and | |
389 | will be padded out to 8 bytes. The encryption is either CBC of | |
390 | PCBC depending on the value of des_rw_mode. If it is DES_PCBC_MODE, | |
391 | pcbc is used, if DES_CBC_MODE, cbc is used. The default is to use | |
392 | DES_PCBC_MODE. | |
393 | ||
394 | int des_enc_write( | |
395 | int fd, | |
396 | char *buf, | |
397 | int len, | |
398 | des_key_schedule ks, | |
399 | des_cblock *iv); | |
400 | This routines read stuff written by des_enc_read() and decrypts it. | |
401 | I have used these routines quite a lot but I don't believe they are | |
402 | suitable for non-blocking io. If you are after a full | |
403 | authentication/encryption over networks, have a look at SSL instead. | |
404 | ||
405 | unsigned long des_quad_cksum( | |
406 | des_cblock *input, | |
407 | des_cblock *output, | |
408 | long length, | |
409 | int out_count, | |
410 | des_cblock *seed); | |
411 | This is a function from Kerberos v4 that is not anything to do with | |
412 | DES but was needed. It is a cksum that is quicker to generate than | |
413 | des_cbc_cksum(); I personally would use MD5 routines now. | |
414 | ===== | |
415 | Modes of DES | |
416 | Quite a bit of the following information has been taken from | |
417 | AS 2805.5.2 | |
418 | Australian Standard | |
419 | Electronic funds transfer - Requirements for interfaces, | |
420 | Part 5.2: Modes of operation for an n-bit block cipher algorithm | |
421 | Appendix A | |
422 | ||
423 | There are several different modes in which DES can be used, they are | |
424 | as follows. | |
425 | ||
426 | Electronic Codebook Mode (ECB) (des_ecb_encrypt()) | |
427 | - 64 bits are enciphered at a time. | |
428 | - The order of the blocks can be rearranged without detection. | |
429 | - The same plaintext block always produces the same ciphertext block | |
430 | (for the same key) making it vulnerable to a 'dictionary attack'. | |
431 | - An error will only affect one ciphertext block. | |
432 | ||
433 | Cipher Block Chaining Mode (CBC) (des_cbc_encrypt()) | |
434 | - a multiple of 64 bits are enciphered at a time. | |
435 | - The CBC mode produces the same ciphertext whenever the same | |
436 | plaintext is encrypted using the same key and starting variable. | |
437 | - The chaining operation makes the ciphertext blocks dependent on the | |
438 | current and all preceding plaintext blocks and therefore blocks can not | |
439 | be rearranged. | |
440 | - The use of different starting variables prevents the same plaintext | |
441 | enciphering to the same ciphertext. | |
442 | - An error will affect the current and the following ciphertext blocks. | |
443 | ||
444 | Cipher Feedback Mode (CFB) (des_cfb_encrypt()) | |
445 | - a number of bits (j) <= 64 are enciphered at a time. | |
446 | - The CFB mode produces the same ciphertext whenever the same | |
447 | plaintext is encrypted using the same key and starting variable. | |
448 | - The chaining operation makes the ciphertext variables dependent on the | |
449 | current and all preceding variables and therefore j-bit variables are | |
450 | chained together and can not be rearranged. | |
451 | - The use of different starting variables prevents the same plaintext | |
452 | enciphering to the same ciphertext. | |
453 | - The strength of the CFB mode depends on the size of k (maximal if | |
454 | j == k). In my implementation this is always the case. | |
455 | - Selection of a small value for j will require more cycles through | |
456 | the encipherment algorithm per unit of plaintext and thus cause | |
457 | greater processing overheads. | |
458 | - Only multiples of j bits can be enciphered. | |
459 | - An error will affect the current and the following ciphertext variables. | |
460 | ||
461 | Output Feedback Mode (OFB) (des_ofb_encrypt()) | |
462 | - a number of bits (j) <= 64 are enciphered at a time. | |
463 | - The OFB mode produces the same ciphertext whenever the same | |
464 | plaintext enciphered using the same key and starting variable. More | |
465 | over, in the OFB mode the same key stream is produced when the same | |
466 | key and start variable are used. Consequently, for security reasons | |
467 | a specific start variable should be used only once for a given key. | |
468 | - The absence of chaining makes the OFB more vulnerable to specific attacks. | |
469 | - The use of different start variables values prevents the same | |
470 | plaintext enciphering to the same ciphertext, by producing different | |
471 | key streams. | |
472 | - Selection of a small value for j will require more cycles through | |
473 | the encipherment algorithm per unit of plaintext and thus cause | |
474 | greater processing overheads. | |
475 | - Only multiples of j bits can be enciphered. | |
476 | - OFB mode of operation does not extend ciphertext errors in the | |
477 | resultant plaintext output. Every bit error in the ciphertext causes | |
478 | only one bit to be in error in the deciphered plaintext. | |
479 | - OFB mode is not self-synchronising. If the two operation of | |
480 | encipherment and decipherment get out of synchronism, the system needs | |
481 | to be re-initialised. | |
482 | - Each re-initialisation should use a value of the start variable | |
483 | different from the start variable values used before with the same | |
484 | key. The reason for this is that an identical bit stream would be | |
485 | produced each time from the same parameters. This would be | |
486 | susceptible to a ' known plaintext' attack. | |
487 | ||
488 | Triple ECB Mode (des_ecb3_encrypt()) | |
489 | - Encrypt with key1, decrypt with key2 and encrypt with key3 again. | |
490 | - As for ECB encryption but increases the key length to 168 bits. | |
491 | There are theoretic attacks that can be used that make the effective | |
492 | key length 112 bits, but this attack also requires 2^56 blocks of | |
493 | memory, not very likely, even for the NSA. | |
494 | - If both keys are the same it is equivalent to encrypting once with | |
495 | just one key. | |
496 | - If the first and last key are the same, the key length is 112 bits. | |
497 | There are attacks that could reduce the key space to 55 bit's but it | |
498 | requires 2^56 blocks of memory. | |
499 | - If all 3 keys are the same, this is effectively the same as normal | |
500 | ecb mode. | |
501 | ||
502 | Triple CBC Mode (des_ede3_cbc_encrypt()) | |
503 | - Encrypt with key1, decrypt with key2 and then encrypt with key3. | |
504 | - As for CBC encryption but increases the key length to 168 bits with | |
505 | the same restrictions as for triple ecb mode. |