1The DES library. 2 3Please note that this library was originally written to operate with 4eBones, a version of Kerberos that had had encryption removed when it left 5the USA and then put back in. As such there are some routines that I will 6advise not using but they are still in the library for historical reasons. 7For all calls that have an 'input' and 'output' variables, they can be the 8same. 9 10This library requires the inclusion of 'des.h'. 11 12All of the encryption functions take what is called a des_key_schedule as an 13argument. A des_key_schedule is an expanded form of the des key. 14A des_key is 8 bytes of odd parity, the type used to hold the key is a 15des_cblock. A des_cblock is an array of 8 bytes, often in this library 16description I will refer to input bytes when the function specifies 17des_cblock's as input or output, this just means that the variable should 18be a multiple of 8 bytes. 19 20The define DES_ENCRYPT is passed to specify encryption, DES_DECRYPT to 21specify decryption. The functions and global variable are as follows: 22 23int 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 29void des_set_odd_parity( 30des_cblock *key ); 31 This function takes a DES key (8 bytes) and sets the parity to odd. 32 33int des_is_weak_key( 34des_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 40int des_set_key( 41des_cblock *key, 42des_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 52int des_key_sched( 53des_cblock *key, 54des_key_schedule schedule); 55 An alternative name for des_set_key(). 56 57int 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 62void des_encrypt( 63unsigned long *data, 64des_key_schedule ks, 65int 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 78void des_encrypt2( 79unsigned long *data, 80des_key_schedule ks, 81int 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 89void des_ecb_encrypt( 90des_cblock *input, 91des_cblock *output, 92des_key_schedule ks, 93int 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 100void des_ecb3_encrypt( 101des_cblock *input, 102des_cblock *output, 103des_key_schedule ks1, 104des_key_schedule ks2, 105des_key_schedule ks3, 106int 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 114void des_cbc_encrypt( 115des_cblock *input, 116des_cblock *output, 117long length, 118des_key_schedule ks, 119des_cblock *ivec, 120int 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 134void des_ncbc_encrypt( 135des_cblock *input, 136des_cblock *output, 137long length, 138des_key_schedule sk, 139des_cblock *ivec, 140int 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 150void des_xcbc_encrypt( 151des_cblock *input, 152des_cblock *output, 153long length, 154des_key_schedule sk, 155des_cblock *ivec, 156des_cblock *inw, 157des_cblock *outw, 158int 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 164void des_3cbc_encrypt( 165des_cblock *input, 166des_cblock *output, 167long length, 168des_key_schedule sk1, 169des_key_schedule sk2, 170des_cblock *ivec1, 171des_cblock *ivec2, 172int 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 180void des_ede3_cbc_encrypt( 181des_cblock *input, 182des_cblock *output, 183long length, 184des_key_schedule ks1, 185des_key_schedule ks2, 186des_key_schedule ks3, 187des_cblock *ivec, 188int 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 199void des_pcbc_encrypt( 200des_cblock *input, 201des_cblock *output, 202long length, 203des_key_schedule ks, 204des_cblock *ivec, 205int 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 209void des_cfb_encrypt( 210unsigned char *in, 211unsigned char *out, 212int numbits, 213long length, 214des_key_schedule ks, 215des_cblock *ivec, 216int 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 230void des_cfb64_encrypt( 231unsigned char *in, 232unsigned char *out, 233long length, 234des_key_schedule ks, 235des_cblock *ivec, 236int *num, 237int 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 246void des_ede3_cfb64_encrypt( 247unsigned char *in, 248unsigned char *out, 249long length, 250des_key_schedule ks1, 251des_key_schedule ks2, 252des_key_schedule ks3, 253des_cblock *ivec, 254int *num, 255int 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 260void des_ofb_encrypt( 261unsigned char *in, 262unsigned char *out, 263int numbits, 264long length, 265des_key_schedule ks, 266des_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 271void des_ofb64_encrypt( 272unsigned char *in, 273unsigned char *out, 274long length, 275des_key_schedule ks, 276des_cblock *ivec, 277int *num); 278 The same as des_cfb64_encrypt() except that it is Output Feed Back 279 mode. 280 281void des_ede3_ofb64_encrypt( 282unsigned char *in, 283unsigned char *out, 284long length, 285des_key_schedule ks1, 286des_key_schedule ks2, 287des_key_schedule ks3, 288des_cblock *ivec, 289int *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 294int des_read_pw_string( 295char *buf, 296int length, 297char *prompt, 298int 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 306unsigned long des_cbc_cksum( 307des_cblock *input, 308des_cblock *output, 309long length, 310des_key_schedule ks, 311des_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 320char *des_fcrypt( 321const char *buf, 322const char *salt 323char *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 331char *crypt( 332const char *buf, 333const 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 338void des_string_to_key( 339char *str, 340des_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 347void des_string_to_2keys( 348char *str, 349des_cblock *key1, 350des_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 358int des_read_password( 359des_cblock *key, 360char *prompt, 361int verify); 362 This routine combines des_read_pw_string() with des_string_to_key(). 363 364int des_read_2passwords( 365des_cblock *key1, 366des_cblock *key2, 367char *prompt, 368int verify); 369 This routine combines des_read_pw_string() with des_string_to_2key(). 370 371void des_random_seed( 372des_cblock key); 373 This routine sets a starting point for des_random_key(). 374 375void des_random_key( 376des_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 381int des_enc_read( 382int fd, 383char *buf, 384int len, 385des_key_schedule ks, 386des_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 394int des_enc_write( 395int fd, 396char *buf, 397int len, 398des_key_schedule ks, 399des_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 405unsigned long des_quad_cksum( 406des_cblock *input, 407des_cblock *output, 408long length, 409int out_count, 410des_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===== 415Modes of DES 416Quite 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 423There are several different modes in which DES can be used, they are 424as follows. 425 426Electronic 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 433Cipher 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 444Cipher 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 461Output 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 488Triple 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 502Triple 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. 506