4.4BSD/usr/share/man/cat3/krb_sendauth.0
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 <<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 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 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>.
MIT Project Athena Kerberos Version 4.0 4