


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


NNAAMMEE
       peks_list_keyfile, peks_private_key, new_peks_key,
       peks_save_private_key, peks_private_access,
       peks_delete_userkey - key and file manipulation functions

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

       ppeekkss__kkeeyy **nneeww__ppeekkss__kkeeyy ((uunnssiiggnneedd _s_i_z_e));;

       uunnssiiggnneedd ppeekkss__kkeeyylleenn ((ccoonnsstt ppeekkss__kkeeyy **_k_e_y));;

       iinntt ppeekkss__lliisstt__kkeeyyffiillee
              ((vvooiidd ((**_p_r_i_n_t)) ((ccoonnsstt cchhaarr**)),, ccoonnsstt cchhaarr **_k_e_y___f_i_l_e));;

       ppeekkss__kkeeyy **ppeekkss__pprriivvaattee__kkeeyy
              ((ccoonnsstt cchhaarr **_u_s_r___a_t___h_o_s_t,,
               ccoonnsstt cchhaarr **_k_e_y___f_i_l_e,, cchhaarr **((**_g_e_t___p_w_d))((iinntt))_,
               uunnssiiggnneedd _k_e_y_l_e_n));;

       iinntt ppeekkss__ssaavvee__pprriivvaattee__kkeeyy
               ((ccoonnsstt cchhaarr **_u_s_r___a_t___h_o_s_t,, ppeekkss__kkeeyy **_k_e_y,,
                ccoonnsstt cchhaarr **_k_e_y___f_i_l_e,, cchhaarr **((**_g_e_t___p_w_d))((iinntt))));;

       iinntt ppeekkss__ssaavvee__ppuubblliicc__kkeeyy
               ((ccoonnsstt cchhaarr **_u_s_r___a_t___h_o_s_t,, ppeekkss__kkeeyy **_k_e_y,,
                ccoonnsstt cchhaarr **_k_e_y___f_i_l_e));;

       iinntt ppeekkss__ddeelleettee__uusseerrkkeeyy
               ((ccoonnsstt cchhaarr **_u_s_r___a_t___h_o_s_t,, ccoonnsstt cchhaarr **_k_e_y___f_i_l_e,,
                cchhaarr **((**_g_e_t___p_w_d))((iinntt));;

       iinntt ppeekkss__ddeelleettee__hhoossttkkeeyy
               ((ccoonnsstt cchhaarr **_h_o_s_t_n_a_m_e,, ccoonnsstt cchhaarr **_k_e_y___f_i_l_e,,
                cchhaarr **((**_g_e_t___p_w_d))((iinntt));;

       iinntt ppeekkss__pprriivvaattee__aacccceessss
               ((ccoonnsstt cchhaarr **_f_i_l_e_n_a_m_e,, iinntt _s_t_r_i_c_t_l_y));;

       uunnssiiggnneedd lloonngg ppeekkss__aaddmmiinn__eeqquuiivv
               ((uunnssiiggnneedd_u_i_d,, uunnssiiggnneedd_g_i_d));;

       vvooiidd ppeekkss__sseett__kkeeeepp__aalliivvee__nnoottiiccee
               ((vvooiidd ((**_p_r_i_n_t___s_t_r_i_n_g))((ccoonnsstt cchhaarr**))));;


DDEESSCCRRIIPPTTIIOONN
       NNeeww__ppeekkss__kkeeyy(())  creates a new private key of at least _s_i_z_e
       bits.

       ppeekkss__kkeeyylleenn(()) returnes the bit  length  of  the  peks  key
       given as argument.

       PPeekkss__lliisstt__kkeeyyffiillee(())  reads  the  file  _k_e_y___f_i_l_e  given  as



PEKS CIPHER LAYER          Jan 21, 2001                         1





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


       argument and prints all the key tags from that file.  Each
       tag  is  printad  on a separate line followed by some com-
       ment.

       If the first function argument _p_r_i_n_t is NULL, the data are
       printed  to  the  stdout,  otherwise the argument function
       _p_r_i_n_t is called once for each line to be printed.

       ppeekkss__pprriivvaattee__kkeeyy(()) reads a user key from the file given as
       argument  and  returns  a  pointer  to  it as the function
       return value.  Assuming the argument _u_s_r___a_t___h_o_s_t is  given
       as  "usr@host"  or  "usr",   the  function looks for a key
       tagged "usr@host:" first (in case of "usr@host",)  and  if
       that failes for a key tagged "usr@", next.

       If there was a key found, the function checks whether that
       key has at least _k_e_y_l_e_n (given as last argument) bits.  If
       it has less bits, an error is returned.

       If  the  key  needs  a  pass phrase, the function given as
       argument _g_e_t___p_w_d is consulted  and  the  return  value  is
       evaluated (see the paragraph PASS PHRASE, below.)

       Otherwise the key is activted and returned.

       If  there  was no key and/or no file, a new private key of
       at least _k_e_y_l_e_n bits will be generated and stored  in  the
       file  _k_e_y___f_i_l_e given as second argument. A pointer to that
       key is returned as function value.

       The  tag  for  the  key  just  created   is   the   string
       _u_s_r___a_t___h_o_s_t.

       Notice:

           In the key data base, there is no other way to distin-
           guish a private key from a public key else but by  the
           tag.  Be aware that this tag may habe been edited.  By
           convention, a user key (the tag  contains  the  letter
           '@') is private and a host key is public.

       ppeekkss__ssaavvee__pprriivvaattee__kkeeyy(())  saves  the  private  key given as
       second argument _k_e_y tagged according to the first argument
       _u_s_r___a_t___f_o_s_t  in  the  file _k_e_y___f_i_l_e. If a key instance for
       the tag  applied  is  found,  already  this  key  will  be
       replaced in the _k_e_y___f_i_l_e.

       If the argument _g_e_t___p_w_d is non NULL, the function given as
       argument _g_e_t___p_w_d is consulted  and  the  return  value  is
       evaluated (see the paragraph PASS PHRASE, below.)

       ppeekkss__ssaavvee__ppuubblliicc__kkeeyy(())  saves  the public key derived from
       the second argument _k_e_y onto the key file  _k_e_y___f_i_l_e  given
       as   last   argument.    The  first  argument  _u_s_r___a_t___f_o_s_t



PEKS CIPHER LAYER          Jan 21, 2001                         2





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


       corresponds to a key tag used for key lookup.  If a public
       key  with a corresponding tag is not found, the public key
       with the tag is added to the file.  Otherwise, if the  key
       tags  match  but  the  public  keys  differ,  an  error is
       detected.

       ppeekkss__ddeelleettee__uusseerrkkeeyy(()) selects a key from the file given as
       argument  the  same  way as described for ppeekkss__pprriivvaattee__kkeeyy
       (()), above.  Once a key  tag  matches,  the  whole  key  is
       deleted from the file.

       ppeekkss__ddeelleettee__hhoossttkkeeyy(())   works   similar  as  the  function
       ppeekkss__ddeelleettee__uusseerrkkeeyy(()) but for host keys.

       If the key needs a pass  phrase,  the  function  given  as
       argument  _g_e_t___p_w_d  is  consulted  and  the return value is
       evaluated (see the paragraph PASS PHRASE, below.)

       The function ppeekkss__pprriivvaattee__aacccceessss(()) is a cute little  func-
       tion that checks the access rights of the file _f_i_l_e_n_a_m_e as
       used for private data such as keys and the like.  With the
       second  parameter _s_t_r_i_c_t_l_y, the function is informed about
       the level of privacy.

       The file _f_i_l_e_n_a_m_e must be a proper file and  cannot  be  a
       symlink  and  cannot  have extra hardlinks.  If the second
       argument _s_t_r_i_c_t_l_y is zero, the file _f_i_l_e_n_a_m_e may be  group
       and  world readable but not writable.  If _s_t_r_i_c_t_l_y is non-
       zero but smaller than 2, the file must not even be  world-
       but  may  be group readable.  If _s_t_r_i_c_t_l_y is 2 or greater,
       no world or group read or write permission is allowed.

       The function ppeekkss__aaddmmiinn__eeqquuiivv(()) installs the maximal  user
       and  group  id  for  any admin account to check, for. When
       checking files with ppeekkss__pprriivvaattee__aacccceessss(()), all  path  seg-
       ments  with a user and group      id smaller or equal than
       these values are considerd secure and tamperproof.

       Passing the second argument _g_i_d as -1, the path  check  is
       disabled  when the first argument _u_i_d is non-zero. In this
       case only file checking applies without owner  check  (!).
       Otherwise,  when  the  second  argument  _g_i_d is -1 and the
       first argument _u_i_d is 0 and patch checking is  turned  on,
       again.

RREETTUURRNN VVAALLUUEE
       NNeeww__ppeekkss__kkeeyy(())  returns  a  pointer to a new key, and NULL
       upon error while the global variable errno will be set  to
       indicate some explanation. ppeekkss__kkeeyylleenn(()) returns number of
       bits used for that key, and 0 if the argument was the NULL
       pointer.

       PPeekkss__lliisstt__kkeeyyffiillee(()) and ppeekkss__ddeelleettee__uusseerrkkeeyy(()) return 0, on
       success and -1, otherwise. In the latter  case  while  the



PEKS CIPHER LAYER          Jan 21, 2001                         3





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


       global  variable  eerrrrnnoo will be set to indicate some error
       explanation  (see   ppeekkss--eerrrrnnuumm_(_3_)   _a_n_d    eerrrrnnoo_(_3_)   _f_o_r
       _d_e_t_a_i_l_s_)_.

       ppeekkss__pprriivvaattee__kkeeyy(()) returns a pointer to a key structure of
       type ppeekkss__kkeeyy on success,  an  NULL  otherwise  while  the
       global variable errno will be set.

       ppeekkss__ssaavvee__ppuubblliicc__kkeeyy(())  returns  0, if there was no key in
       the data base and a new key had been added.   If  the  key
       existed,  already in the data base and was the same as the
       one to be added, 0 is returned otherwise if tags match but
       not the keys -1 is returned.

       PPeekkss__pprriivvaattee__aacccceessss(())  returns 0 on success.  In this case
       the file exists and meets the privacy settings  as  speci-
       fied.   Otherwise  -1 is returned. In that case the global
       variable eerrrrnnoo will be set to indicate some error explana-
       tion (see ppeekkss--eerrrrnnuumm_(_3_) _a_n_d  eerrrrnnoo_(_3_) _f_o_r _d_e_t_a_i_l_s_)_.

       If  the second argument _g_i_d of ppeekkss__aaddmmiinn__eeqquuiivv__uuiidd is not
       -1, it returns the values that were previously  effective.
       The  values  are  retured as a pair of 16 bit values as in
       (uid<<16)|(gid&0xffff).

       If the second argument _g_i_d of ppeekkss__aaddmmiinn__eeqquuiivv__uuiidd is  -1,
       the  previous  state of the patc ckeck mode is returned: 0
       if path check were enabled, and -1, otherwise.

       ppeekkss__sseett__kkeeeepp__aalliivvee__nnoottiiccee lets you  define  a  call  back
       function  _p_r_i_n_t___s_t_r_i_n_g  printing  some dots while a key is
       generated. By default, this funtion looks similar to  ppuuttss
       function printing to the _s_t_d_o_u_t (see ppuuttss(3) for details.)
       Passing a NULL argument  to  _p_r_i_n_t___s_t_r_i_n_g  resets  to  the
       default.

PPAASSSS PPHHRRAASSEE
       The  pass  phrase for a private key is always read by some
       call back function. In this  documentation,  the  function
       argument pointer _g_e_t___p_w_d refers to a pass phrase returning
       function.

       The pass phrase function will be called as  ggeett__ppwwdd((00))  if
       the private key is to be activated, only and as ggeett__ppwwdd((11))
       if the key is to be ireencoded with a new pass phrase.  If
       the  function  is  called  from ppeekkss__pprriivvaattee__kkeeyy(()) after a
       newly generated key, it is called as ggeett__ppwwdd((22)).

       This function ggeett__ppwwdd(()) returns a character  string  which
       comprises  the  pass  phrase.  The value NULL or the empty
       string "" is returned if there  is  no  such  pass  phrase
       which  has the same effect as if the argument _g_e_t___p_w_d were
       passed as NULL pointer from the beginning.




PEKS CIPHER LAYER          Jan 21, 2001                         4





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


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

       An error condition can be returned as (char*)-1 which will
       be handled, accordingly. Such a pass phrase function could
       look like

         #include <pwd.h>
         #include <string.h>

         const char*
         get_pwd
           (int mode)
         {
            char *s, *t ;
            if (mode == 0) /* read private key */
              return getpass ("Pass phrase: ");

            /* change pass phrase for the private key */
            if ((s = getpass ("New pass phrase: ")) == 0)
              return (char*)-1;

            s = strdup (s);
            if ((t = getpass ("Repeat         : ")) == 0) {
              free (s);
              return (char*)-1;
            }
            if (strcmp (s, t) != 0)
              t = 0 ;

            free (s);
            if (t == 0)
              return (char*)-1;
            return t ;
          }


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

SSEEEE AALLSSOO
       ggeetthhoossttbbyynnaammee(3),     ppeekkss--kkeeyyffiillee(5),     ttaaggssrreessoollvvee(3),
       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                         5


