crypto/heimdal-0.6.3/lib/des/des.doc

   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.