peks-keyfile(5)

Usage

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

Overview

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

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.

Referred to by