crypto/kerberosIV/man/kerberos.3

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