Commit | Line | Data |
---|---|---|
8f8a9528 JH |
1 | .\" $Source: /home/cvs/386BSD/src/kerberosIV/man/krb.3,v $ |
2 | .\" $Author: wollman $ | |
3 | .\" $Header: /home/cvs/386BSD/src/kerberosIV/man/krb.3,v 1.1.1.1 1994/02/25 01:14:44 wollman Exp $ | |
fdf53e02 GW |
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 KERBEROS 3 "Kerberos Version 4.0" "MIT Project Athena" | |
10 | .SH NAME | |
11 | krb_mk_req, krb_rd_req, krb_kntoln, krb_set_key, krb_get_cred, | |
12 | krb_mk_priv, krb_rd_priv, krb_mk_safe, krb_rd_safe, krb_mk_err, | |
13 | krb_rd_err, krb_ck_repl \- Kerberos authentication library | |
14 | .SH SYNOPSIS | |
15 | .nf | |
16 | .nj | |
17 | .ft B | |
18 | #include <kerberosIV/des.h> | |
19 | #include <kerberosIV/krb.h> | |
20 | .PP | |
21 | .ft B | |
22 | extern char *krb_err_txt[]; | |
23 | .PP | |
24 | .ft B | |
25 | int krb_mk_req(authent,service,instance,realm,checksum) | |
26 | KTEXT authent; | |
27 | char *service; | |
28 | char *instance; | |
29 | char *realm; | |
30 | u_long checksum; | |
31 | .PP | |
32 | .ft B | |
33 | int krb_rd_req(authent,service,instance,from_addr,ad,fn) | |
34 | KTEXT authent; | |
35 | char *service; | |
36 | char *instance; | |
37 | u_long from_addr; | |
38 | AUTH_DAT *ad; | |
39 | char *fn; | |
40 | .PP | |
41 | .ft B | |
42 | int krb_kntoln(ad,lname) | |
43 | AUTH_DAT *ad; | |
44 | char *lname; | |
45 | .PP | |
46 | .ft B | |
47 | int krb_set_key(key,cvt) | |
48 | char *key; | |
49 | int cvt; | |
50 | .PP | |
51 | .ft B | |
52 | int krb_get_cred(service,instance,realm,c) | |
53 | char *service; | |
54 | char *instance; | |
55 | char *realm; | |
56 | CREDENTIALS *c; | |
57 | .PP | |
58 | .ft B | |
59 | long krb_mk_priv(in,out,in_length,schedule,key,sender,receiver) | |
60 | u_char *in; | |
61 | u_char *out; | |
62 | u_long in_length; | |
63 | des_cblock key; | |
64 | des_key_schedule schedule; | |
65 | struct sockaddr_in *sender; | |
66 | struct sockaddr_in *receiver; | |
67 | .PP | |
68 | .ft B | |
69 | long krb_rd_priv(in,in_length,schedule,key,sender,receiver,msg_data) | |
70 | u_char *in; | |
71 | u_long in_length; | |
72 | Key_schedule schedule; | |
73 | des_cblock key; | |
74 | struct sockaddr_in *sender; | |
75 | struct sockaddr_in *receiver; | |
76 | MSG_DAT *msg_data; | |
77 | .PP | |
78 | .ft B | |
79 | long krb_mk_safe(in,out,in_length,key,sender,receiver) | |
80 | u_char *in; | |
81 | u_char *out; | |
82 | u_long in_length; | |
83 | des_cblock key; | |
84 | struct sockaddr_in *sender; | |
85 | struct sockaddr_in *receiver; | |
86 | .PP | |
87 | .ft B | |
88 | long krb_rd_safe(in,length,key,sender,receiver,msg_data) | |
89 | u_char *in; | |
90 | u_long length; | |
91 | des_cblock key; | |
92 | struct sockaddr_in *sender; | |
93 | struct sockaddr_in *receiver; | |
94 | MSG_DAT *msg_data; | |
95 | .PP | |
96 | .ft B | |
97 | long krb_mk_err(out,code,string) | |
98 | u_char *out; | |
99 | long code; | |
100 | char *string; | |
101 | .PP | |
102 | .ft B | |
103 | long krb_rd_err(in,length,code,msg_data) | |
104 | u_char *in; | |
105 | u_long length; | |
106 | long code; | |
107 | MSG_DAT *msg_data; | |
108 | .fi | |
109 | .ft R | |
110 | .SH DESCRIPTION | |
111 | This library supports network authentication and various related | |
112 | operations. The library contains many routines beyond those described | |
113 | in this man page, but they are not intended to be used directly. | |
114 | Instead, they are called by the routines that are described, the | |
115 | authentication server and the login program. | |
116 | .PP | |
117 | .I krb_err_txt[] | |
118 | contains text string descriptions of various Kerberos error codes returned | |
119 | by some of the routines below. | |
120 | .PP | |
121 | .I krb_mk_req | |
122 | takes a pointer to a text structure in which an authenticator is to be | |
123 | built. It also takes the name, instance, and realm of the service to be | |
124 | used and an optional checksum. It is up to the application to decide | |
125 | how to generate the checksum. | |
126 | .I krb_mk_req | |
127 | then retrieves a ticket for the desired service and creates an | |
128 | authenticator. The authenticator is built in | |
129 | .I authent | |
130 | and is accessible | |
131 | to the calling procedure. | |
132 | .PP | |
133 | It is up to the application to get the authenticator to the service | |
134 | where it will be read by | |
135 | .I krb_rd_req. | |
8f8a9528 | 136 | Unless an attacker possesses the session key contained in the ticket, it |
fdf53e02 GW |
137 | will be unable to modify the authenticator. Thus, the checksum can be |
138 | used to verify the authenticity of the other data that will pass through | |
139 | a connection. | |
140 | .PP | |
141 | .I krb_rd_req | |
142 | takes an authenticator of type | |
143 | .B KTEXT, | |
144 | a service name, an instance, the address of the | |
145 | host originating the request, and a pointer to a structure of type | |
146 | .B AUTH_DAT | |
147 | which is filled in with information obtained from the authenticator. | |
148 | It also optionally takes the name of the file in which it will find the | |
149 | secret key(s) for the service. | |
150 | If the supplied | |
151 | .I instance | |
152 | contains "*", then the first service key with the same service name | |
153 | found in the service key file will be used, and the | |
154 | .I instance | |
155 | argument will be filled in with the chosen instance. This means that | |
156 | the caller must provide space for such an instance name. | |
157 | .PP | |
158 | It is used to find out information about the principal when a request | |
159 | has been made to a service. It is up to the application protocol to get | |
160 | the authenticator from the client to the service. The authenticator is | |
161 | then passed to | |
162 | .I krb_rd_req | |
163 | to extract the desired information. | |
164 | .PP | |
165 | .I krb_rd_req | |
166 | returns zero (RD_AP_OK) upon successful authentication. If a packet was | |
167 | forged, modified, or replayed, authentication will fail. If the | |
168 | authentication fails, a non-zero value is returned indicating the | |
169 | particular problem encountered. See | |
170 | .I krb.h | |
171 | for the list of error codes. | |
172 | .PP | |
173 | If the last argument is the null string (""), krb_rd_req will use the | |
174 | file /etc/srvtab to find its keys. If the last argument is NULL, it | |
175 | will assume that the key has been set by | |
176 | .I krb_set_key | |
177 | and will not bother looking further. | |
178 | .PP | |
179 | .I krb_kntoln | |
180 | converts a Kerberos name to a local name. It takes a structure | |
181 | of type AUTH_DAT and uses the name and instance to look in the database | |
182 | /etc/aname to find the corresponding local name. The local name is | |
183 | returned and can be used by an application to change uids, directories, | |
184 | or other parameters. It is not an integral part of Kerberos, but is | |
185 | instead provided to support the use of Kerberos in existing utilities. | |
186 | .PP | |
187 | .I krb_set_key | |
188 | takes as an argument a des key. It then creates | |
189 | a key schedule from it and saves the original key to be used as an | |
190 | initialization vector. | |
191 | It is used to set the server's key which | |
192 | must be used to decrypt tickets. | |
193 | .PP | |
194 | If called with a non-zero second argument, | |
195 | .I krb_set_key | |
196 | will first convert the input from a string of arbitrary length to a DES | |
197 | key by encrypting it with a one-way function. | |
198 | .PP | |
199 | In most cases it should not be necessary to call | |
200 | .I krb_set_key. | |
201 | The necessary keys will usually be obtained and set inside | |
202 | .I krb_rd_req. krb_set_key | |
203 | is provided for those applications that do not wish to place the | |
204 | application keys on disk. | |
205 | .PP | |
206 | .I krb_get_cred | |
207 | searches the caller's ticket file for a ticket for the given service, instance, | |
208 | and realm; and, if a ticket is found, fills in the given CREDENTIALS structure | |
209 | with the ticket information. | |
210 | .PP | |
211 | If the ticket was found, | |
212 | .I krb_get_cred | |
213 | returns GC_OK. | |
214 | If the ticket file can't be found, can't be read, doesn't belong to | |
215 | the user (other than root), isn't a regular file, or is in the wrong | |
216 | mode, the error GC_TKFIL is returned. | |
217 | .PP | |
218 | .I krb_mk_priv | |
219 | creates an encrypted, authenticated | |
220 | message from any arbitrary application data, pointed to by | |
221 | .I in | |
222 | and | |
223 | .I in_length | |
224 | bytes long. | |
225 | The private session key, pointed to by | |
226 | .I key | |
227 | and the key schedule, | |
228 | .I schedule, | |
229 | are used to encrypt the data and some header information using | |
230 | .I pcbc_encrypt. | |
231 | .I sender | |
232 | and | |
233 | .I receiver | |
234 | point to the Internet address of the two parties. | |
235 | In addition to providing privacy, this protocol message protects | |
236 | against modifications, insertions or replays. The encapsulated message and | |
237 | header are placed in the area pointed to by | |
238 | .I out | |
239 | and the routine returns the length of the output, or -1 indicating | |
240 | an error. | |
241 | .PP | |
242 | .I krb_rd_priv | |
243 | decrypts and authenticates a received | |
244 | .I krb_mk_priv | |
245 | message. | |
246 | .I in | |
247 | points to the beginning of the received message, whose length | |
248 | is specified in | |
249 | .I in_length. | |
250 | The private session key, pointed to by | |
251 | .I key, | |
252 | and the key schedule, | |
253 | .I schedule, | |
254 | are used to decrypt and verify the received message. | |
255 | .I msg_data | |
256 | is a pointer to a | |
257 | .I MSG_DAT | |
258 | struct, defined in | |
259 | .I krb.h. | |
260 | The routine fills in the | |
261 | .I app_data | |
262 | field with a pointer to the decrypted application data, | |
263 | .I app_length | |
264 | with the length of the | |
265 | .I app_data | |
266 | field, | |
267 | .I time_sec | |
268 | and | |
269 | .I time_5ms | |
270 | with the timestamps in the message, and | |
271 | .I swap | |
272 | with a 1 if the byte order of the receiver is different than that of | |
273 | the sender. (The application must still determine if it is appropriate | |
274 | to byte-swap application data; the Kerberos protocol fields are already taken | |
275 | care of). The | |
276 | .I hash | |
277 | field returns a value useful as input to the | |
278 | .I krb_ck_repl | |
279 | routine. | |
280 | ||
281 | The routine returns zero if ok, or a Kerberos error code. Modified messages | |
282 | and old messages cause errors, but it is up to the caller to | |
283 | check the time sequence of messages, and to check against recently replayed | |
284 | messages using | |
285 | .I krb_ck_repl | |
286 | if so desired. | |
287 | .PP | |
288 | .I krb_mk_safe | |
289 | creates an authenticated, but unencrypted message from any arbitrary | |
290 | application data, | |
291 | pointed to by | |
292 | .I in | |
293 | and | |
294 | .I in_length | |
295 | bytes long. | |
296 | The private session key, pointed to by | |
297 | .I key, | |
298 | is used to seed the | |
299 | .I quad_cksum() | |
300 | checksum algorithm used as part of the authentication. | |
301 | .I sender | |
302 | and | |
303 | .I receiver | |
304 | point to the Internet address of the two parties. | |
305 | This message does not provide privacy, but does protect (via detection) | |
306 | against modifications, insertions or replays. The encapsulated message and | |
307 | header are placed in the area pointed to by | |
308 | .I out | |
309 | and the routine returns the length of the output, or -1 indicating | |
310 | an error. | |
311 | The authentication provided by this routine is not as strong as that | |
312 | provided by | |
313 | .I krb_mk_priv | |
314 | or by computing the checksum using | |
315 | .I cbc_cksum | |
316 | instead, both of which authenticate via DES. | |
317 | .PP | |
318 | ||
319 | .I krb_rd_safe | |
320 | authenticates a received | |
321 | .I krb_mk_safe | |
322 | message. | |
323 | .I in | |
324 | points to the beginning of the received message, whose length | |
325 | is specified in | |
326 | .I in_length. | |
327 | The private session key, pointed to by | |
328 | .I key, | |
329 | is used to seed the quad_cksum() routine as part of the authentication. | |
330 | .I msg_data | |
331 | is a pointer to a | |
332 | .I MSG_DAT | |
333 | struct, defined in | |
334 | .I krb.h . | |
335 | The routine fills in these | |
336 | .I MSG_DAT | |
337 | fields: | |
338 | the | |
339 | .I app_data | |
340 | field with a pointer to the application data, | |
341 | .I app_length | |
342 | with the length of the | |
343 | .I app_data | |
344 | field, | |
345 | .I time_sec | |
346 | and | |
347 | .I time_5ms | |
348 | with the timestamps in the message, and | |
349 | .I swap | |
350 | with a 1 if the byte order of the receiver is different than that of | |
351 | the sender. | |
352 | (The application must still determine if it is appropriate | |
353 | to byte-swap application data; the Kerberos protocol fields are already taken | |
354 | care of). The | |
355 | .I hash | |
356 | field returns a value useful as input to the | |
357 | .I krb_ck_repl | |
358 | routine. | |
359 | ||
360 | The routine returns zero if ok, or a Kerberos error code. Modified messages | |
361 | and old messages cause errors, but it is up to the caller to | |
362 | check the time sequence of messages, and to check against recently replayed | |
363 | messages using | |
364 | .I krb_ck_repl | |
365 | if so desired. | |
366 | .PP | |
367 | .I krb_mk_err | |
368 | constructs an application level error message that may be used along | |
369 | with | |
370 | .I krb_mk_priv | |
371 | or | |
372 | .I krb_mk_safe. | |
373 | .I out | |
374 | is a pointer to the output buffer, | |
375 | .I code | |
376 | is an application specific error code, and | |
377 | .I string | |
378 | is an application specific error string. | |
379 | ||
380 | .PP | |
381 | .I krb_rd_err | |
382 | unpacks a received | |
383 | .I krb_mk_err | |
384 | message. | |
385 | .I in | |
386 | points to the beginning of the received message, whose length | |
387 | is specified in | |
388 | .I in_length. | |
389 | .I code | |
390 | is a pointer to a value to be filled in with the error | |
391 | value provided by the application. | |
392 | .I msg_data | |
393 | is a pointer to a | |
394 | .I MSG_DAT | |
395 | struct, defined in | |
396 | .I krb.h . | |
397 | The routine fills in these | |
398 | .I MSG_DAT | |
399 | fields: the | |
400 | .I app_data | |
401 | field with a pointer to the application error text, | |
402 | .I app_length | |
403 | with the length of the | |
404 | .I app_data | |
405 | field, and | |
406 | .I swap | |
407 | with a 1 if the byte order of the receiver is different than that of | |
408 | the sender. (The application must still determine if it is appropriate | |
409 | to byte-swap application data; the Kerberos protocol fields are already taken | |
410 | care of). | |
411 | ||
412 | The routine returns zero if the error message has been successfully received, | |
413 | or a Kerberos error code. | |
414 | .PP | |
415 | The | |
416 | .I KTEXT | |
417 | structure is used to pass around text of varying lengths. It consists | |
418 | of a buffer for the data, and a length. krb_rd_req takes an argument of this | |
419 | type containing the authenticator, and krb_mk_req returns the | |
420 | authenticator in a structure of this type. KTEXT itself is really a | |
421 | pointer to the structure. The actual structure is of type KTEXT_ST. | |
422 | .PP | |
423 | The | |
424 | .I AUTH_DAT | |
425 | structure is filled in by krb_rd_req. It must be allocated before | |
426 | calling krb_rd_req, and a pointer to it is passed. The structure is | |
427 | filled in with data obtained from Kerberos. | |
428 | .I MSG_DAT | |
429 | structure is filled in by either krb_rd_priv, krb_rd_safe, or | |
430 | krb_rd_err. It must be allocated before the call and a pointer to it | |
431 | is passed. The structure is | |
432 | filled in with data obtained from Kerberos. | |
433 | .PP | |
434 | .SH FILES | |
435 | /usr/include/kerberosIV/krb.h | |
436 | .br | |
437 | /usr/lib/libkrb.a | |
438 | .br | |
439 | /usr/include/kerberosIV/des.h | |
440 | .br | |
441 | /usr/lib/libdes.a | |
442 | .br | |
443 | /etc/kerberosIV/aname | |
444 | .br | |
445 | /etc/kerberosIV/srvtab | |
446 | .br | |
447 | /tmp/tkt[uid] | |
448 | .SH "SEE ALSO" | |
449 | kerberos(1), des_crypt(3) | |
450 | .SH DIAGNOSTICS | |
451 | .SH BUGS | |
452 | The caller of | |
453 | .I krb_rd_req, krb_rd_priv, and krb_rd_safe | |
454 | must check time order and for replay attempts. | |
455 | .I krb_ck_repl | |
456 | is not implemented yet. | |
457 | .SH AUTHORS | |
458 | Clifford Neuman, MIT Project Athena | |
459 | .br | |
460 | Steve Miller, MIT Project Athena/Digital Equipment Corporation | |
461 | .SH RESTRICTIONS | |
462 | COPYRIGHT 1985,1986,1989 Massachusetts Institute of Technology |