%%% -*-LaTeX-*-
%%%
-%%% $Id: become.tex,v 1.2 1997/08/04 10:24:20 mdw Exp $
+%%% $Id: become.tex,v 1.3 1997/08/07 09:37:44 mdw Exp $
%%%
%%% Documentation for `become'
%%%
%%%----- Revision history ---------------------------------------------------
%%%
%%% $Log: become.tex,v $
+%%% Revision 1.3 1997/08/07 09:37:44 mdw
+%%% Updated to reflect new `become' version. Included description of multiple
+%%% server support, netgroup handling, larger random seed file, and so on.
+%%%
%%% Revision 1.2 1997/08/04 10:24:20 mdw
%%% Sources placed under CVS control.
%%%
-% Revision 1.1 1997/07/21 13:47:54 mdw
-% Initial revision
-%
+%%% Revision 1.1 1997/07/21 13:47:54 mdw
+%%% Initial revision
+%%%
%%%----- Document preamble --------------------------------------------------
The program contains nontrivial pieces of code owned by the European
Bioinformatics Institute, Mark Wooding and Straylight (even though I
actually wrote it all). Thanks also to the Free Software Foundation for
- Autoconf; to Ron Rivest for the MD5 message digest algorithm; to Xuekia
+ Autoconf; to Ron Rivest for the MD5 message digest algorithm; to Xuejia
Lai and James Massey for the IDEA cipher; and to Bruce Schneier, for
writing \emph{Applied Cryptography}, which explained why I'd written the
first version of all this code wrong.} \\
system vendor hasn't bothered to comply with an eight year old standard,
you ought to firstly complain to your vendor, and secondly install the
GNU~C compiler.}
-\item You need a copy of GNU make to build the software. This can be
- obtained from any GNU software archive.
\item You'll probably need GNU flex and bison to rebuild the scanner and
parser. However, prebuilt C~source for these components is provided, and
will probably work.
The \become\ software is distributed as a gzipped tape archive: saying
\begin{verbatim}
- $ gunzip -c become-1.1.tar.gz | tar xvf -
+ $ gunzip -c become-1.2.tar.gz | tar xvf -
\end{verbatim}
will decompress and unpack the source code into a directory
-\path{become-1.1}.
+\path{become-1.2}.
The software must be configured prior to compilation. The author has used
the Free Software Foundation's Autoconf system which will (with luck)
$ ./configure --help
\end{verbatim}
-You can now build the programs by invoking GNU make. Whether simply typing
-\texttt{make} is sufficient to run GNU make depends on your site: ask around
-if you don't know how to invoke GNU make.
+You can now build the programs by invoking make.
Finally, you can install the various files to their correct directories by
saying
\item a \emph{standalone} installation, where the configuration is stored
locally, and
\item a \emph{centralised} installation, where the configuration is stored on
- a central (and trusted) server.
+ a central trusted server.
\end{itemize}
The difference is basically how you want to maintain the configuration. In
the standalone case, you have to ensure that the configuration file is copied
lots of commands at the same time.
\end{itemize}
-Also, note that lots of user classes come \emph{predefined}. A class is
-defined for every user, named with the user's name, and containing that user.
-Also, for every group, there is a class, named with the group's name, which
-contains all users who are members of that group. You can redefine these
-classes if you like: they're meant to be a convenience, but if you don't like
-them, you don't have to use them.
+\subsubsection{Predefined names}
-A warning is in order: some systems have group names which are also user
-names: in this case, a class is defined containing the named user \emph{and}
-all the members of the group. That's probably not desirable.
+Before reading the configuration file, \become\ predefines a collection of
+classes:
+\begin{itemize}
+\item For every user $u$, a class `$u$' is created containing that user.
+\item For every group $g$, a class `$g$' is created containing all members of
+ that group.
+\item For each netgroup $n$ read from the NIS server, a class `\lit*{u_}$n$'
+ is created containing all the users listed in the netgroup, and a class
+ `\lit{h_}$n$' containing the IP address of all the hosts listed in the
+ netgroup.\footnote{
+ Netgroups don't fit in particularly well with \become's way of thinking.
+ The netgroup idea tries to bind users and hosts together in tight little
+ bundles, which doesn't help here. The current behaviour of splitting
+ the tight little host--user--domain bundles into separate lists of users
+ and hosts is, to the author's knowledge, the cleanest way of making
+ netgroups useful.
+
+ It should probably be pointed out that, in general, NIS should be
+ considered insecure. Nothing too terrible should happen if you run your
+ \become\ server on the NIS master machine.}
+\end{itemize}
+User and group names can contain characters (e.g., dashes or dots) which
+aren't allowed in \become\ class names; \become\ automatically translates
+any non-alphanumeric characters into underscores.
+
+Note that by the end of this process, each class contains the \emph{union} of
+all the things which are automatically put there. So if your system has a
+`root' group, then the class \lit{root} ends up containing the root user
+together with all members of the root group. You can be sure of referring to
+a single user by enclosing the user name in quotes. Hence
+\begin{verbatim}
+ allow HACKERS -> rcs;
+\end{verbatim}
+lets your syshacks become anyone in the rcs group, whereas
+\begin{verbatim}
+ allow HACKERS -> "rcs";
+\end{verbatim}
+lets them become the rcs user only.
\subsection{Configuring standalone installations}
If you're only interested in setting up a standalone installation, then
you're finished, and can get on with doing something interesting.
-Alternatively, read on, and see all the work you don't have to do.
+Alternatively, read on, and see all the work you don't have to do. You
+should probably note, however, that reading a configuration file for a
+reasonable-sized site takes quite a long while, though; doing this in a
+central server will make your users happier, as well as being less work for
+you.
\subsection{Keys and random numbers}
Both of these files should be stored on a local filesystem, and they should
be readable only by the super-user.
-Each of the two files, the key and the random number file, contain a 128-bit
-number, written in hexadecimal. To make the thing more readable, you may
-insert dashes in the number between each chunk of eight digits.\footnote{
- Actually, you can insert dashes wherever you like in the number, but
- this is only because the parser is rather primitive. The author recommends
- that you stick with every eight digits.}
+The key contains a 128-bit number; the random number file contains a 512-bit
+number. Both numbers are written in hexadecimal. To make the thing more
+readable, you may insert dashes in the number between each chunk of eight digits.\footnote{
+ Actually, you can insert dashes wherever you like in the number, but this
+ is only because the parser is rather primitive. The author recommends that
+ you stick with every eight digits.}
Here's an example of a possible key file:
\begin{verbatim}
4fda99b0-fcbd8bcb-d1bcf951-e1ed04c9
\end{verbatim}
-You should generate 128 genuinely random bits for each file. It is
+You should generate 128 genuinely random bits for the key file. It is
\emph{not} good enough to use a computer random number generator. A program
will be supplied later which will examine key timings as a source for random
numbers. Also, don't use the number printed above. That would be really
-silly.
-
-To help you do this, a program `keygen' is provided. It uses timings of
-keypresses to generate random numbers. To use the program to generate (for
-example) the random number seed file, type
+silly. To help you do this, a program `keygen' is provided. It uses timings
+of keypresses to generate random numbers. To use the program to generate
+the key file, type
\begin{verbatim}
- $ keygen -o become.random
+ $ keygen -o become.key
\end{verbatim}
Keygen will report the number of bits which still need to be generated. Keep
typing until it says `done'. The program automatically ensures that its
generated, which is correct for IDEA keys. If you omit the \<file-name>, the
random key is written to standard output.
+The random number file can be generated by saying
+\begin{verbatim}
+ keygen -o become.random -b 512
+\end{verbatim}
+However, \become\ will generate a random number file if it can't find one.
+Note that its randomness acquisition isn't completely wonderful yet; the
+author recommends that you \emph{do} generate a seed file.
+
\subsection{Setting up the server and clients}
+As of version 1.2, the \become\ client is capable of sending its request to
+multiple servers, which makes it more resilient to server failures.
+
You don't need a separate program to run as a \become\ server: the normal
\become\ is quite capable of behaving as a server all by itself. However,
before you start the server up, you need to decide on a port to which it will
\end{verbatim}
Now to configure the clients. All they need is a file saying where to find
-the server. All this contains is a single line of the form
+the server or servers. This has the syntax:
\begin{syntdiag}
- <host-name> \[ `:' <port-number> \]
+ \< <host-name> \[ `:' <port> \] \>
\end{syntdiag}
-If you omit the port number (or it's otherwise incomprehensible) then
-\become\ looks at the services table (again using the name under which it was
-invoked) to find a port. If it still can't find a port to use, then \become\
-complains.
-
-The server wakes up every five minutes to rescan its configuration and
+The \<port> can be either a number (which is used directly) or a service
+name, which is looked up in the system's services database (typically
+\texttt{/etc/services}). If you omit the port number, then \become\ looks in
+the services database for a service with the name used to invoke it. This
+usage isn't recommended, however.\footnote{
+ It's not actually a security risk, because even though a user could
+ potentially make the client send its request to a different server, the
+ server would only be able to build a valid reply if it knew the correct
+ key.}
+
+The server wakes up every half an hour to rescan its configuration and
encryption key. Thus, it should react fairly quickly to changes to the user
database or to its configuration. However, you can always force the server
to refetch its configuration files by sending it a SIGHUP signal. To help
attacks, even though the user can make the client send arbitrary messages.
-\subsection{The random number generator}
-
-The random number generator is used to generate initialisation vectors and
-session keys for the cryptographic protocol above. The random number
-generator might well change in later versions of \become.
-
-The current implementation maintains an $n$-bit random number seed~$R_i$. It
-generates a 128-bit session key~$s$, an initialisation vector~$IV$ and a new
-seed~$R_{i+1}$.
-\[
- \begin{eqalign}
- s &= MD5(R_i, t, p, k) \cr
- IV &= MD5(R_i, t, p, s)[0:64] \cr
- R_{i + 1} &= (R_i[n - 128 : n] \xor s, R_i[0 : n - 128]) \cr
- \end{eqalign}
-\]
-\ifxypic
- See figure~\ref{fig:become.randgen} for a diagrammatic representation of
- the generator. It's
-\else
- This is
-\fi
-really just a weird sort of feedback shift register, generating 128~bits of
-data at a time.
-
-\ifxypic
-\begin{figure}
-
- \xymatrix{
-
- }
-
- \caption{The \become\ random number generator}
- \label{fig:become.randgen}
-\end{figure}
-\fi
-
-
-The use of the secret key~$k$ helps to ensure that even if the random number
-seed is compromised, an attacker still needs to know $k$ before he can
-predict session keys. Of course, if the attacker knows $k$, he has no need
-to predict session keys: he can just decrypt them from the messages. The use
-of the values $t$ and $p$ attempts to add a small quantity of randomness to
-the seed in each iteration.
-
-
\subsection{The `keygen' program}
The `keygen' program attempts to take advantage of the variations in time
\item Feed the client program bad input to overflow a fixed-size buffer. The
bad input contains executable code which gives the attacker a privileged
shell. The author isn't aware of any buffers which might overflow as a
- result of user-supplied data.
+ result of user-supplied data, and has checked the source rather carefully.
\end{itemize}
\end{itemize}
-%%%----- Licencing conditions -----------------------------------------------
-
-\input{gpl}
-
%%%----- That's all, folks --------------------------------------------------
\end{document}
~mdw / become / commitdiff