usr/share/man/cat3/ksend.0



KRB_SENDAUTH(3)                4.0                KRB_SENDAUTH(3)


N\bNA\bAM\bME\bE
     krb_sendauth, krb_recvauth, krb_net_write, krb_net_read -
     Kerberos routines for sending authentication via network
     stream sockets

S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
     #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<k\bke\ber\brb\bbe\ber\bro\bos\bsI\bIV\bV/\b/k\bkr\brb\bb.\b.h\bh>\b>
     #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<k\bke\ber\brb\bbe\ber\bro\bos\bsI\bIV\bV/\b/d\bde\bes\bs.\b.h\bh>\b>
     #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<n\bne\bet\bti\bin\bne\bet\bt/\b/i\bin\bn.\b.h\bh>\b>

     i\bin\bnt\bt k\bkr\brb\bb_\b_s\bse\ben\bnd\bda\bau\but\bth\bh(\b(o\bop\bpt\bti\bio\bon\bns\bs,\b, f\bfd\bd,\b, k\bkt\bte\bex\bxt\bt,\b, s\bse\ber\brv\bvi\bic\bce\be,\b, i\bin\bns\bst\bt,\b, r\bre\bea\bal\blm\bm,\b,
               c\bch\bhe\bec\bck\bks\bsu\bum\bm,\b, m\bms\bsg\bg_\b_d\bda\bat\bta\ba,\b, c\bcr\bre\bed\bd,\b, s\bsc\bch\bhe\bed\bdu\bul\ble\be,\b, l\bla\bad\bdd\bdr\br,\b, f\bfa\bad\bdd\bdr\br,\b,
               v\bve\ber\brs\bsi\bio\bon\bn)\b)
     l\blo\bon\bng\bg o\bop\bpt\bti\bio\bon\bns\bs;\b;
     i\bin\bnt\bt f\bfd\bd;\b;
     K\bKT\bTE\bEX\bXT\bT k\bkt\bte\bex\bxt\bt;\b;
     c\bch\bha\bar\br *\b*s\bse\ber\brv\bvi\bic\bce\be,\b, *\b*i\bin\bns\bst\bt,\b, *\b*r\bre\bea\bal\blm\bm;\b;
     u\bu_\b_l\blo\bon\bng\bg c\bch\bhe\bec\bck\bks\bsu\bum\bm;\b;
     M\bMS\bSG\bG_\b_D\bDA\bAT\bT *\b*m\bms\bsg\bg_\b_d\bda\bat\bta\ba;\b;
     C\bCR\bRE\bED\bDE\bEN\bNT\bTI\bIA\bAL\bLS\bS *\b*c\bcr\bre\bed\bd;\b;
     K\bKe\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;
     s\bst\btr\bru\buc\bct\bt s\bso\boc\bck\bka\bad\bdd\bdr\br_\b_i\bin\bn *\b*l\bla\bad\bdd\bdr\br,\b, *\b*f\bfa\bad\bdd\bdr\br;\b;
     c\bch\bha\bar\br *\b*v\bve\ber\brs\bsi\bio\bon\bn;\b;

     i\bin\bnt\bt k\bkr\brb\bb_\b_r\bre\bec\bcv\bva\bau\but\bth\bh(\b(o\bop\bpt\bti\bio\bon\bns\bs,\b, f\bfd\bd,\b, k\bkt\bte\bex\bxt\bt,\b, s\bse\ber\brv\bvi\bic\bce\be,\b, i\bin\bns\bst\bt,\b, f\bfa\bad\bdd\bdr\br,\b,
               l\bla\bad\bdd\bdr\br,\b, a\bau\but\bth\bh_\b_d\bda\bat\bta\ba,\b, f\bfi\bil\ble\ben\bna\bam\bme\be,\b, s\bsc\bch\bhe\bed\bdu\bul\ble\be,\b, v\bve\ber\brs\bsi\bio\bon\bn)\b)
     l\blo\bon\bng\bg o\bop\bpt\bti\bio\bon\bns\bs;\b;
     i\bin\bnt\bt f\bfd\bd;\b;
     K\bKT\bTE\bEX\bXT\bT k\bkt\bte\bex\bxt\bt;\b;
     c\bch\bha\bar\br *\b*s\bse\ber\brv\bvi\bic\bce\be,\b, *\b*i\bin\bns\bst\bt;\b;
     s\bst\btr\bru\buc\bct\bt s\bso\boc\bck\bka\bad\bdd\bdr\br_\b_i\bin\bn *\b*f\bfa\bad\bdd\bdr\br,\b, *\b*l\bla\bad\bdd\bdr\br;\b;
     A\bAU\bUT\bTH\bH_\b_D\bDA\bAT\bT *\b*a\bau\but\bth\bh_\b_d\bda\bat\bta\ba;\b;
     c\bch\bha\bar\br *\b*f\bfi\bil\ble\ben\bna\bam\bme\be;\b;
     K\bKe\bey\by_\b_s\bsc\bch\bhe\bed\bdu\bul\ble\be s\bsc\bch\bhe\bed\bdu\bul\ble\be;\b;
     c\bch\bha\bar\br *\b*v\bve\ber\brs\bsi\bio\bon\bn;\b;

     i\bin\bnt\bt k\bkr\brb\bb_\b_n\bne\bet\bt_\b_w\bwr\bri\bit\bte\be(\b(f\bfd\bd,\b, b\bbu\buf\bf,\b, l\ble\ben\bn)\b)
     i\bin\bnt\bt f\bfd\bd;\b;
     c\bch\bha\bar\br *\b*b\bbu\buf\bf;\b;
     i\bin\bnt\bt l\ble\ben\bn;\b;

     i\bin\bnt\bt k\bkr\brb\bb_\b_n\bne\bet\bt_\b_r\bre\bea\bad\bd(\b(f\bfd\bd,\b, b\bbu\buf\bf,\b, l\ble\ben\bn)\b)
     i\bin\bnt\bt f\bfd\bd;\b;
     c\bch\bha\bar\br *\b*b\bbu\buf\bf;\b;
     i\bin\bnt\bt l\ble\ben\bn;\b;

D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
     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 _\bk_\br_\bb__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh 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 _\bk_\br_\bb__\br_\be_\bc_\bv_\ba_\bu_\bt_\bh function receives the ticket from the
     client by reading from a network socket.


K\bKR\bRB\bB_\b_S\bSE\bEN\bND\bDA\bAU\bUT\bTH\bH
     This function writes the ticket to the network socket speci-
     fied by the file descriptor _\bf_\bd, returning KSUCCESS if the
     write proceeds successfully, and an error code if it does
     not.

     The _\bk_\bt_\be_\bx_\bt argument should point to an allocated KTEXT_ST
     structure.  The _\bs_\be_\br_\bv_\bi_\bc_\be, _\bi_\bn_\bs_\bt, and _\br_\be_\ba_\bl_\bm 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 _\br_\be_\ba_\bl_\bm argument to NULL.

     The _\bv_\be_\br_\bs_\bi_\bo_\bn 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 _\bv_\be_\br_\bs_\bi_\bo_\bn
     string can be up to KSEND_VNO_LEN (see <_\bk_\br_\bb._\bh>) characters
     in length.

     The _\bc_\bh_\be_\bc_\bk_\bs_\bu_\bm 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 _\bk_\br_\bb__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh passes it
     over the network in encrypted form.  The _\bc_\bh_\be_\bc_\bk_\bs_\bu_\bm argument
     is passed as the checksum argument to _\bk_\br_\bb__\bm_\bk__\br_\be_\bq.

     You can set _\bk_\br_\bb__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh'_\bs 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.


K\bKR\bRB\bB_\b_S\bSE\bEN\bND\bDA\bAU\bUT\bTH\bH A\bAN\bND\bD M\bMU\bUT\bTU\bUA\bAL\bL A\bAU\bUT\bTH\bHE\bEN\bNT\bTI\bIC\bCA\bAT\bTI\bIO\bON\bN
     If you want mutual authentication, make sure that you read
     all pending data from the local socket before calling
     _\bk_\br_\bb__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh.  Set _\bk_\br_\bb__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh'_\bs _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument to
     K\bKO\bOP\bPT\bT_\b_D\bDO\bO_\b_M\bMU\bUT\bTU\bUA\bAL\bL (this macro is defined in the _\bk_\br_\bb._\bh file);
     make sure that the _\bl_\ba_\bd_\bd_\br argument points to the address of
     the local socket, and that _\bf_\ba_\bd_\bd_\br points to the foreign
     socket's network address.

     _\bK_\br_\bb__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh fills in the other arguments-- _\bm_\bs_\bg__\bd_\ba_\bt_\ba, _\bc_\br_\be_\bd,
     and _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be--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)


     _\bK_\br_\bb__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh supports two other options: K\bKO\bOP\bPT\bT_\b_D\bDO\bON\bNT\bT_\b_M\bMK\bK_\b_R\bRE\bEQ\bQ,\b,
     and K\bKO\bOP\bPT\bT_\b_D\bDO\bON\bNT\bT_\b_C\bCA\bAN\bNO\bON\bN.\b.  If called with _\bo_\bp_\bt_\bi_\bo_\bn_\bs set as
     KOPT_DONT_MK_REQ, _\bk_\br_\bb__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh will not use the _\bk_\br_\bb__\bm_\bk__\br_\be_\bq
     function to retrieve the ticket from the Kerberos server.
     The _\bk_\bt_\be_\bx_\bt argument must point to an existing ticket and
     authenticator (such as would be created by _\bk_\br_\bb__\bm_\bk__\br_\be_\bq), and
     the _\bs_\be_\br_\bv_\bi_\bc_\be, _\bi_\bn_\bs_\bt, and _\br_\be_\ba_\bl_\bm arguments can be set to NULL.

     If called with _\bo_\bp_\bt_\bi_\bo_\bn_\bs set as KOPT_DONT_CANON, _\bk_\br_\bb__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh
     will not convert the service's instance to canonical form
     using _\bk_\br_\bb__\bg_\be_\bt__\bp_\bh_\bo_\bs_\bt(3).

     If you want to call _\bk_\br_\bb__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh with a multiple _\bo_\bp_\bt_\bi_\bo_\bn_\bs
     specification, construct _\bo_\bp_\bt_\bi_\bo_\bn_\bs as a bitwise-OR of the
     options you want to specify.


K\bKR\bRB\bB_\b_R\bRE\bEC\bCV\bVA\bAU\bUT\bTH\bH
     The _\bk_\br_\bb__\br_\be_\bc_\bv_\ba_\bu_\bt_\bh function reads a ticket/authenticator pair
     from the socket pointed to by the _\bf_\bd argument.  Set the
     _\bo_\bp_\bt_\bi_\bo_\bn_\bs argument as a bitwise-OR of the options desired.
     Currently only KOPT_DO_MUTUAL is useful to the receiver.

     The _\bk_\bt_\be_\bx_\bt argument should point to an allocated KTEXT_ST
     structure.  _\bK_\br_\bb__\br_\be_\bc_\bv_\ba_\bu_\bt_\bh fills _\bk_\bt_\be_\bx_\bt with the
     ticket/authenticator pair read from _\bf_\bd, then passes it to
     _\bk_\br_\bb__\br_\bd__\br_\be_\bq.

     The _\bs_\be_\br_\bv_\bi_\bc_\be and _\bi_\bn_\bs_\bt arguments specify the expected service
     and instance for which the ticket was generated.  They are
     also passed to _\bk_\br_\bb__\br_\bd__\br_\be_\bq.  The _\bi_\bn_\bs_\bt argument may be set to
     "*" if the caller wishes _\bk_\br_\bb__\bm_\bk__\br_\be_\bq to fill in the instance
     used (note that there must be space in the _\bi_\bn_\bs_\bt argument to
     hold a full instance name, see _\bk_\br_\bb__\bm_\bk__\br_\be_\bq(3)).

     The _\bf_\ba_\bd_\bd_\br argument should point to the address of the peer
     which is presenting the ticket.  It is also passed to
     _\bk_\br_\bb__\br_\bd__\br_\be_\bq.

     If the client and server plan to mutually authenticate one
     another, the _\bl_\ba_\bd_\bd_\br argument should point to the local
     address of the file descriptor.  Otherwise you can set this
     argument to NULL.

     The _\ba_\bu_\bt_\bh__\bd_\ba_\bt_\ba argument should point to an allocated AUTH_DAT
     area.  It is passed to and filled in by _\bk_\br_\bb__\br_\bd__\br_\be_\bq.  The
     checksum passed to the corresponding _\bk_\br_\bb__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh is avail-
     able as part of the filled-in AUTH_DAT area.

     The _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be argument specifies the filename which the ser-
     vice program should use to obtain its service key.
     _\bK_\br_\bb__\br_\be_\bc_\bv_\ba_\bu_\bt_\bh passes _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be to the _\bk_\br_\bb__\br_\bd__\br_\be_\bq function.  If


Printed 7/27/90             Kerberos                            3


KRB_SENDAUTH(3)                4.0                KRB_SENDAUTH(3)


     you set this argument to "", _\bk_\br_\bb__\br_\bd__\br_\be_\bq looks for the ser-
     vice key in the file /_\be_\bt_\bc/_\bk_\be_\br_\bb_\be_\br_\bo_\bs_\bI_\bV/_\bs_\br_\bv_\bt_\ba_\bb.

     If the client and server are performing mutual authenica-
     tion, the _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be argument should point to an allocated
     Key_schedule.  Otherwise it is ignored and may be NULL.

     The _\bv_\be_\br_\bs_\bi_\bo_\bn 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 _\bk_\br_\bb__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh.

K\bKR\bRB\bB_\b_N\bNE\bET\bT_\b_W\bWR\bRI\bIT\bTE\bE A\bAN\bND\bD K\bKR\bRB\bB_\b_N\bNE\bET\bT_\b_R\bRE\bEA\bAD\bD
     The _\bk_\br_\bb__\bn_\be_\bt__\bw_\br_\bi_\bt_\be function emulates the write(2) system
     call, but guarantees that all data specified is written to
     _\bf_\bd before returning, unless an error condition occurs.

     The _\bk_\br_\bb__\bn_\be_\bt__\br_\be_\ba_\bd function emulates the read(2) system call,
     but guarantees that the requested amount of data is read
     from _\bf_\bd before returning, unless an error condition occurs.

B\bBU\bUG\bGS\bS
     _\bk_\br_\bb__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh, _\bk_\br_\bb__\br_\be_\bc_\bv_\ba_\bu_\bt_\bh, _\bk_\br_\bb__\bn_\be_\bt__\bw_\br_\bi_\bt_\be, and _\bk_\br_\bb__\bn_\be_\bt__\br_\be_\ba_\bd
     will not work properly on sockets set to non-blocking I/O
     mode.


S\bSE\bEE\bE A\bAL\bLS\bSO\bO
     krb_mk_req(3), krb_rd_req(3), krb_get_phost(3)


A\bAU\bUT\bTH\bHO\bOR\bR
     John T. Kohl, MIT Project Athena

R\bRE\bES\bST\bTR\bRI\bIC\bCT\bTI\bIO\bON\bNS\bS
     Copyright 1988, Massachusetts Instititute of Technology.
     For copying and distribution information, please see the
     file <mit-copyright.h>.


Printed 7/27/90             Kerberos                            4