% $RCSfile: km.tex,v $
%
% $Revision: 1.1 $
% $Date: 1995/07/28 21:18:01 $
%

\protspec{KM}{KM (An Encryption Key Manager)}
\index{km}
\label{KM}

\input cryptDist

\topic{SPECIFICATION}

\noindent
KM provides a key that matches a participant list. 

\topic{SYNOPSIS}

KM maps addresses to keys. Both keys and addresses are 
uninterpreted byte strings to KM. KM reads a key file at start 
up.  The first line of the key file contains the length of the 
addresses in bytes, the length of the keys in bytes and the size 
to pass when creating the key map. The remaining lines of the 
key file contain address key pairs.  

When a protocol such as CRYPT needs to look up a key, it opens 
a session to KM. The entire participant list is converted into a 
byte string and used to lookup a session in the key map. Note if 
you wish to associate a key with a single participant in a 
participant list you must create a new participant list with 
that participant as its only member. (Not an easy thing to do 
with the current participant structure.) The control operation 
KM\_RESOLVE is used to lookup the actual keys. The control 
operation KM\_SET is used to change the value of a key. The 
control operation KM\_INVALIDATE is used to invalidate a key. 
The state of the KM session can be determined by calling the 
control operations KM\_ISEMPTY, KM\_ISVALID, 
KM\_ISINVALID. If the state is empty no key value has ever 
been set for this address. If the state is valid there is a valid 
key for this address if the state is invalid an invalidate 
operation has been performed on this session. If a higher level 
protocol is no longer interested in a specific key it should 
perform a close operation on the KM session.  No messages are 
pushed or popped to KM.

The keys file name is formed by concatenating the string
``keys'' with the instance name of the protocol (which may be 
null).

\noindent 
\topic{REALM}

KM is in the ASYNC realm.

\topic{PARTICIPANTS}

KM accepts participants in order to do a table lookup to find 
the key. The entire participant list is converted into a byte 
string which is then used to lookup the key. 

\topic{CONTROL OPERATIONS}
KM\_RESOLVE returns a copy of the key stored in that session. 
This key is the key which is associated with the participant 
list passed at open time. KM\_RESOLVE can fail if no key has
been set or that key has been invalidated.

KM\_SET sets the key for that session to the value passed.

KM\_INVALIDATE marks the key as invalid and removes the KM 
session from the map. The session is not destroyed until all 
users of that session have closed it. 

KM\_ISEMPTY succeeds if no key for this session has been 
defined.  

KM\_ISVALID succeeds if there is a valid key for this session. 

KM\_ISINVALID succeeds if a KM\_INVALIDATE operation has 
been performed in this session. 

\topic{CONFIGURATION}

\noindent KM is configured with cryptographic protocols such as CRYPT. 
It can be configured as a terminal node of the graph, or with two
lower protocols.  The first should be a transport protocol capable
of key retrieval (such as DHKX \ref{DHKX}), and the second should
be the key manager used by that protocol.

\topic{OPTIONS}

\noindent There are three options: {\it kmparams}, {\it kmkeyfile}, and {\it
kmkey}.  The first can be used to specify the same information as the
first line of a keys file (see below); if this option is used without
a name following, no keys file will be used by the protocol.  The
second option is the name of the keys file.  The third option can
specify key information to be merged with the information in the keys
file (if any).

\topic{CRYPTOGRAPHIC SHORTCOMINGS}

\noindent The operating system file protections must be used to protect 
the keys file from unauthorized snooping.

\topic{EXAMPLE KEY FILES}

\noindent Here are four examples of key files.

The first example shows a key file which maps 4 byte IP 
addresses to 8 byte DES keys. The 57 is the number passed to 
mapCreate as the size of the key map. The IP address is 
followed by a DES key, of 16 hex digits. Hex letters may be
in upper or lower case. A trailing comment is optional, but it
helps to keep track of the machine name. This keying method is 
appropriate if the CRYPT module is configured above IP.
Note that for historical reasons the id field begins with 
0x while the key field does not.

\begin{verbatim}
---------------------------------
4 8 57
0xc00c4582 0807060504030201  
0xc00c4587 080706050403d213
0xc00c456e 0103040506070802
0xc00c4589 abbadabbad0add15   Berlioz  192.12.69.137
0xc00c4518 141421356abcdefa   Britten  192.12.69.24
0xc00c4554 2718281828459045   Cottonwood 192.12.69.84
0xc00c4574 3141592653589793   Leibniz  192.12.69.116
0xc00c4562 98cba765fed43210   Tchaikovsky 192.12.69.98
0xc00c4536 010304050ad53812
0xc00c4563 7766554433221100
0xc00c4561 0103040706070a02
---------------------------------
\end{verbatim}

The second example shows keying based on Ethernet address, 
which is 6 bytes long. This keying is appropriate when the 
CRYPT module is placed above ETH.
\begin{verbatim}
---------------------------------
6 8 57
0xc00c456e0ca2 0807060504030201  
0xc00c45432694 0103040506070802
---------------------------------
\end{verbatim}

The third example shows keying based on the combination of 
UDP port number and IP address.  The lookup data is 8 bytes 
long: 4 bytes of UDP port number and 4 bytes of IP address.  
This keying is appropriate when the CRYPT module is 
configured above UDP.
\begin{verbatim}
---------------------------------
8 8 57
0x000007d1c00c456e 0807060504030201  
0x00000100c00c4582 0103040506070802
0x000007d1c00c4587 010304a50607080f
---------------------------------
\end{verbatim}

The fourth example shows some additional features of the key
file parser.  Addresses and keys may be character strings instead
of hex byte strings; the strings are demarcated with double-quotes.
For long keys, the backslash character may be used to hide line
breaks, to include octal-coded characters, and to quote backslash
and doublequote characters.  A comment may be placed after backslash-space.
Following a hidden newline, initial whitespace is discarded,
but another backslash turns off hiding.

Variable length keys are permitted.
To use this option, the first line of the file should have a range
of lengths instead of a single number.

The 0x in front of the address is optional for addresses, prohibited 
for keys.
Individual hex bytes may be separated with one space or punctuation
character.  A hex byte string is terminated with tab, newline,
double space, double punctuation, or the double-quote character.
Single space is allowed as a terminator when the byte string is
maximum permitted length, and no internal spaces have been used in 
the string.  Single hex digits are ok, but odd length blocks of
hex digits are not.  In AA-B-CCC-DDDD, the B is ok but the CCC isn't.

Comment lines begin with \#.  Also, any text following a key is treated as
a comment line, even without a \#.
\begin{verbatim}
---------------------------------
6-10  0-2000 100
"Alabama"  99 11 33 66  a four byte key
"Arkansas"      "An example of a very long \
                 key, that shows some of the \
                 uses of backslash, such as \
                 for breaking long lines, for \
                 including \000 oddball characters, \
                 for quoting \\ and \", \   freebie comment!
                 \  and for resuming scanning \
                 after a hidden line, \


                 and even hiding multiple blank lines!"
"Alaska"  ""  null key is not a good idea, but permitted
001122334455  "an address or key may be expressed either \
               as a character string, or as hex bytes" if you want
0X C0 C 45 74 fF Ff   3141-59:2653;58,97  punctuation run riot
#and finally, an ordinary comment
---------------------------------
\end{verbatim}

Limited support for additional address styles is available.  The
following are only useful with 32-bit host addresses and can be
specified only through the input file (i.e., not {\em KMSET}).  These
styles impinge on the generality of the quoted string facility.

\noindent CAVEAT: these might need byte-swapping on some architectures.
If so, this should be considered a bug in the key manager code that
needs fixing.

The 4-byte IP address style is supported when enclosed in quotes:
\begin{verbatim}
4 4 16
"192.12.69.113"	000000003
\end{verbatim}

Wildcard bytes with the 4-byte IP address style are supported.  The
``*'' character can be used to specify a byte that is ignored in matches:
\begin{verbatim}
4 4 16
"192.12.69.*"	000000003
\end{verbatim}
The wildcard matches are processed in the {\em open} and {\em openenable}
routines after attempting a specific match.  The wildcards are
processed in the order they occur in the keys file.

A general 32-bit mask can be specified using ``x'' to specify ``don't care''
bits.
\begin{verbatim}
4 4 16
"m 110xxxxxx111111111111111111111111"	000000003
\end{verbatim}
In the example above, the first two characters (``m '') indicate that
a bit mask follows.  The string will match any bitstring with ones and
zeroes in the indicated positions.  Bits in the ``x'' positions do
not matter.

\medskip

\topic{AUTHORS}

\noindent David C. Schwartz, Sean W. O'Malley, and Rich Schroeppel.

