


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


NNAAMMEE
       server_negotiate_session_key,
       client_negotiate_session_key  - public key encryption tun-
       nel negotiation

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

       iinntt sseerrvveerr__nneeggoottiiaattee__sseessssiioonn__kkeeyy
              ((ppeekkss__kkeeyy **_p_r_i_v_a_t_e___k_e_y,, iinntt _s_o_c_k_e_t,,
                ccoonnsstt cchhaarr **_c_l_i_e_n_t___n_a_m_e,, ppeekkss__kkeeyy **_d_h___g_r_o_u_p));;

       iinntt cclliieenntt__nneeggoottiiaattee__sseessssiioonn__kkeeyy
              ((ccoonnsstt cchhaarr **_c_i_p_h_e_r___t_y_p_e,, iinntt _s_o_c_k_e_t,,
               ccoonnsstt cchhaarr **_s_e_r_v_e_r___n_a_m_e,, ccoonnsstt cchhaarr **_k_e_y___f_i_l_e));;

       eexxtteerrnn iinntt ppeekkss__rreeccvv__ttiimmeeoouutt;;

DDEESSCCRRIIPPTTIIOONN
       SSeerrvveerr__nneeggoottiiaattee__sseessssiioonn__kkeeyy (()) starts an encrypted client
       session  on  the  server. After a successful initalization
       all io data passed through the iostream transparent socket
       layer (see iioossttrreeaamm(3) for details) will be encrypted.

       The  first  argument  _p_r_i_v_a_t_e___k_e_y must be non-NULL.  It is
       used to authenticate the server while setting up the  ses-
       sion.

       The  second  argument  _s_o_c_k_e_t  is an open TCP socket.  The
       other arguments are used to find a private key  to  derive
       the public key from, needed to negotiate the session keys.

       If the last argument _d_h___g_r_o_u_p is non-NULL, its prime  mod-
       ule and generator is used for the Diffie Hellman key nego-
       tiation.  Otherwise the module  and  generator  are  taken
       from the _p_r_i_v_a_t_e___k_e_y.

       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(()).

       Note:

           A  client  that  connects  to the server for the first
           time will store the public key  from  the  server  and
           tell the server to terminate key negotiation. So -1 is
           returned on the server and the global  variable  _e_r_r_n_o
           will  be  set  the  as  the  error code for the symbol
           _S_R_V___C_L_I_E_N_T___K_N_O_C_K_I_N_G (see also ppeekkss--eerrrrnnuumm(3)).

       Example:




PEKS CIPHER LAYER          Jan 21, 2001                         1





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


         #include <sys/socket.h>
         #include <netinet/in.h>
         #include <arpa/inet.h>
         #include <peks.h>
         #include <messages.h>

         /* ERROR () and EXIT () are macros with
            the obvious functionality */

         for (;;) {
            int n = server_negotiate_session_key
              (key,                           /* default key */
               socket,                        /* open socket */
               inet_ntoa (address->sin_addr), /* client addr  */
               "/etc/peks/private.keys") ;    /* key file */

            if (n >= 0)                       /* success */
              break;

            if (errno != errnum (SRV_CLIENT_KNOCKING)) {
              ERROR ("Cannot negotiate keys: %s - aborting",
                     peks_strerr (errno)) ;
              EXIT (1);
            }
         } /* end for (;;) */

       CClliinneett__nneeggoottiiaattee__sseessssiioonn__kkeeyy (()) starts an  encrypted  ses-
       sion on the client. The function starts waiting for a peks
       server to negotiate session keys. For  communication,  the
       open socket passed as second argument _s_o_c_k_e_t is used.

       The    argument   _c_i_p_h_e_r___t_y_p_e   is   a   string   "<block-
       cipher>/<hash-type>" composed of two text fields separated
       by  a slash.  For the values that can be used here consult
       the file cciipphheerr..hh from the sorce code. Currently, the fol-
       lowing block ciphers are available

           blowfish    - 16 byte key length, 8 byte block length
           blowfish160 - 16 byte key length, 16 byte block length
           twofish     - 16 byte key length, 16 byte block length
           3des        - 16 byte key length (hashed to 24 bytes),
                         8 byte block length

       and the hash types

           ripem160    - 20 byte result
           sha1        - 20 byte result
           md5         - 20 byte result

       Thanks  to the gnupg people where I got the sources, from.

       The other two the arguments _s_e_r_v_e_r___n_a_m_e and  _k_e_y___f_i_l_e  are
       used  to  check the public key from the server against the
       list of servers, already known.



PEKS CIPHER LAYER          Jan 21, 2001                         2





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


       If both, the argument _k_e_y___f_i_l_e is non-NULL and  the  argu-
       ment _s_e_r_v_e_r___n_a_m_e is non-NULL, the server key just received
       is checked as follows:

           If there is no file with name  _k_e_y___f_i_l_e,  it  is  just
           created.

           An  existing key file file must be privately owned and
           must neither be world nor group read/writable.

           If the file with name _k_e_y___f_i_l_e exists, it is  searched
           for  a  line  tag   matching the argument _s_e_r_v_e_r___n_a_m_e.
           Host names in the key file can be used as well  as  ip
           addesses.    If  the argument _s_e_r_v_e_r___n_a_m_e matches line
           tag, the corresponding key fields are checked  against
           the public key just received from the server.

           If  the  public  key  received does not match the ones
           found in the file  _k_e_y___f_i_l_e,  an  error  value  -1  is
           returned and no session is opened.

           If there is no public key from this server in the file
           _k_e_y___f_i_l_e, a  line  with  the  public  server  keys  is
           appended  to  the  file  and  an  error  value  -1  is
           returned.  No session will be opened. The global error
           varaiable   _e_r_r_n_o  will  be  set  to  the error symbol
           _S_T_O_R_E_D___S_E_R_V_E_R___K_E_Y (see ppeekkss__ssttddeerrrr(3) for details).

           Otherwise, an encrypted session with the  server  will
           have  been  opened  and  pushed  (see  iioo__ppuusshh(3)  for
           details) upon the transparent socket layer.

       Example:

         #include <sys/socket.h>
         #include <netinet/in.h>
         #include <arpa/inet.h>
         #include <peks.h>
         #include <messages.h>

         /* ERROR () and EXIT () are macros with
            the obvious functionality */

         for (;;) {
            int n = client_negotiate_session_key
              ("blowfish160/sha1",            /* encr type */
               socket,                        /* open socket */
               inet_ntoa (address->sin_addr), /* server addr */
               "~/.server.keys") ;            /* key file */

            if (n >= 0)                       /* success */
              break;

            if (errno != errnum (STORED_SERVER_KEY)) {



PEKS CIPHER LAYER          Jan 21, 2001                         3





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


              ERROR ("Cannot negotiate keys: %s - aborting",
                     peks_strerr (errno)) ;
              EXIT (1);
            }
         } /* end for (;;) */

RREETTUURRNN VVAALLUUEE
       SSeerrvveerr__nneeggoottiiaattee__sseessssiioonn__kkeeyy  (())  returns  0,  on  success
       while  an encrypted session with the client will have been
       opened and pushed (see iioo__ppuusshh(3) for  details)  upon  the
       transparent  socket  layer. On error, -1 is returned while
       the global variable _e_r_r_n_o will be set.

       CClliinneett__nneeggoottiiaattee__sseessssiioonn__kkeeyy  (())  returns  0,  on  success
       while  an encrypted session with the server will have been
       opened and pushed (see iioo__ppuusshh(3) for  details)  upon  the
       transparent  socket  layer. On error, -1 is returned while
       the global variable _e_r_r_n_o will be set.

EERRRROORR CCOODDEESS
       Some error codes besides the eerrrrnnoo(3) interface are  used,
       here.  They  are  referred  to as error symbols (see ppeekkss--
       eerrrrnnuumm(3) for details):

         SRV_MAGIC_FAILED    Server could not read magic string
         SRV_WRONG_MAGIC     Client sent incompatible magic string
         SRV_CLIENT_KNOCKING Client was knocking at the door, only
         SRV_CLIENT_RESPERR  Initial client response was garbage

         CANT_EXPAND_FNAME   Cannot expand file name ($HOME missing?)
         SERVER_SPOOF_ALERT  Spoof alert: Server key has changed
         STORED_SERVER_KEY   Host key for that server has been saved

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

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

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


