peks-keyfile(5)

NAME

peks-keyfile - syntax of password and keys

SYNTAX

<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>     ' '      'A'        ' ' <encr-pwd>
           | <p-module> ' ' <prime-element> ' ' <peks-key>

DESCRIPTION

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 <key-def>.

The <key-def> line represents an public/private key or a user password. It is always preceeded by a lookup item <user-tag> or <host-tag>. It is used to select a particular line. By definition, the first line with a given tag hides all lines with the same tag, below.

If the <tag> is a <user-tag>, it roughly looks like an email address. Unless you have a user restricted to particular host, the <netspecs> part (host name, say) is omitted.

The <netspecs> 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
<ipv4-addr>/255.255.255.255 or <ipv4-addr>/32, where both representations are equivalent. Of course, in the most general case, the <netspecs> part of the <user-tag> is a list of networks.

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

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

can be viewed as an abbreviation for the <netspecs> 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 <tag> is a <host-tag>, 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 <crc> defined as PEKS_KEY_LINE_CRC_TYPE, and PEKS_KEY_LINE_CRC_OFFS in peks-baseXX.h of the program sources.

For a meaning of the key fields see the file README.PUB-KEY-ALGO 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-key>     ::= g^a

You may savely edit a <tag> with any text editor as the <crc> only checks for the integrity of the <fields>, following the <tag>.

MATCHING TAGS

In order to match a lookup item agains all the tags in the data base, a <user-tag> lookup item is checked agains all user tags, and a <host-tag> 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 <user-tag> lookup item matches against a user tag in the data base if the <user-name> parts match literally and one of the following holds:

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

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

Matching s <host-tag> in the data base just reduces to matching <netspecs>, as described, next.

MATCHING NETSPECS

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 <netspecs> 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 decimal-number representation first, and by means of the function gethostbyname() (see gethostbyname(3) for details) otherwise.

For all <netpecs> tags in the data base, the lookup item ip address Y is checked against all <netspec> parts comprising the complete <netpecs> tag.

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

(Y & mask) == address.

More general, if the current <netspec> part is defined as a range of networks like from-to/mask, 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

ENVIRONMENT VARIABLES

HOME: Some function may accept a key file name as argument. Here, for the key file name expansion a leading tilde-slash given as in "~/<key-file>" is interpreted as "$HOME/<key-file>".

NESSUSHOME: This variable has the same meaning as the HOME variable, explained above. It has precedence over the former.

AUTHOR

The peks package where these functions belong to was written by Jordan Hrycaj <[email protected]>, originally to support the nessus security scanner.