


PEKS-KEYFILE(5) PEKS 0.8.18 Programming Interface PEKS-KEYFILE(5)


NNAAMMEE
       peks-keyfile - syntax of password and keys

SSYYNNTTAAXX
     <file>     :
                | <line> '\n' <file>

     <line>     :
                | <comment>
                | <key-def>

     <comment>  : '#' any text ...

     <key-def>  : <tag> ' ' <fields> ' ' <crc>

     <tag>      : <user-tag>
                | <host-tag>

     <user-tag> : <usrspecs> ':'

     <host-tag> : <netspecs> ':'

     <usrspecs> : <user-name> '@' <netspecs> ':'
                | <user-name> '@'

     <netspecs> :
                | <netspec> '+' <netspecs>

     <netspec>  : <ipv4-addr>
                | <ipv4-addr> '/' <ipv4-mask>
                | <ipv4-first> '-' <ipv4-last>
                | <ipv4-first> '-' <ipv4-last> '/' <ipv4-mask>


     <ipv4-addr>: octett.octett.octett.octett
                | decimal-number

     <ipv4-mask>: octett.octett.octett.octett
                | leading-bits

     <fields>   : <seed>     ' '     e'A'        ' ' <encr-pwd>
                | <p-module> ' ' <prime-element> ' ' <peks-key>

DDEESSCCRRIIPPTTIIOONN
       A  key  file  is  organized line wise, comment lines start
       with a hash character ''##''.  All that is interesting in the
       syntax  desription,  above  is  the organisation of a line
       that is a <<kkeeyy--ddeeff>>_.

       The <<kkeeyy--ddeeff>> line represents an public/private key  or  a
       user  password.  It  is  always preceeded by a lookup item
       <<uusseerr--ttaagg>> or <<hhoosstt--ttaagg>>. It is used to select a  particu-
       lar  line.  By definition, the first line with a given tag
       hides all lines with the same tag, below.



PEKS CIPHER LAYER          Jan 21, 2001                         1





PEKS-KEYFILE(5) PEKS 0.8.18 Programming Interface PEKS-KEYFILE(5)


       If the <<ttaagg>> is a <<uusseerr--ttaagg>>, it  roughly  looks  like  an
       email  address.  Unless you have a user restricted to par-
       ticular host, the <<nneettssppeeccss>>  part  (host  name,  say)  is
       omitted.

       The  <<nneettssppeeccss>>  can be viewed as a generalized host name,
       here.  Viewing a host as a collapsed network,  one  writes
       the name or address followed by a netmask as
       _<_i_p_v_4_-_a_d_d_r_>_/_2_5_5_._2_5_5_._2_5_5_._2_5_5  or _<_i_p_v_4_-_a_d_d_r_>_/_3_2, where both
       representations are equivalent.  Of course,  in  the  most
       general  case,  the <<nneettssppeeccss>> part of the <<uusseerr--ttaagg>> is a
       list of networks.

       It is also possible, to formulate a range of ipv4 networks
       witin a single <<nneettssppeecc>>.  A network range

           <first-addr>-<last-addr>/<mask>

       can  be  viewed  as  an  abbreviation  for  the <<nneettssppeeccss>>
       instance

           <first-addr>/<mask>+<next-addr>/<mask>+ ... \
                          ... +<last-addr>/<mask>

       of consecutive networks  with  increasing  adresses.   For
       that  reason,  the  forst  address  within  a  must not be
       greater than the last one. The definition of  a  range  of
       netwotks  comes  most natural when a range of hostnames is
       specified like

           <first-hist-addr>-<last-host-addr>.


       If the <<ttaagg>> is a <<hhoosstt--ttaagg>>, it is usually a host name or
       an  ipv4-address, followed by a colon.  Again, in the most
       general case we have a list of networks, here.

       What follows are <fields> that are checked integral by a 4
       byte      message      digest     <<ccrrcc>>     defined     as
       PPEEKKSS__KKEEYY__LLIINNEE__CCRRCC__TTYYPPEE,  and   PPEEKKSS__KKEEYY__LLIINNEE__CCRRCC__OOFFFFSS   in
       ppeekkss--bbaasseeXXXX..hh of the program sources.

       For  a  meaning of the key fields see the file RREEAADDMMEE..PPUUBB--
       KKEEYY--AALLGGOO of the program sources, with the numeric  symbols
       p, g, and a replaced by

           <p-module>     ::= p
           <prime-element>::= g
           <peks-key>     ::= a

       for a public key, the fields are read as

           <prime-module> ::= p
           <prime-element>::= g,



PEKS CIPHER LAYER          Jan 21, 2001                         2





PEKS-KEYFILE(5) PEKS 0.8.18 Programming Interface PEKS-KEYFILE(5)


           <peks-key>     ::= g^a

       You  may  savely  edit a <<ttaagg>> with any text editor as the
       <<ccrrcc>> only checks for the integrity of the <<ffiieellddss>>,  fol-
       lowing the <<ttaagg>>.


MMAATTCCHHIINNGG TTAAGGSS
       In order to match a lookup item agains all the tags in the
       data base, a <<uusseerr--ttaagg>> lookup item is checked agains  all
       user  tags,  and  a <<hhoosstt--ttaagg>> is checked all host tags in
       the data base. The first particular match  always  applies
       disregarding all other data base entries. A user tag never
       matches a host tag, and vice versa.

       A <<uusseerr--ttaagg>> lookup item matches against a user tag in the
       data base if the <<uusseerr--nnaammee>> parts match literally and one
       of the following holds:

         For both, the lookup item and the  data  base  item  the
         <<nneettssppeeccss>> are non-empty and match, or

         the tag item in the data base has no <<nneettssppeeccss>> part.

       Matching  s  <<hhoosstt--ttaagg>>  in  the data base just reduces to
       matching <<nneettssppeeccss>>, as described, next.


MMAATTCCHHIINNGG NNEETTSSPPEECCSS
       Assume there is a network lookup item X  that  has  to  be
       matched  against all the <netspecs> tags in the data base.
       As already mentioned, the first match applies disregarding
       all  other  data  base entries. The syntax allowed for the
       lookup item X follows the generalized <<nneettssppeeccss>> syntax.

       If the lookup item X is literally equal to some <netspecs>
       entry in the data base, it matches.

       If  the  lookup item X is something else than a plain host
       name (it contains the  letter  '+',  or  '/'),  the  match
       fails.

       The lookup item X is converted to an ip address Y checking
       for a _d_e_c_i_m_a_l_-_n_u_m_b_e_r representation first, and by means of
       the  function  gethostbyname()  (see  ggeetthhoossttbbyynnaammee(3) for
       details) otherwise.

       For all <<nneettppeeccss>> tags in the data base, the  lookup  item
       ip  address  Y is checked against all <<nneettssppeecc>> parts com-
       prising the complete <<nneettppeeccss>> tag.

       If the current <<nneettssppeecc>> part is defined as a network like
       _a_d_d_r_e_s_s_/_m_a_s_k, the lookup item ip address Y matches if




PEKS CIPHER LAYER          Jan 21, 2001                         3





PEKS-KEYFILE(5) PEKS 0.8.18 Programming Interface PEKS-KEYFILE(5)


           (Y & mask) == address.

       More  general, if the current <<nneettssppeecc>> part is defined as
       a range of networks like _f_r_o_m_-_t_o_/_m_a_s_k, the lookup item  ip
       address Y matches if

           from <= (Y & mask) <= to.

       Examples:

           Y == 4.3.2.1 matches 4.3.2.1 but not 4.3.2.2
           Y == 1.2.3.4 matches 1.0.0.0/14 but not 1.0.0.0/15
           Y == 1/0 matches 1/0 but not 0/0
           Y == 1 does not match 1/0

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       HHOOMMEE   Some  function  may accept a key file name as argu-
              ment. Here, for the key file name expansion a lead-
              ing  tilde-slash  given  as  in  "~/<key-file>"  is
              interpreted as "$HOME/<key-file>".

       NNEESSSSUUSSHHOOMMEE
              This variable has the  same  meaning  as  the  _H_O_M_E
              variable,  explained  above. It has precedence over
              the former.

SSEEEE AALLSSOO
       ppeekkss__eeddiitt__ppaasssswwdd__ffiillee(3), ppeekkss--aauutthh(3),  ggeetthhoossttbbyynnaammee(3),
       ttaaggssrreessoollvvee(3), ppeekkss--sseessssiioonn(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


