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