KRB_SENDAUTH(3) BSD Programmer's Manual 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 <> ##iinncclluuddee <> ##iinncclluuddee <> 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 Ker- beros library, provide a convenient means for client and MIT Project Athena Kerberos Version 4.0 1 KRB_SENDAUTH(3) BSD Programmer's Manual KRB_SENDAUTH(3) 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 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 specified 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 pro- gram 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 infor- mation to the server program. The client program is responsible for specifying this information. This check- sum information 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 authenticate themselves. In the case of mutual authenti- cation, the client authenticates itself to the server pro- gram, 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. MIT Project Athena Kerberos Version 4.0 2 KRB_SENDAUTH(3) BSD Programmer's Manual KRB_SENDAUTH(3) _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 program. You must, however, allocate space for these arguments before calling the function. _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 ser- vice 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. MIT Project Athena Kerberos Version 4.0 3 KRB_SENDAUTH(3) BSD Programmer's Manual KRB_SENDAUTH(3) 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 available as part of the filled-in AUTH_DAT area. The _f_i_l_e_n_a_m_e argument specifies the filename which the service 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 you set this argument to "", _k_r_b___r_d___r_e_q looks for the service 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 authentica- 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 Project Athena Kerberos Version 4.0 4