Return to krb_sendauth.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / kerberosIV / man

Annotation of 43BSDReno/kerberosIV/man/krb_sendauth.3, revision 1.1

1.1     ! root        1: .\" $Source: /usr/src/kerberosIV/man/RCS/krb_sendauth.3,v $
        !             2: .\" $Author: kfall $
        !             3: .\" $Header: /usr/src/kerberosIV/man/RCS/krb_sendauth.3,v 4.2 90/06/25 21:12:26 kfall 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 <kerberosIV/krb.h>
        !            18: #include <kerberosIV/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/kerberosIV/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>.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.