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 .\" $DragonFly: src/crypto/kerberosIV/man/Attic/kerberos.3,v 1.2 2003/06/17 04:24:36 dillon 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 <openssl/des.h>
  19 #include <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/krb.h
 436 .br
 437 /usr/lib/libkrb.a
 438 .br
 439 /usr/include/des.h
 440 .br
 441 /usr/lib/libdes.a
 442 .br
 443 /etc/aname
 444 .br
 445 /etc/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