crypto/kerberosIV/man/krb_sendauth.3

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