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.
4 .\" For copying and distribution information,
5 .\" please see the file <mit-copyright.h>.
7 .TH DES_CRYPT 3 "Kerberos Version 4.0" "MIT Project Athena"
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
19 .B int des_read_password(key,prompt,verify)
25 int des_string_to_key(str,key)
30 int des_random_key(key)
34 int des_set_key(key,schedule)
36 des_key_schedule schedule;
39 int des_ecb_encrypt(input,output,schedule,encrypt)
42 des_key_schedule schedule;
46 int des_cbc_encrypt(input,output,length,schedule,ivec,encrypt)
50 des_key_schedule schedule;
55 int des_pcbc_encrypt(input,output,length,schedule,ivec,encrypt)
59 des_key_schedule schedule;
64 unsigned long des_cbc_cksum(input,output,length,schedule,ivec)
68 des_key_schedule schedule;
72 unsigned long quad_cksum(input,output,length,out_count,seed)
81 This library supports various DES encryption related operations. It differs
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.
88 For each key that may be simultaneously active, create a
91 defined in "des.h". Next, create key schedules (from the 8-byte keys) as
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,
103 or, to generate a cryptographic checksum, use
111 struct is an 8 byte block used as the fundamental unit for DES data and
112 keys, and is defined as:
114 .B typedef unsigned char des_cblock[8];
120 .B typedef struct des_ks_struct {des_cblock _;} des_key_schedule[16];
123 writes the string specified by
126 output, turns off echo (if possible)
127 and reads an input string from standard input until terminated with a newline.
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
135 converts the input string into a valid DES key, internally
138 routine. The newly created key is copied to the
139 area pointed to by the
143 returns a zero if no errors occurred, or a -1
144 indicating that an error
145 occurred trying to manipulate the terminal echo.
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.
155 argument is a pointer to the string, and
160 supplied by the caller to receive the generated key.
161 No meaningful value is returned. Void is not used for compatibility with
166 generates a random DES encryption key (eight bytes), set to odd parity per
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
180 No meaningful value is returned. Void is not used for compatibility
181 with other compilers.
185 calculates a key schedule from all eight bytes of the input key, pointed
188 argument, and outputs the schedule into the
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.
204 is the basic DES encryption routine that encrypts or decrypts a single 8-byte
206 .B electronic code book
207 mode. It always transforms the input data, pointed to by
209 into the output data, pointed to by the
215 argument is non-zero, the
217 (cleartext) is encrypted into the
219 (ciphertext) using the key_schedule specified by the
221 argument, previously set via
224 If encrypt is zero, the
226 (now ciphertext) is decrypted into the
230 Input and output may overlap.
232 No meaningful value is returned. Void is not used for compatibility
233 with other compilers.
237 encrypts/decrypts using the
238 .B cipher-block-chaining mode of DES.
241 argument is non-zero, the routine cipher-block-chain encrypts
242 the cleartext data pointed to by the
244 argument into the ciphertext pointed to by the
246 argument, using the key schedule provided by the
248 argument, and initialization vector provided by the
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
260 is zero, the routine cipher-block chain decrypts the (now) ciphertext
261 data pointed to by the
263 argument into (now) cleartext pointed to by the
265 argument using the key schedule provided by the
267 argument, and initialization vector provided by the
269 argument. Decryption ALWAYS operates on integral
270 multiples of 8 bytes, so it will round 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.
278 No errors or meaningful values are returned. Void is not used for
279 compatibility with other compilers.
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,
288 is STRONGLY recommended for applications where
289 indefinite propagation of errors is required in order to detect modifications.
293 encrypts/decrypts using a modified block chaining mode. Its calling
294 sequence is identical to
296 It differs in its error propagation characteristics.
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.
308 produces an 8 byte cryptographic checksum by cipher-block-chain
309 encrypting the cleartext data pointed to by the
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
316 It uses the key schedule,
319 argument and initialization vector provided by the
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.
328 The routine also returns an unsigned long, which is the last (highest address)
329 half of the 8 byte checksum computed.
333 produces a checksum by chaining quadratic operations on the cleartext data
338 argument specifies the length of the
339 input -- only exactly that many bytes are included for the checksum,
342 The algorithm may be iterated over the same input data, if the
344 argument is 2, 3 or 4, and the optional
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
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.
355 It returns both an unsigned long checksum value, and
358 argument is not a null pointer, up to 16 bytes of
359 the computed checksum are written into the output.
369 This software has not yet been compiled or tested on machines other than the
372 Steve Miller, MIT Project Athena/Digital Equipment Corporation
374 COPYRIGHT 1985,1986 Massachusetts Institute of Technology
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.