![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to krb.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 krb.3 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / kerberosIV / man |
1.1 root 1: .\" $Source: /usr/src/kerberosIV/man/RCS/kerberos.3,v $
2: .\" $Author: kfall $
3: .\" $Header: /usr/src/kerberosIV/man/RCS/kerberos.3,v 4.10 90/06/25 21:12:11 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 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.
136: Unless an attacker posesses the session key contained in the ticket, it
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
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.