4.3BSD-Reno/share/man/cat3/ksend.0

KRB_SENDAUTH(3)                4.0		  KRB_SENDAUTH(3)



NNAAMMEE
     krb_sendauth, krb_recvauth, krb_net_write, krb_net_read -
     Kerberos routines for sending authentication via network
     stream sockets

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<kkeerrbbeerroossIIVV//kkrrbb..hh>>
     ##iinncclluuddee <<kkeerrbbeerroossIIVV//ddeess..hh>>
     ##iinncclluuddee <<nneettiinneett//iinn..hh>>

     iinntt kkrrbb__sseennddaauutthh((ooppttiioonnss,, ffdd,, kktteexxtt,, sseerrvviiccee,, iinnsstt,, rreeaallmm,,
	       cchheecckkssuumm,, mmssgg__ddaattaa,, ccrreedd,, sscchheedduullee,, llaaddddrr,, ffaaddddrr,,
	       vveerrssiioonn))
     lloonngg ooppttiioonnss;;
     iinntt ffdd;;
     KKTTEEXXTT kktteexxtt;;
     cchhaarr **sseerrvviiccee,, **iinnsstt,, **rreeaallmm;;
     uu__lloonngg cchheecckkssuumm;;
     MMSSGG__DDAATT **mmssgg__ddaattaa;;
     CCRREEDDEENNTTIIAALLSS **ccrreedd;;
     KKeeyy__sscchheedduullee sscchheedduullee;;
     ssttrruucctt ssoocckkaaddddrr__iinn **llaaddddrr,, **ffaaddddrr;;
     cchhaarr **vveerrssiioonn;;

     iinntt kkrrbb__rreeccvvaauutthh((ooppttiioonnss,, ffdd,, kktteexxtt,, sseerrvviiccee,, iinnsstt,, ffaaddddrr,,
	       llaaddddrr,, aauutthh__ddaattaa,, ffiilleennaammee,, sscchheedduullee,, vveerrssiioonn))
     lloonngg ooppttiioonnss;;
     iinntt ffdd;;
     KKTTEEXXTT kktteexxtt;;
     cchhaarr **sseerrvviiccee,, **iinnsstt;;
     ssttrruucctt ssoocckkaaddddrr__iinn **ffaaddddrr,, **llaaddddrr;;
     AAUUTTHH__DDAATT **aauutthh__ddaattaa;;
     cchhaarr **ffiilleennaammee;;
     KKeeyy__sscchheedduullee sscchheedduullee;;
     cchhaarr **vveerrssiioonn;;

     iinntt kkrrbb__nneett__wwrriittee((ffdd,, bbuuff,, lleenn))
     iinntt ffdd;;
     cchhaarr **bbuuff;;
     iinntt lleenn;;

     iinntt kkrrbb__nneett__rreeaadd((ffdd,, bbuuff,, lleenn))
     iinntt ffdd;;
     cchhaarr **bbuuff;;
     iinntt lleenn;;

DDEESSCCRRIIPPTTIIOONN
     These functions, which are built on top of the core Kerberos
     library, provide a convenient means for client and server
     programs to send authentication messages to one another
     through network connections.  The _k_r_b__s_e_n_d_a_u_t_h function
     sends an authenticated ticket from the client program to the



Printed 7/27/90             Kerberos				1






KRB_SENDAUTH(3)                4.0		  KRB_SENDAUTH(3)



     server program by writing the ticket to a network socket.
     The _k_r_b__r_e_c_v_a_u_t_h function receives the ticket from the
     client by reading from a network socket.


KKRRBB__SSEENNDDAAUUTTHH
     This function writes the ticket to the network socket speci-
     fied by the file descriptor _f_d, returning KSUCCESS if the
     write proceeds successfully, and an error code if it does
     not.

     The _k_t_e_x_t argument should point to an allocated KTEXT_ST
     structure.  The _s_e_r_v_i_c_e, _i_n_s_t, and _r_e_a_l_m arguments specify
     the server program's Kerberos principal name, instance, and
     realm.  If you are writing a client that uses the local
     realm exclusively, you can set the _r_e_a_l_m argument to NULL.

     The _v_e_r_s_i_o_n argument allows the client program to pass an
     application-specific version string that the server program
     can then match against its own version string.  The _v_e_r_s_i_o_n
     string can be up to KSEND_VNO_LEN (see <_k_r_b._h>) characters
     in length.

     The _c_h_e_c_k_s_u_m argument can be used to pass checksum informa-
     tion to the server program.  The client program is responsi-
     ble for specifying this information.  This checksum informa-
     tion is difficult to corrupt because _k_r_b__s_e_n_d_a_u_t_h passes it
     over the network in encrypted form.  The _c_h_e_c_k_s_u_m argument
     is passed as the checksum argument to _k_r_b__m_k__r_e_q.

     You can set _k_r_b__s_e_n_d_a_u_t_h'_s other arguments to NULL unless
     you want the client and server programs to mutually authen-
     ticate themselves.  In the case of mutual authentication,
     the client authenticates itself to the server program, and
     demands that the server in turn authenticate itself to the
     client.


KKRRBB__SSEENNDDAAUUTTHH AANNDD MMUUTTUUAALL AAUUTTHHEENNTTIICCAATTIIOONN
     If you want mutual authentication, make sure that you read
     all pending data from the local socket before calling
     _k_r_b__s_e_n_d_a_u_t_h.  Set _k_r_b__s_e_n_d_a_u_t_h'_s _o_p_t_i_o_n_s argument to
     KKOOPPTT__DDOO__MMUUTTUUAALL (this macro is defined in the _k_r_b._h file);
     make sure that the _l_a_d_d_r argument points to the address of
     the local socket, and that _f_a_d_d_r points to the foreign
     socket's network address.

     _K_r_b__s_e_n_d_a_u_t_h fills in the other arguments-- _m_s_g__d_a_t_a, _c_r_e_d,
     and _s_c_h_e_d_u_l_e--before sending the ticket to the server pro-
     gram.  You must, however, allocate space for these arguments
     before calling the function.




Printed 7/27/90             Kerberos				2






KRB_SENDAUTH(3)                4.0		  KRB_SENDAUTH(3)



     _K_r_b__s_e_n_d_a_u_t_h supports two other options: KKOOPPTT__DDOONNTT__MMKK__RREEQQ,,
     and KKOOPPTT__DDOONNTT__CCAANNOONN..  If called with _o_p_t_i_o_n_s set as
     KOPT_DONT_MK_REQ, _k_r_b__s_e_n_d_a_u_t_h will not use the _k_r_b__m_k__r_e_q
     function to retrieve the ticket from the Kerberos server.
     The _k_t_e_x_t argument must point to an existing ticket and
     authenticator (such as would be created by _k_r_b__m_k__r_e_q), and
     the _s_e_r_v_i_c_e, _i_n_s_t, and _r_e_a_l_m arguments can be set to NULL.

     If called with _o_p_t_i_o_n_s set as KOPT_DONT_CANON, _k_r_b__s_e_n_d_a_u_t_h
     will not convert the service's instance to canonical form
     using _k_r_b__g_e_t__p_h_o_s_t(3).

     If you want to call _k_r_b__s_e_n_d_a_u_t_h with a multiple _o_p_t_i_o_n_s
     specification, construct _o_p_t_i_o_n_s as a bitwise-OR of the
     options you want to specify.


KKRRBB__RREECCVVAAUUTTHH
     The _k_r_b__r_e_c_v_a_u_t_h function reads a ticket/authenticator pair
     from the socket pointed to by the _f_d argument.  Set the
     _o_p_t_i_o_n_s argument as a bitwise-OR of the options desired.
     Currently only KOPT_DO_MUTUAL is useful to the receiver.

     The _k_t_e_x_t argument should point to an allocated KTEXT_ST
     structure.  _K_r_b__r_e_c_v_a_u_t_h fills _k_t_e_x_t with the
     ticket/authenticator pair read from _f_d, then passes it to
     _k_r_b__r_d__r_e_q.

     The _s_e_r_v_i_c_e and _i_n_s_t arguments specify the expected service
     and instance for which the ticket was generated.  They are
     also passed to _k_r_b__r_d__r_e_q.  The _i_n_s_t argument may be set to
     "*" if the caller wishes _k_r_b__m_k__r_e_q to fill in the instance
     used (note that there must be space in the _i_n_s_t argument to
     hold a full instance name, see _k_r_b__m_k__r_e_q(3)).

     The _f_a_d_d_r argument should point to the address of the peer
     which is presenting the ticket.  It is also passed to
     _k_r_b__r_d__r_e_q.

     If the client and server plan to mutually authenticate one
     another, the _l_a_d_d_r argument should point to the local
     address of the file descriptor.  Otherwise you can set this
     argument to NULL.

     The _a_u_t_h__d_a_t_a argument should point to an allocated AUTH_DAT
     area.  It is passed to and filled in by _k_r_b__r_d__r_e_q.  The
     checksum passed to the corresponding _k_r_b__s_e_n_d_a_u_t_h is avail-
     able as part of the filled-in AUTH_DAT area.

     The _f_i_l_e_n_a_m_e argument specifies the filename which the ser-
     vice program should use to obtain its service key.
     _K_r_b__r_e_c_v_a_u_t_h passes _f_i_l_e_n_a_m_e to the _k_r_b__r_d__r_e_q function.  If



Printed 7/27/90             Kerberos				3






KRB_SENDAUTH(3)                4.0		  KRB_SENDAUTH(3)



     you set this argument to "", _k_r_b__r_d__r_e_q looks for the ser-
     vice key in the file /_e_t_c/_k_e_r_b_e_r_o_s_I_V/_s_r_v_t_a_b.

     If the client and server are performing mutual authenica-
     tion, the _s_c_h_e_d_u_l_e argument should point to an allocated
     Key_schedule.  Otherwise it is ignored and may be NULL.

     The _v_e_r_s_i_o_n argument should point to a character array of at
     least KSEND_VNO_LEN characters.  It is filled in with the
     version string passed by the client to _k_r_b__s_e_n_d_a_u_t_h.

KKRRBB__NNEETT__WWRRIITTEE AANNDD KKRRBB__NNEETT__RREEAADD
     The _k_r_b__n_e_t__w_r_i_t_e function emulates the write(2) system
     call, but guarantees that all data specified is written to
     _f_d before returning, unless an error condition occurs.

     The _k_r_b__n_e_t__r_e_a_d function emulates the read(2) system call,
     but guarantees that the requested amount of data is read
     from _f_d before returning, unless an error condition occurs.

BBUUGGSS
     _k_r_b__s_e_n_d_a_u_t_h, _k_r_b__r_e_c_v_a_u_t_h, _k_r_b__n_e_t__w_r_i_t_e, and _k_r_b__n_e_t__r_e_a_d
     will not work properly on sockets set to non-blocking I/O
     mode.


SSEEEE AALLSSOO
     krb_mk_req(3), krb_rd_req(3), krb_get_phost(3)


AAUUTTHHOORR
     John T. Kohl, MIT Project Athena

RREESSTTRRIICCTTIIOONNSS
     Copyright 1988, Massachusetts Instititute of Technology.
     For copying and distribution information, please see the
     file <mit-copyright.h>.


















Printed 7/27/90             Kerberos				4