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 .\" $DragonFly: src/crypto/kerberosIV/man/Attic/krb_sendauth.3,v 1.2 2003/06/17 04:24:36 dillon 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 <krb.h>
  18 #include <openssl/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/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>.