% Run this file through LaTex with the appropriate wrapper.

\chapter{Security Management}

\section{Configuration}

\subsection{Compilation Options}

The configuration file \file{h/config.h} in the ISODE source tree can be edited
to select various options. These are compile-time options --- QUIPU must be
re-compiled and re-installed before they take effect.

To select an option, add a line like this :
\begin{quote}\begin{verbatim}
#define <option_name>
\end{verbatim}\end{quote}

(Instead of $<$option\_name$>$, type the name of the option that you want).

If there is a line explicitly cancelling the option that you have selected,
it must be removed. Such lines look like this :
\begin{quote}\begin{verbatim}
#undef <option_name>
\end{verbatim}\end{quote}

The available options are as follows :

\begin{describe}
\item [NO\_STATS]

This option results in a DSA that doesn't record any usage and
audit information. From the standpoint of security, it is advisable not
to select this option. Audit logs are very useful for detecting and tracing
attempts to break the security of the system.

\item[HAVE\_PROTECTED]

This option results in a DSA that can perform protected simple authentication.
\item[HAVE\_RSA]

This option results in a DSA that can perform strong authentication. 
\end{describe}

To build a DSA that can perform strong or protected simple authentication,
you will need additional files that are not part of the ISODE.
These files (the ``QUIPU security upgrade'') are distributed by
University College London. For further information, contact :

\begin{verse}
Steve Kille \\
Department of Computer Science \\
University College London \\
Gower Street, \\
London, \\
England 
\end{verse}

\begin{verse}
Internet: quipu-security@cs.ucl.ac.uk
\end{verse}

\subsection{Quipu Userid}

The DSA should not run under the userid of the super-user ({\em root}). The
reason for this is that no application should be run as root unless it is
absolutely necessary, just in case an undetected bug causes it to malfunction.
(A process running as an ordinary user will be halted if it starts to
misbehave; One running as root might carry on and delete important files, for
example).

Ideally, the DSA should be assigned a special userid to run under. (Called,
for example, ``quipu''). If this is not possible, it should run under the
userid of the DSA manager. Whichever option is taken, we shall henceforth refer
to the selected userid as ``quipu'' in the documentation.

\subsection{File Permissions}

The EDB files are where QUIPU stores the contents of the Directory. As these
files potentially contain sensitive information, they should be readable and
writable only by the quipu userid.

There are two log files; one for debugging information and one for audit.
Both of these files should be readable and writable only by the quipu userid.
There is a potential problem here, in that ISODE's logging code usually makes
log files writable by everybody. To be on the safe side, make a separate
directory for QUIPU's logs (\file{/etc/isode/quipu-logs}, for example). Make this
directory only accessible by the quipu userid, and change the tailoring
parameter {\em logdir} so that the logs are written there.

\section{Discretionary Access Control}

The principles of discretionary access control are explained in the
Part II of this Manual. This section gives guidelines on setting the access
control lists for entries in the DIT.

\subsection{What must be Publicly Readable}

Some attributes are used by the Directory itself for routing and other
purposes. If these attributes are not publicly readable (and hence readable
by all DSA's) then the Directory's internal communications may fail. 
If a DUA gives messages such as ``Unavailable'' this is one possible cause.
Note that there are many other possible causes of such failures --- Network
congestion or a machine being down is the most likely explanation.

The following attributes ought to be publicly readable:

\begin{itemize}
\item
masterDSA
\item
slaveDSA
\item
presentationAddress
\item
userCertificate
\item
treeStructure
\end{itemize}

The {\em userPassword} attribute ought to be comparable by everybody, but not
readable.

\section{Audit}

\subsection{Enabling Auditing}

The {\em stats} parameter in the {\em quiputailor} file controls how much audit
information is kept. It is advisable to enable recording of audit events at 
levels {\em notice}, {\em exceptions}, and {\em fatal}.

\subsection{Relating Events to Users}

Most events in the usage log contain an {\em association descriptor} instead
of the name of the user who caused the event. An association descriptor is
a (small) number which identifies a connection to QUIPU. (It's rather like
knowing which terminal line a command came in on). To discover the user name,
it is necessary to scan back through the log to find the record for the start
of the association. This will contain the name of the user and how they
authenticated themselves.

\subsection{Format of Audit Records}

Each record in the log file is formatted as follows :-

\begin{quote}\begin{verbatim}
<AuditRecord> ::= <month> "/" <day> <time> <process> 
                  <pid> "(" <userid> ")" <Event>
\end{verbatim}\end{quote}

\begin{describe}
\item [time:]
The time of the event in hh:mm:ss format.
\item [process:]
The name of the program (quipu).
\item [pid:]
The process id of the DSA.
\item [userid:]
The id of the user who started the DSA running. It is {\em not} the id
of the DUA which caused the event!
\item [Event:]
is the rest of the message. The following sections describe most of the
common messages.
\end{describe}
	

\subsection{Start of an Association}

\begin{quote}\begin{verbatim}
<BindEvent> ::= "Bind" "(" <Integer> ")"
                 "(" <AuthType> ")" 
                 ":" <DN>
<AuthType> ::= "none" | "simple" | "protected" | "strong"
\end{verbatim}\end{quote}

For example :

\begin{quote}\begin{verbatim}
Bind (4) (simple): c=GB@o=University College 
         London@ou=Computer Science@cn=Steve Kille
\end{verbatim}\end{quote}

This means that Steve Kille has started using association descriptor 4, and
proved his identity using simple authentication (i.e. a password).

\subsection{End of an Association}

\begin{quote}\begin{verbatim}
<UnbindEvent> ::= "Unbind" "(" <Integer> ")" <WhoBy> 
      ":" <DN> <WhoBy> ::= "(by this)" | "(by that)"
\end{verbatim}\end{quote}

For example :

\begin{quote}\begin{verbatim}
Unbind (4) (by that): c=GB@o=University College
           London@ou=Computer Science@cn=Steve Kille
\end{verbatim}\end{quote}

This means that Steve Kille's DUA has disconnected from the DSA, and descriptor
4 is left free for use by someone else. The "(by that)" means that the DUA,
rather than the DSA, decided to close the connection.

\subsection{DAP Operation}

\begin{quote}\begin{verbatim}
<DAPOperationEvent> ::= <OpType> "(" <Integer> ")"
                         ":" <DN>
<OpType> ::= "Read" | "Search" | "List" | "Compare"
\end{verbatim}\end{quote}

For example :

\begin{quote}\begin{verbatim}
Read (4): c=gb@o=Nottingham University
\end{verbatim}\end{quote}

This means that whoever is using association 4 (Steve Kille in this example)
has read the entry for Nottingham University.

\subsection{DAP Result}

\begin{quote}\begin{verbatim}
<DAPResultEvent> ::= "Result sent" "(" <Integer> ")"
<DAPErrorEvent>  ::= "Error sent"  "(" <Integer> ")"
\end{verbatim}\end{quote}

Each operation will normally be answered by either a result or an error.

\subsection{Chaining}

\begin{quote}\begin{verbatim}
<ChainingEvent> ::= "Chain" "(" <Integer> ")"
\end{verbatim}\end{quote}

This means that the DSA has decided to contact another DSA in order to
perform the operation received previously.

\subsection{Other Events}

The are many other messages that can be written to the audit log. The text
messages should be self-explanatory.
