


PEKS-AUTH(3)    PEKS 0.8.18 Programming Interface    PEKS-AUTH(3)


NNAAMMEE
       peks_server_auth_pubkey,
       peks_server_auth_accept, peks_server_auth_reject,
       peks_client_authenticate - public key authentication

SSYYNNOOPPSSIISS
       ##iinncclluuddee <<ppeekkss..hh>>

       cchhaarr **ppeekkss__sseerrvveerr__aauutthh__ppuubbkkeeyy
              ((iinntt _s_o_c_k_e_t,, ccoonnsstt cchhaarr **_c_l_i_e_n_t___h_o_s_t,,
               ppeekkss__kkeeyy **_p_w_d___k_e_y,, uunnssiiggnneedd _k_e_y_l_e_n,,
               uunnssiiggnneedd _m_a_x___f_a_i_l,, ccoonnsstt cchhaarr **_k_e_y___f_i_l_e));;

       vvooiidd ppeekkss__sseerrvveerr__aauutthh__aacccceepptt ((ppeekkss__kkeeyy **_p_w_d___k_e_y));;

       vvooiidd ppeekkss__sseerrvveerr__aauutthh__rreejjeecctt ((ppeekkss__kkeeyy **_p_w_d___k_e_y,, cchhaarr **_w_h_y));;

       iinntt ppeekkss__cclliieenntt__aauutthheennttiiccaattee
              ((uunnssiiggnneedd _d_i_g_s_t___m_e_t_h,, iinntt _s_o_c_k_e_t,, ccoonnsstt cchhaarr **_u_s_e_r,,
               ppeekkss__kkeeyy **_k_e_y,, cchhaarr **((**_g_e_t___p_w_d))((iinntt))));;

       eexxtteerrnn iinntt ppeekkss__rreeccvv__ppaasssswwdd__ttiimmeeoouutt ;;
       eexxtteerrnn iinntt ppeekkss__rreeccvv__ttiimmeeoouutt;;

DDEESSCCRRIIPPTTIIOONN
       PPeekkss__sseerrvveerr__aauutthh__ppuubbkkeeyy(())  lets a user client authenticate
       on the server by having her signed a  challenge.   If  the
       user  client  is  unknown, yet she gets a chance sending a
       password digest.  If the password is ok, the passowd  line
       is  replaced  by the public key sent by the client serving
       fur further logins.

       If the client is rejected, she will  be  informed  immedi-
       ately  and  the  function  returnes  NULL.  Otherwise, the
       function returns the user name but does not have sent  the
       final acceptance notice to the client, yet.

       The arguments needed for ppeekkss__sseerrvveerr__aauutthh__ppuubbkkeeyy(()) are:

       _S_o_c_k_e_t is  the  socket id to read from, this function uses
              iioo__sseenndd(()) and  iioo__rreeccvv(())  rather  than  sseenndd(())  and
              rreeccvv(()), see iioossttrreeaamm(3).

       _C_l_i_e_n_t_h_o_s_t
              is  the  name of the IP address of the client host,
              used for key  or  password  lookup,  see  ppeekkss--kkeeyy--
              ffiillee(5).

       _P_w_d___k_e_y
              is  the  private  key,  the password is (assymetri-
              cally) encrypted with. The structure is  also  used
              to hold the current protocol state.

       _K_e_y_l_e_n is  the  minimal bit length of a user's public key.



PEKS CIPHER LAYER          Jan 21, 2001                         1





PEKS-AUTH(3)    PEKS 0.8.18 Programming Interface    PEKS-AUTH(3)


              Keys received with less bits than this  length  are
              rejected.

       _M_a_x___f_a_i_l
              is  the maximal number of failures using a password
              when there is no public  key,  available.  If  that
              limit is exeeded, the password line will be deleted
              automatically from the password data base.

       _K_e_y___f_i_l_e
              is the name of the file that coontains the password
              and  user  key  data  base. If the file name begins
              with a tilde as in  "~/<filename>",  the  tilde  is
              replaced  by  the  actual  value of the environment
              variable HHOOMMEE.

       The function ppeekkss__sseerrvveerr__aauutthh__ppuubbkkeeyy(()) must always be fol-
       lowed     by    either    ppeekkss__sseerrvveerr__aauutthh__aacccceepptt(()),    or
       ppeekkss__sseerrvveerr__aauutthh__rreejjeecctt(()) if  the  return  value  was  non
       NULL. Otherwise, ppeekkss__sseerrvveerr__aauutthh__rreejjeecctt(()) has been called
       already, implicitely but there is no harm  to  call  these
       functions, anyway.

       Example:

         #include "peks.h"

         if ((user = peks_server_auth_pubkey
              (socket,              /* socket number */
               from,                /* client host name */
               key,                 /* server prv key */
               peks_keylen,         /* client min key len */
               MAXPWDFAIL,          /* max failures allowed */
               usrkeys_file)) == 0) /* client key data base */
            return 0;

         /* do some more checks for that user */
         ...

         if (user == 0) {
            peks_server_auth_reject (key, "user not configured") ;
            return 0;
         }

         peks_server_auth_accept (key) ;
         return user;

       PPeekkss__sseerrvveerr__aauutthh__aacccceepptt(()) sends a final acceptance message
       to the authenticated client after a successful authentica-
       tion  accomplished by ppeekkss__sseerrvveerr__aauutthh__ppuubbkkeeyy(()). It cleans
       up the internal state information in the _p_w_d___k_e_y  argument
       structure.

       PPeekkss__sseerrvveerr__aauutthh__rreejjeecctt(())  sends a final rejection message



PEKS CIPHER LAYER          Jan 21, 2001                         2





PEKS-AUTH(3)    PEKS 0.8.18 Programming Interface    PEKS-AUTH(3)


       to the client and cleans up the state information  in  the
       _p_w_d___k_e_y argument structure.  If the second argument _w_h_y is
       non-NULL, this string is sent with the rejection notice to
       the  client  as  an  explanation why the server decided to
       reject the client (currently,  this  explanation  is  dis-
       carded on the authentication client.)

       PPeekkss__cclliieenntt__aauutthheennttiiccaattee(())  lets  a client authenticate on
       the server by having her signed a challenge granted by the
       server.

       The   client   must   choose  some  authentication  method
       _d_i_g_s_t___m_e_t_h (currently 1 or  3.)  This  decides  upon  some
       mathematical  method  to sign a key, either one is similar
       to the other (see README.PUB-KEY-ALGO in the  source  dis-
       tribution for details.)

       The other arguments, PPeekkss__cclliieenntt__aauutthheennttiiccaattee(()) needs are:

       _S_o_c_k_e_t is the socket id to read from, this  function  uses
              iioo__sseenndd(())  and  iioo__rreeccvv(())  rather  than  sseenndd(()) and
              rreeccvv(()), see iioossttrreeaamm(3).

       _U_s_e_r   is the name the user who wants to be authenticated.

       _K_e_y    is  the  private  key  needed  in order to sign the
              server challenge.

       _G_e_t___p_w_d
              is a call back function pointer. If it is non-NULL,
              the  function  called with argument 0 as ggeett__ppwwdd((00))
              is expected to return  a  password  (or  NULL  when
              there  is  none,  and (char*)-1 upon error) used to
              authenticate the user after the public  key  method
              failed.

       If a password is returned, the password will be cleared to
       0 after usage. So the function ggeett__ppwwdd(()) must never return
       static memory.

       By  setting  the global variable _p_e_k_s___r_e_c_v___t_i_m_e_o_u_t to some
       positive value _n, a timeout is imposed on waiting  for  an
       answer while the handshake is active. This is done by tem-
       porarily  changing  the  receive   timeout   value   using
       iioo__rreeccvv__ttmmoo(()),    a    similar    procedure   applies   to
       _p_e_k_s___r_e_c_v___p_a_s_s_w_d___t_i_m_e_o_u_t, which is the waiting time when a
       passwd  is  asked, for.  The default values are 20 seconds
       for _p_e_k_s___r_e_c_v___t_i_m_e_o_u_t, and 90 seconds for
        _p_e_k_s___r_e_c_v___p_a_s_s_w_d___t_i_m_e_o_u_t.

RREETTUURRNN VVAALLUUEE
       PPeekkss__sseerrvveerr__aauutthh__ppuubbkkeeyy(()) returns the login  name  of  the
       client  user  when  the authentication was successful, and
       NULL otherwise. In the latter case  you  could  check  the



PEKS CIPHER LAYER          Jan 21, 2001                         3





PEKS-AUTH(3)    PEKS 0.8.18 Programming Interface    PEKS-AUTH(3)


       global  variable  eerrrrnnoo  to  get  an explanation where the
       authentication failed, see also ppeekkss__ssttrreerrrr(3).

       PPeekkss__cclliieenntt__aauutthheennttiiccaattee  returns  0  if  the  server  has
       accepted  the user, and 1 if the server rejected the user.
       Upon error, -1 is returned while  the  variable  errno  is
       set,  accordingly. In that case you could check the global
       variable eerrrrnnoo to get an explanation why  the  authentica-
       tion failed, see also ppeekkss--eerrrrnnuumm(3).

CCAAVVEEAATT
       Any  non-NULL  return value will have been allocated using
       the XXMMAALLLLOOCC(()) macro (which is usually  a  replacement  for
       ccaalllloocc(3)) as configured in the ccoommmmoonn--ssttuuffff..hh header file
       upon compilation of the package.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       HHOOMMEE   Used for the key file name expansion when there  is
              a leading tilde-slash as in "~/<filename>".

SSEEEE AALLSSOO
       ssoocckkeett(3),     ccaalllloocc(3),     iioo__ppuusshh(3),     iioossttrreeaamm(3),
       iioo__rreeccvv__ttmmoo(3), eerrrrnnoo(3), ppeekkss--eerrrrnnuumm(3), ppeekkss--kkeeyyffiillee(5),

AAUUTTHHOORR
       The ppeekkss package where these functions belong to was writ-
       ten by Jordan Hrycaj <jordan@teddy-net.com>, originally to
       support the nneessssuuss security scanner.





























PEKS CIPHER LAYER          Jan 21, 2001                         4


