


PEKS-KEYS(3)    PEKS 0.8.13 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__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));;

       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 argu-
       ment and prints all the key tags from that file. Each  tag
       is printad on a separate line followed by some comment.

       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.




PEKS CIPHER LAYER          Jul 10, 2000                         1





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


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



PEKS CIPHER LAYER          Jul 10, 2000                         2





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


       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.

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
       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__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_)_.

       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



PEKS CIPHER LAYER          Jul 10, 2000                         3





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


       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.

       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),




PEKS CIPHER LAYER          Jul 10, 2000                         4





PEKS-KEYS(3)    PEKS 0.8.13 Programming Interface    PEKS-KEYS(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          Jul 10, 2000                         5


