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