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