crypto/heimdal-0.6.3/lib/des/des_crypt.man

   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)