![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to krb_sendauth.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_sendauth.3 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / kerberosIV / man |
1.1 root 1: .\" $Source: /usr/src/kerberosIV/man/RCS/krb_sendauth.3,v $
2: .\" $Author: kfall $
3: .\" $Header: /usr/src/kerberosIV/man/RCS/krb_sendauth.3,v 4.2 90/06/25 21:12:26 kfall Exp $
4: .\" Copyright 1988 by the Massachusetts Institute of Technology.
5: .\"
6: .\" For copying and distribution information,
7: .\" please see the file <mit-copyright.h>.
8: .\"
9: .TH KRB_SENDAUTH 3 "Kerberos Version 4.0" "MIT Project Athena"
10: .SH NAME
11: krb_sendauth, krb_recvauth, krb_net_write, krb_net_read \-
12: Kerberos routines for sending authentication via network stream sockets
13: .SH SYNOPSIS
14: .nf
15: .nj
16: .ft B
17: #include <kerberosIV/krb.h>
18: #include <kerberosIV/des.h>
19: #include <netinet/in.h>
20: .PP
21: .fi
22: .HP 1i
23: .ft B
24: int krb_sendauth(options, fd, ktext, service, inst, realm, checksum,
25: msg_data, cred, schedule, laddr, faddr, version)
26: .nf
27: .RS 0
28: .ft B
29: long options;
30: int fd;
31: KTEXT ktext;
32: char *service, *inst, *realm;
33: u_long checksum;
34: MSG_DAT *msg_data;
35: CREDENTIALS *cred;
36: Key_schedule schedule;
37: struct sockaddr_in *laddr, *faddr;
38: char *version;
39: .PP
40: .fi
41: .HP 1i
42: .ft B
43: int krb_recvauth(options, fd, ktext, service, inst, faddr, laddr,
44: auth_data, filename, schedule, version)
45: .nf
46: .RS 0
47: .ft B
48: long options;
49: int fd;
50: KTEXT ktext;
51: char *service, *inst;
52: struct sockaddr_in *faddr, *laddr;
53: AUTH_DAT *auth_data;
54: char *filename;
55: Key_schedule schedule;
56: char *version;
57: .PP
58: .ft B
59: int krb_net_write(fd, buf, len)
60: int fd;
61: char *buf;
62: int len;
63: .PP
64: .ft B
65: int krb_net_read(fd, buf, len)
66: int fd;
67: char *buf;
68: int len;
69: .fi
70: .SH DESCRIPTION
71: .PP
72: These functions,
73: which are built on top of the core Kerberos library,
74: provide a convenient means for client and server
75: programs to send authentication messages
76: to one another through network connections.
77: The
78: .I krb_sendauth
79: function sends an authenticated ticket from the client program to
80: the server program by writing the ticket to a network socket.
81: The
82: .I krb_recvauth
83: function receives the ticket from the client by
84: reading from a network socket.
85:
86: .SH KRB_SENDAUTH
87: .PP
88: This function writes the ticket to
89: the network socket specified by the
90: file descriptor
91: .IR fd,
92: returning KSUCCESS if the write proceeds successfully,
93: and an error code if it does not.
94:
95: The
96: .I ktext
97: argument should point to an allocated KTEXT_ST structure.
98: The
99: .IR service,
100: .IR inst,
101: and
102: .IR realm
103: arguments specify the server program's Kerberos principal name,
104: instance, and realm.
105: If you are writing a client that uses the local realm exclusively,
106: you can set the
107: .I realm
108: argument to NULL.
109:
110: The
111: .I version
112: argument allows the client program to pass an application-specific
113: version string that the server program can then match against
114: its own version string.
115: The
116: .I version
117: string can be up to KSEND_VNO_LEN (see
118: .IR <krb.h> )
119: characters in length.
120:
121: The
122: .I checksum
123: argument can be used to pass checksum information to the
124: server program.
125: The client program is responsible for specifying this information.
126: This checksum information is difficult to corrupt because
127: .I krb_sendauth
128: passes it over the network in encrypted form.
129: The
130: .I checksum
131: argument is passed as the checksum argument to
132: .IR krb_mk_req .
133:
134: You can set
135: .IR krb_sendauth's
136: other arguments to NULL unless you want the
137: client and server programs to mutually authenticate
138: themselves.
139: In the case of mutual authentication,
140: the client authenticates itself to the server program,
141: and demands that the server in turn authenticate itself to
142: the client.
143:
144: .SH KRB_SENDAUTH AND MUTUAL AUTHENTICATION
145: .PP
146: If you want mutual authentication,
147: make sure that you read all pending data from the local socket
148: before calling
149: .IR krb_sendauth.
150: Set
151: .IR krb_sendauth's
152: .I options
153: argument to
154: .BR KOPT_DO_MUTUAL
155: (this macro is defined in the
156: .IR krb.h
157: file);
158: make sure that the
159: .I laddr
160: argument points to
161: the address of the local socket,
162: and that
163: .I faddr
164: points to the foreign socket's network address.
165:
166: .I Krb_sendauth
167: fills in the other arguments--
168: .IR msg_data ,
169: .IR cred ,
170: and
171: .IR schedule --before
172: sending the ticket to the server program.
173: You must, however, allocate space for these arguments
174: before calling the function.
175:
176: .I Krb_sendauth
177: supports two other options:
178: .BR KOPT_DONT_MK_REQ,
179: and
180: .BR KOPT_DONT_CANON.
181: If called with
182: .I options
183: set as KOPT_DONT_MK_REQ,
184: .I krb_sendauth
185: will not use the
186: .I krb_mk_req
187: function to retrieve the ticket from the Kerberos server.
188: The
189: .I ktext
190: argument must point to an existing ticket and authenticator (such as
191: would be created by
192: .IR krb_mk_req ),
193: and the
194: .IR service,
195: .IR inst,
196: and
197: .IR realm
198: arguments can be set to NULL.
199:
200: If called with
201: .I options
202: set as KOPT_DONT_CANON,
203: .I krb_sendauth
204: will not convert the service's instance to canonical form using
205: .IR krb_get_phost (3).
206:
207: If you want to call
208: .I krb_sendauth
209: with a multiple
210: .I options
211: specification,
212: construct
213: .I options
214: as a bitwise-OR of the options you want to specify.
215:
216: .SH KRB_RECVAUTH
217: .PP
218: The
219: .I krb_recvauth
220: function
221: reads a ticket/authenticator pair from the socket pointed to by the
222: .I fd
223: argument.
224: Set the
225: .I options
226: argument
227: as a bitwise-OR of the options desired.
228: Currently only KOPT_DO_MUTUAL is useful to the receiver.
229:
230: The
231: .I ktext
232: argument
233: should point to an allocated KTEXT_ST structure.
234: .I Krb_recvauth
235: fills
236: .I ktext
237: with the
238: ticket/authenticator pair read from
239: .IR fd ,
240: then passes it to
241: .IR krb_rd_req .
242:
243: The
244: .I service
245: and
246: .I inst
247: arguments
248: specify the expected service and instance for which the ticket was
249: generated. They are also passed to
250: .IR krb_rd_req.
251: The
252: .I inst
253: argument may be set to "*" if the caller wishes
254: .I krb_mk_req
255: to fill in the instance used (note that there must be space in the
256: .I inst
257: argument to hold a full instance name, see
258: .IR krb_mk_req (3)).
259:
260: The
261: .I faddr
262: argument
263: should point to the address of the peer which is presenting the ticket.
264: It is also passed to
265: .IR krb_rd_req .
266:
267: If the client and server plan to mutually authenticate
268: one another,
269: the
270: .I laddr
271: argument
272: should point to the local address of the file descriptor.
273: Otherwise you can set this argument to NULL.
274:
275: The
276: .I auth_data
277: argument
278: should point to an allocated AUTH_DAT area.
279: It is passed to and filled in by
280: .IR krb_rd_req .
281: The checksum passed to the corresponding
282: .I krb_sendauth
283: is available as part of the filled-in AUTH_DAT area.
284:
285: The
286: .I filename
287: argument
288: specifies the filename
289: which the service program should use to obtain its service key.
290: .I Krb_recvauth
291: passes
292: .I filename
293: to the
294: .I krb_rd_req
295: function.
296: If you set this argument to "",
297: .I krb_rd_req
298: looks for the service key in the file
299: .IR /etc/kerberosIV/srvtab.
300:
301: If the client and server are performing mutual authenication,
302: the
303: .I schedule
304: argument
305: should point to an allocated Key_schedule.
306: Otherwise it is ignored and may be NULL.
307:
308: The
309: .I version
310: argument should point to a character array of at least KSEND_VNO_LEN
311: characters. It is filled in with the version string passed by the client to
312: .IR krb_sendauth.
313: .PP
314: .SH KRB_NET_WRITE AND KRB_NET_READ
315: .PP
316: The
317: .I krb_net_write
318: function
319: emulates the write(2) system call, but guarantees that all data
320: specified is written to
321: .I fd
322: before returning, unless an error condition occurs.
323: .PP
324: The
325: .I krb_net_read
326: function
327: emulates the read(2) system call, but guarantees that the requested
328: amount of data is read from
329: .I fd
330: before returning, unless an error condition occurs.
331: .PP
332: .SH BUGS
333: .IR krb_sendauth,
334: .IR krb_recvauth,
335: .IR krb_net_write,
336: and
337: .IR krb_net_read
338: will not work properly on sockets set to non-blocking I/O mode.
339:
340: .SH SEE ALSO
341:
342: krb_mk_req(3), krb_rd_req(3), krb_get_phost(3)
343:
344: .SH AUTHOR
345: John T. Kohl, MIT Project Athena
346: .SH RESTRICTIONS
347: Copyright 1988, Massachusetts Instititute of Technology.
348: For copying and distribution information,
349: please see the file <mit-copyright.h>.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.