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

   1 .\" $Id: des_crypt.3,v 1.2 1996/06/12 21:29:09 bg Exp $
   2 .\" Copyright 1989 by the Massachusetts Institute of Technology.
   3 .\"
   4 .\" For copying and distribution information,
   5 .\" please see the file <mit-copyright.h>.
   6 .\"
   7 .TH DES_CRYPT 3  "Kerberos Version 4.0" "MIT Project Athena"
   8 .SH NAME
   9 des_read_password, des_string_to_key, des_random_key, des_set_key,
  10 des_ecb_encrypt, des_cbc_encrypt, des_pcbc_encrypt, des_cbc_cksum,
  11 des_quad_cksum, \- (new) DES encryption
  12 .SH SYNOPSIS
  13 .nf
  14 .nj
  15 .ft B
  16 #include <des.h>
  17 .PP
  18 .ft B
  19 .B int des_read_password(key,prompt,verify)
  20 des_cblock *key;
  21 char *prompt;
  22 int verify;
  23 .PP
  24 .ft B
  25 int des_string_to_key(str,key)
  26 char *str;
  27 des_cblock key;
  28 .PP
  29 .ft B
  30 int des_random_key(key)
  31 des_cblock *key;
  32 .PP
  33 .ft B
  34 int des_set_key(key,schedule)
  35 des_cblock *key;
  36 des_key_schedule schedule;
  37 .PP
  38 .ft B
  39 int des_ecb_encrypt(input,output,schedule,encrypt)
  40 des_cblock *input;
  41 des_cblock *output;
  42 des_key_schedule schedule;
  43 int encrypt;
  44 .PP
  45 .ft B
  46 int des_cbc_encrypt(input,output,length,schedule,ivec,encrypt)
  47 des_cblock *input;
  48 des_cblock *output;
  49 long length;
  50 des_key_schedule schedule;
  51 des_cblock *ivec;
  52 int encrypt;
  53 .PP
  54 .ft B
  55 int des_pcbc_encrypt(input,output,length,schedule,ivec,encrypt)
  56 des_cblock *input;
  57 des_cblock *output;
  58 long length;
  59 des_key_schedule schedule;
  60 des_cblock *ivec;
  61 int encrypt;
  62 .PP
  63 .ft B
  64 unsigned long des_cbc_cksum(input,output,length,schedule,ivec)
  65 des_cblock *input;
  66 des_cblock *output;
  67 long length;
  68 des_key_schedule schedule;
  69 des_cblock *ivec;
  70 .PP
  71 .ft B
  72 unsigned long quad_cksum(input,output,length,out_count,seed)
  73 des_cblock *input;
  74 des_cblock *output;
  75 long length;
  76 int out_count;
  77 des_cblock *seed;
  78 .PP
  79 .fi
  80 .SH DESCRIPTION
  81 This library supports various DES encryption related operations. It differs
  82 from the
  83 .I crypt, setkey, and encrypt
  84 library routines in that it provides
  85 a true DES encryption, without modifying the algorithm,
  86 and executes much faster.
  87 .PP
  88 For each key that may be simultaneously active, create a
  89 .B des_key_schedule
  90 struct,
  91 defined in "des.h". Next, create key schedules (from the 8-byte keys) as
  92 needed, via
  93 .I des_set_key,
  94 prior to using the encryption or checksum routines. Then
  95 setup the input and output areas.  Make sure to note the restrictions
  96 on lengths being multiples of eight bytes. Finally, invoke the
  97 encryption/decryption routines,
  98 .I des_ecb_encrypt
  99 or
 100 .I des_cbc_encrypt
 101 or
 102 .I des_pcbc_encrypt,
 103 or, to generate a cryptographic checksum, use
 104 .I quad_cksum
 105 (fast) or
 106 .I des_cbc_cksum
 107 (slow).
 108 .PP
 109 A
 110 .I des_cblock
 111 struct is an 8 byte block used as the fundamental unit for DES data and
 112 keys, and is defined as:
 113 .PP
 114 .B      typedef unsigned char des_cblock[8];
 115 .PP
 116 and a
 117 .I des_key_schedule,
 118 is defined as:
 119 .PP
 120 .B      typedef struct des_ks_struct {des_cblock _;}  des_key_schedule[16];
 121 .PP
 122 .I des_read_password
 123 writes the string specified by
 124 .I prompt
 125 to the standard
 126 output, turns off echo (if possible)
 127 and reads an input string from standard input until terminated with a newline.
 128 If
 129 .I verify
 130 is non-zero, it prompts and reads input again, for use
 131 in applications such as changing a password; both
 132 versions are compared, and the input is requested repeatedly until they
 133 match.  Then
 134 .I des_read_password
 135 converts the input string into a valid DES key, internally
 136 using the
 137 .I des_string_to_key
 138 routine.  The newly created key is copied to the
 139 area pointed to by the
 140 .I key
 141 argument.
 142 .I des_read_password
 143 returns a zero if no errors occurred, or a -1
 144 indicating that an error
 145 occurred trying to manipulate the terminal echo.
 146 .PP
 147 .PP
 148 .I des_string_to_key
 149 converts an arbitrary length null-terminated string
 150 to an 8 byte DES key, with odd byte parity, per FIPS specification.
 151 A one-way function is used to convert the string to a key, making it
 152 very difficult to reconstruct the string from the key.
 153 The
 154 .I str
 155 argument is a pointer to the string, and
 156 .I key
 157 should
 158 point to a
 159 .I des_cblock
 160 supplied by the caller to receive the generated key.
 161 No meaningful value is returned. Void is not used for compatibility with
 162 other compilers.
 163 .PP
 164 .PP
 165 .I des_random_key
 166 generates a random DES encryption key (eight bytes), set to odd parity per
 167 FIPS
 168 specifications.
 169 This routine uses the current time, process id, and a counter
 170 as a seed for the random number generator.
 171 The caller must supply space for the output key, pointed to
 172 by argument
 173 .I key,
 174 then after calling
 175 .I des_random_key
 176 should
 177 call the
 178 .I des_set_key
 179 routine when needed.
 180 No meaningful value is returned.  Void is not used for compatibility
 181 with other compilers.
 182 .PP
 183 .PP
 184 .I des_set_key
 185 calculates a key schedule from all eight bytes of the input key, pointed
 186 to by the
 187 .I key
 188 argument, and outputs the schedule into the
 189 .I des_key_schedule
 190 indicated by the
 191 .I schedule
 192 argument. Make sure to pass a valid eight byte
 193 key; no padding is done.  The key schedule may then be used in subsequent
 194 encryption/decryption/checksum operations.  Many key schedules may be
 195 cached for later use.  The user is responsible to clear keys and schedules
 196 as soon as no longer needed, to prevent their disclosure.
 197 The routine also checks the key
 198 parity, and returns a zero if the key parity is correct (odd), a -1
 199 indicating a key parity error, or a -2 indicating use of an illegal
 200 weak key. If an error is returned, the key schedule was not created.
 201 .PP
 202 .PP
 203 .I des_ecb_encrypt
 204 is the basic DES encryption routine that encrypts or decrypts a single 8-byte
 205 block in
 206 .B electronic code book
 207 mode.  It always transforms the input data, pointed to by
 208 .I input,
 209 into the output data, pointed to by the
 210 .I output
 211 argument.
 212 .PP
 213 If the
 214 .I encrypt
 215 argument is non-zero, the
 216 .I input
 217 (cleartext) is encrypted into the
 218 .I output
 219 (ciphertext) using the key_schedule specified by the
 220 .I schedule
 221 argument, previously set via
 222 .I des_set_key
 223 .PP
 224 If encrypt is zero, the
 225 .I input
 226 (now ciphertext) is decrypted into the
 227 .I output
 228 (now cleartext).
 229 .PP
 230 Input and output may overlap.
 231 .PP
 232 No meaningful value is returned.  Void is not used for compatibility
 233 with other compilers.
 234 .PP
 235 .PP
 236 .I des_cbc_encrypt
 237 encrypts/decrypts using the
 238 .B cipher-block-chaining mode of DES.
 239 If the
 240 .I encrypt
 241 argument is non-zero, the routine cipher-block-chain encrypts
 242 the cleartext data pointed to by the
 243 .I input
 244 argument into the ciphertext pointed to by the
 245 .I output
 246 argument, using the key schedule provided by the
 247 .I schedule
 248 argument, and initialization vector provided by the
 249 .I ivec
 250 argument.
 251 If the
 252 .I length
 253 argument is not an integral
 254 multiple of eight bytes, the last block is copied to a temp and zero
 255 filled (highest addresses).  The output is ALWAYS an integral multiple
 256 of eight bytes.
 257 .PP
 258 If
 259 .I encrypt
 260 is zero, the routine cipher-block chain decrypts the (now) ciphertext
 261 data pointed to by the
 262 .I input
 263 argument into (now) cleartext pointed to by the
 264 .I output
 265 argument using the key schedule provided by the
 266 .I schedule
 267 argument, and initialization vector provided by the
 268 .I ivec
 269 argument. Decryption ALWAYS operates on integral
 270 multiples of 8 bytes, so it will round the
 271 .I length
 272 provided up to the
 273 appropriate multiple. Consequently, it will always produce the rounded-up
 274 number of bytes of output cleartext. The application must determine if
 275 the output cleartext was zero-padded due to original cleartext lengths that
 276 were not integral multiples of 8.
 277 .PP
 278 No errors or meaningful values are returned.  Void is not used for
 279 compatibility with other compilers.
 280 .PP
 281 A characteristic of cbc mode is that changing a single bit of the
 282 cleartext, then encrypting using cbc mode,
 283 affects ALL the subsequent ciphertext.  This makes cryptanalysis
 284 much more difficult. However, modifying a single bit of the ciphertext,
 285 then decrypting, only affects the resulting cleartext from
 286 the modified block and the succeeding block.  Therefore,
 287 .I des_pcbc_encrypt
 288 is STRONGLY recommended for applications where
 289 indefinite propagation of errors is required in order to detect modifications.
 290 .PP
 291 .PP
 292 .I des_pcbc_encrypt
 293 encrypts/decrypts using a modified block chaining mode. Its calling
 294 sequence is identical to
 295 .I des_cbc_encrypt.
 296 It differs in its error propagation characteristics.
 297 .PP
 298 .I des_pcbc_encrypt
 299 is highly recommended for most encryption purposes, in that
 300 modification of a single bit of the ciphertext will affect ALL the
 301 subsequent (decrypted) cleartext. Similarly, modifying a single bit of
 302 the cleartext will affect ALL the subsequent (encrypted) ciphertext.
 303 "PCBC" mode, on encryption, "xors" both the
 304 cleartext of block N and the ciphertext resulting from block N with the
 305 cleartext for block N+1 prior to encrypting block N+1.
 306 .PP
 307 .I des_cbc_cksum
 308 produces an 8 byte cryptographic checksum by cipher-block-chain
 309 encrypting the cleartext data pointed to by the
 310 .I input
 311 argument. All of the ciphertext output is discarded, except the
 312 last 8-byte ciphertext block, which is written into the area pointed to by
 313 the
 314 .I output
 315 argument.
 316 It uses the key schedule,
 317 provided by the
 318 .I schedule
 319 argument and initialization vector provided by the
 320 .I ivec
 321 argument.
 322 If the
 323 .I length
 324 argument is not an integral
 325 multiple of eight bytes, the last cleartext block is copied to a temp and zero
 326 filled (highest addresses).  The output is ALWAYS eight bytes.
 327 .PP
 328 The routine also returns an unsigned long, which is the last (highest address)
 329 half of the 8 byte checksum computed.
 330 .PP
 331 .PP
 332 .I quad_cksum
 333 produces a checksum by chaining quadratic operations on the cleartext data
 334 pointed to by the
 335 .I input
 336 argument. The
 337 .I length
 338 argument specifies the length of the
 339 input -- only exactly that many bytes are included for the checksum,
 340 without any padding.
 341 .PP
 342 The algorithm may be iterated over the same input data, if the
 343 .I out_count
 344 argument is 2, 3 or 4, and the optional
 345 .I output
 346 argument is a non-null pointer .
 347 The default is one iteration, and it will not run
 348 more than 4 times. Multiple iterations run slower, but provide
 349 a longer checksum if desired. The
 350 .I seed
 351 argument provides an 8-byte seed for the first iteration. If multiple iterations are
 352 requested, the results of one iteration are automatically used as
 353 the seed for the next iteration.
 354 .PP
 355 It returns both an unsigned long checksum value, and
 356 if the
 357 .I output
 358 argument is not a null pointer, up to 16 bytes of
 359 the computed checksum are written into the output.
 360 .PP
 361 .PP
 362 .SH FILES
 363 /usr/include/des.h
 364 .br
 365 /usr/lib/libdes.a
 366 .SH "SEE ALSO"
 367 .SH DIAGNOSTICS
 368 .SH BUGS
 369 This software has not yet been compiled or tested on machines other than the
 370 VAX and the IBM PC.
 371 .SH AUTHORS
 372 Steve Miller, MIT Project Athena/Digital Equipment Corporation
 373 .SH RESTRICTIONS
 374 COPYRIGHT 1985,1986 Massachusetts Institute of Technology
 375 .PP
 376 This software may not be exported outside of the US without a special
 377 license from the US Dept of Commerce. It may be replaced by any secret
 378 key block cipher with block length and key length of 8 bytes, as long
 379 as the interface is the same as described here.