BSD 4_4_Lite2 development

[unix-history] / usr / share / man / cat3 / krb_sendauth.0

KRB_SENDAUTH(3)      BSD Programmer's Manual      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  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 _\bk_\br_\bb_\b__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh
       function sends an authenticated  ticket  from  the  client
       program  to  the server program by writing the ticket to a
       network socket.  The _\bk_\br_\bb_\b__\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
       specified by the file descriptor _\bf_\bd_\b, 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_\b, _\bi_\bn_\bs_\bt_\b, 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  pro-
       gram  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  _\b<_\bk_\br_\bb_\b._\bh_\b>)
       characters in length.

       The  _\bc_\bh_\be_\bc_\bk_\bs_\bu_\bm 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
       _\bk_\br_\bb_\b__\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_\b__\bm_\bk_\b__\br_\be_\bq.

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


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_\b__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh_\b.   Set  _\bk_\br_\bb_\b__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh_\b'_\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_\b._\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.



MIT Project Athena     Kerberos Version 4.0                     2








KRB_SENDAUTH(3)      BSD Programmer's Manual      KRB_SENDAUTH(3)


       _\bK_\br_\bb_\b__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh fills  in  the  other  arguments--  _\bm_\bs_\bg_\b__\bd_\ba_\bt_\ba,
       _\bc_\br_\be_\bd,  and  _\bs_\bc_\bh_\be_\bd_\bu_\bl_\be--before  sending  the  ticket  to the
       server program.  You must,  however,  allocate  space  for
       these arguments before calling the function.

       _\bK_\br_\bb_\b__\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_\b__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh will not use the _\bk_\br_\bb_\b__\bm_\bk_\b__\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_\b__\bm_\bk_\b__\br_\be_\bq),
       and  the  _\bs_\be_\br_\bv_\bi_\bc_\be_\b, _\bi_\bn_\bs_\bt_\b, 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_\b__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh  will  not  convert the service's instance to
       canonical form using _\bk_\br_\bb_\b__\bg_\be_\bt_\b__\bp_\bh_\bo_\bs_\bt(3).

       If you want to call _\bk_\br_\bb_\b__\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_\b__\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_\b__\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_\b__\br_\bd_\b__\br_\be_\bq.

       The  _\bs_\be_\br_\bv_\bi_\bc_\be  and _\bi_\bn_\bs_\bt arguments specify the expected ser-
       vice and instance for  which  the  ticket  was  generated.
       They are also passed to _\bk_\br_\bb_\b__\br_\bd_\b__\br_\be_\bq_\b.  The _\bi_\bn_\bs_\bt argument may
       be set to "*" if the caller wishes _\bk_\br_\bb_\b__\bm_\bk_\b__\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_\b__\bm_\bk_\b__\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_\b__\br_\bd_\b__\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.



MIT Project Athena     Kerberos Version 4.0                     3








KRB_SENDAUTH(3)      BSD Programmer's Manual      KRB_SENDAUTH(3)


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

       The _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be argument specifies  the  filename  which  the
       service  program  should  use  to  obtain its service key.
       _\bK_\br_\bb_\b__\br_\be_\bc_\bv_\ba_\bu_\bt_\bh passes _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be to the  _\bk_\br_\bb_\b__\br_\bd_\b__\br_\be_\bq  function.
       If  you  set this argument to "", _\bk_\br_\bb_\b__\br_\bd_\b__\br_\be_\bq looks for the
       service key in the file _\b/_\be_\bt_\bc_\b/_\bk_\be_\br_\bb_\be_\br_\bo_\bs_\bI_\bV_\b/_\bs_\br_\bv_\bt_\ba_\bb_\b.

       If the client and server are performing mutual authentica-
       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_\b__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh_\b.


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_\b__\bn_\be_\bt_\b__\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_\b__\bn_\be_\bt_\b__\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_\b__\bs_\be_\bn_\bd_\ba_\bu_\bt_\bh_\b,     _\bk_\br_\bb_\b__\br_\be_\bc_\bv_\ba_\bu_\bt_\bh_\b,     _\bk_\br_\bb_\b__\bn_\be_\bt_\b__\bw_\br_\bi_\bt_\be_\b,     and
       _\bk_\br_\bb_\b__\bn_\be_\bt_\b__\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>.





MIT Project Athena     Kerberos Version 4.0                     4