X-Git-Url: https://git.distorted.org.uk/~mdw/become/blobdiff_plain/03f996bd8a0d6391518979cdab3dbe38cba0bf83..46cc26eb66585c23ca816e17b7e1721585b4057a:/manual/become.tex

diff --git a/manual/become.tex b/manual/become.tex
index 16785b5..c01fd02 100644
--- a/manual/become.tex
+++ b/manual/become.tex
@@ -1,6 +1,6 @@
 %%% -*-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'
 %%%
@@ -28,12 +28,16 @@
 %%%----- 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 --------------------------------------------------
 
@@ -96,7 +100,7 @@
     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.} \\
@@ -182,8 +186,6 @@ Before you begin, there are some prerequisites you should check:
     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.
@@ -194,10 +196,10 @@ Before you begin, there are some prerequisites you should check:
 
 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)
@@ -252,9 +254,7 @@ by passing the \texttt{--help} option:
     $ ./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
@@ -277,7 +277,7 @@ the rules describing who is allowed to become whom:
 \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
@@ -416,16 +416,46 @@ identifying members.
   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}
@@ -437,7 +467,11 @@ file and decide for itself whether to grant the user's request.
 
 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}
@@ -459,28 +493,26 @@ up two files, both in \become's system configuration directory:
 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
@@ -493,9 +525,20 @@ If you don't specify a \<number> of bits, a default of 128 random bits are
 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
@@ -537,16 +580,21 @@ run the daemon with a different configuration file, by using the
 \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
@@ -763,52 +811,6 @@ The use of ciphertext feedback mode attempts to prevent chosen-plaintext
 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
@@ -854,7 +856,7 @@ some possibilities which might occur to an attacker, though:
 \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}
 
@@ -877,10 +879,6 @@ attacks rely on misconfiguration:
 \end{itemize}
 
 
-%%%----- Licencing conditions -----------------------------------------------
-
-\input{gpl}
-
 %%%----- That's all, folks --------------------------------------------------
 
 \end{document}
