Move authentication into POSIX part.

Downgrade subsubsections to paragraphs again.

5 files changed, 175 insertions, 176 deletions

diff --git a/doc/authentication.tex b/doc/authentication.tex
deleted file mode 100644
index 817afa9..0000000
--- a/doc/authentication.tex
+++ /dev/null
@@ -1,158 +0,0 @@
-\chapter{Authentication}
-\label{auth}
-
-Capabilities are a good way to give access to protected objects and
-services.  They are flexible, lightweight and generic.  However, Unix
-traditionally uses access control lists (ACL) to restrict access to
-objects like files.  Any task running with a certain user ID can
-access all files that are readable for the user with that user ID.
-Although all objects are implemented as capabilities in the Hurd, the
-Hurd also supports the use of user IDs for access control.
-
-The system authentication server \texttt{auth} implements the Unix
-authentication scheme using capabilities.  It provides auth
-capabilities, which are associated with a list of effective and
-available user and group IDs.  The holder of such a capability can use
-it to authenticate itself to other servers, using the protocol below.
-
-Of course, these other servers must use (and trust) the same
-\texttt{auth} server as the user.  Otherwise, the authentication will
-fail.  Once a capability is authenticated in the server, the server
-will know the user IDs of the client, and can use them to validate
-further operations.
-
-The \texttt{auth} server provides two types of capabilities:
-
-\subsubsection{Auth capabilities}
-An auth capability is associated with four vectors of IDs: The
-effective user and group IDs, which should be used by other servers to
-authenticate operations that require certain user or group IDs, and
-the available user and group IDs.  Available IDs should not be used
-for authentication purposes, but can be turned into effective IDs by
-the holder of an auth capability at any time.
-
-New auth capabilities can be created from existing auth capabilities,
-but only if the requested IDs are a subsets from the union of the
-(effective and available) IDs in the provided auth capabilities.  If
-an auth capability has an effective or available user ID 0, then
-arbitrary new auth objects can be created from that.
-
-\subsubsection{Passport capabilities}
-A passport capability can be created from an auth capability and is
-only valid for the task that created it.  It can be provided to a
-server in an authentication process (see below).  For the client, the
-passport capability does not directly implement any useful operation.
-For the server, it can be used to verify the identity of a user and
-read out the effective user and group IDs.
-
-The auth server should always create new passport objects for
-different tasks, even if the underlying auth object is the same, so
-that a task having the passport capability can not spy on other tasks
-unless they were given the passport capability by that task.
-
-\section{Authenticating a client to a server}
-
-A client can authenticate itself to a server with the following
-protocol:
-
-\subsubsection{Preconditions}
-The client $C$ has an auth capability implemented by the \texttt{auth}
-server $A$.  It also has a capability implemented by the server $S$.
-It wants to reauthenticate this capability with the auth capability,
-so the server associates the new user and group IDs with it.
-
-The server also has an auth capability implemented by its trusted
-\texttt{auth} server.  For the reauthentication to succeed, the
-\texttt{auth} server of the client and the server must be identical.
-If this is the case, the participating tasks hold task info caps for
-all other participating tasks (because of the capabilities they hold).
-
-\begin{enumerate}
-\item The client $C$ requests the passport capability for itself from
-  the auth capability from $A$.
-
-  \begin{comment}
-    Normally, the client will request the passport capability only
-    once and store it together with the auth capability.
-  \end{comment}
-  
-\item The \texttt{auth} server receives the request and creates a new
-  passport capability for this auth capability and this client.  The
-  passport capability is returned to the user.
-  
-\item The user receives the reply from the \texttt{auth} server.
-  
-  It then sends the reauthentication request to the server $S$, which
-  is invoked on the capability the client wants to reauthenticate.  It
-  provides the passport capability as an argument.
-  
-\item The server $S$ can accept the passport capability, if it
-  verifies that it is really implemented by the \texttt{auth} server
-  it trusts.  If the client does not provide a passport capability to
-  the trusted \texttt{auth} server, the authentication process is
-  aborted with an error.
-  
-  Now the server can send a request to the \texttt{auth} server to
-  validate the passport capability.  The RPC is invoked on the
-  passport capability.
-  
-\item The \texttt{auth} server receives the validation request on the
-  passport capability and returns the task ID of the client $C$ that
-  this passport belongs to, and the effective user and group IDs for
-  the auth cap to which this passport cap belongs.
-
-  \begin{comment}
-    The Hurd on Mach returned the available IDs as well.  This feature
-    is not used anywhere in the Hurd, and as the available IDs should
-    not be used for authentication anyway, this does not seem to be
-    useful.  If it is needed, it can be added in an extended version
-    of the validation RPC.
-  \end{comment}
-  
-\item The server receives the task ID and the effective user and group
-  IDs.  The server now verifies that the task ID is the same as the
-  task ID of the sender of the reauthentication request.  Only then
-  was the reauthentication request made by the owner of the auth cap.
-  It can then return a new capability authenticated with the new user
-  and group IDs.
-
-  \begin{comment}
-    The verification of the client's task ID is necessary.  As the
-    passport cap is copied to other tasks, it can not serve as a proof
-    of identity alone.  It is of course absolutely crucial that the
-    server holds the task info cap for the client task $C$ for the
-    whole time of the protocol.  But the same is actually true for any
-    RPC, as the server needs to be sure that the reply message is sent
-    to the sender thread (and not any imposter).
-  \end{comment}
-  
-\item The client receives the reply with the new, reauthenticated
-  capability.  Usually this capability is associated in the server
-  with the same abstract object, but different user credentials.
-
-  \begin{comment}
-    Of course a new capability must be created.  Otherwise, all other
-    users holding the same capability would be affected as well.
-  \end{comment}
-
-  The client can now deallocate the passport cap.
-
-  \begin{comment}
-    As said before, normally the passport cap is cached by the client
-    for other reauthentications.
-  \end{comment}
-\end{enumerate}
-
-\subsubsection{Result}
-The client $C$ has a new capability that is authenticated with the new
-effective user and group IDs.  The server has obtained the effective
-user and group IDs from the \texttt{auth} server it trusts.
-
-\begin{comment}
-  The Hurd on Mach uses a different protocol, which is more complex
-  and is vulnerable to DoS attacks.  The above protocol can not
-  readily be used on Mach, because the sender task of a message can
-  not be easily identified.
-\end{comment}
-
-
diff --git a/doc/hurd-on-l4.tex b/doc/hurd-on-l4.tex
index 8d8ffaa..1b22e73 100644
--- a/doc/hurd-on-l4.tex
+++ b/doc/hurd-on-l4.tex
@@ -20,7 +20,6 @@
 \include{ipc}
 \include{threads-tasks}
 \include{vmm}
-\include{authentication}
 \include{posix}
 \include{debugging}
 \include{device-drivers}
diff --git a/doc/ipc.tex b/doc/ipc.tex
index 522faf5..01f4dd0 100644
--- a/doc/ipc.tex
+++ b/doc/ipc.tex
@@ -236,7 +236,7 @@ is to give both participants a chance to acquire a task info cap for
 the other participants task ID, so they can be sure that from there on
 they will always talk to the same task as they talked to before.
 
-\subsubsection{Preconditions}
+\paragraph{Preconditions}
 The client knows the thread ID of the server thread that receives and
 processes the bootstrap messages.  Some other task might hold a task
 info capability to the server the client wants to connect to.
@@ -373,7 +373,7 @@ have to take it out of the long version.
   \end{comment}
 \end{enumerate}
 
-\subsubsection{Result}
+\paragraph{Result}
 The client has a task info capability for the server and an
 authenticated capability.  The server has a task info capability for
 the client and seen some sort of authentication for the capability it
@@ -419,7 +419,7 @@ also robust and secure.  If any of the participants dies unexpectedly,
 or any of the untrusted participants is malicious, the others should
 not be harmed.
 
-\subsubsection{Preconditions}
+\paragraph{Preconditions}
 The client $C$ has a capability from server $S$ (this implies that $C$
 has a task info cap for $S$ and $S$ has a task info cap for $C$).  It
 wants to copy the capability to the destination task $D$.  For this,
@@ -615,7 +615,7 @@ have to take it out of the long version.
 
 \end{enumerate}
 
-\subsubsection{Result}
+\paragraph{Result}
 For the client $C$, nothing has changed.  The destination task $D$
 either did not accept the capability, and nothing has changed for it,
 and also not for the server $S$.  Or $D$ accepted the capability, and
@@ -671,7 +671,7 @@ If you find any other problematic scenario, again, let us know.
   important information about how, and more importantly, why it works.
 \end{comment}
 
-\subsubsection{The server $S$ dies}
+\paragraph{The server $S$ dies}
 What happens if the server $S$ dies unexpectedly sometime throughout
 the protocol?
 
@@ -700,7 +700,7 @@ send messages to $S$.
 Eventually, $C$ (and $D$ if it already got the task info cap for $S$)
 will process the task death notification and clean up their state.
 
-\subsubsection{The client $C$ dies}
+\paragraph{The client $C$ dies}
 The server $S$ and the destination task $D$ hold a task info cap for
 $C$, so no imposter can get its task ID.  $S$ and $D$ will get errors
 when trying to send messages to $C$.  Depending on when $C$ dies, the
@@ -720,7 +720,7 @@ include the empty reference container, if any.
   suggests that.
 \end{comment}
 
-\subsubsection{The destination task $D$ dies}
+\paragraph{The destination task $D$ dies}
 
 The client $C$ holds a task info cap for $D$ over the whole operation,
 so no imposter can get its task ID.  Depending on when $D$ dies, it
@@ -728,7 +728,7 @@ has either not yet accepted the capability, then $C$ will clean up by
 destroying the reference container, or it has, and then $S$ will clean
 up its state when it processes the task death notification for $D$.
 
-\subsubsection{The client $C$ and the destination task $D$ die}
+\paragraph{The client $C$ and the destination task $D$ die}
 
 This scenario is the reason why the server acquires its own task info
 cap for $D$ so early, and why it must do that under the constraint
@@ -761,7 +761,7 @@ is processed.  Either way no imposter can get at the capability.
 Of course, if the capability was already copied at the time $C$ and
 $D$ die, the server will just do the normal cleanup.
 
-\subsubsection{The client $C$ and the server $S$ die}
+\paragraph{The client $C$ and the server $S$ die}
 
 This scenario does not cause any problems, because on the one hand,
 the destination task $D$ holds a task info cap for $C$, and it
@@ -774,14 +774,14 @@ possible to get because $C$ died early, would not receive any message
 from $D$ because $D$ uses $C$ as its constraint in acquireing the task
 info cap for $S$.
 
-\subsubsection{The destination task $D$ and the server $S$ die}
+\paragraph{The destination task $D$ and the server $S$ die}
 
 As $C$ holds task info caps for $S$ and $D$, there is nothing that can
 go wrong here.  Eventually, the task death notifications are
 processed, but the task info caps are not released until the protocol
 is completed or aborted because of errors.
 
-\subsubsection{The client $C$, the destination task $D$ and the server $S$ die}
+\paragraph{The client $C$, the destination task $D$ and the server $S$ die}
 
 Before the last one of these dies, you are in one of the scenarios
 which already have been covered.  After the last one dies, there is
@@ -812,7 +812,7 @@ in the following paragraphs.
   server $S$.
 \end{comment}
 
-\subsubsection{The client $C$ is malicious}
+\paragraph{The client $C$ is malicious}
 
 If the client $C$ wants to break the protocol, it has numerous
 possibilities to do so.  The first thing it can do is to provide a
@@ -908,7 +908,7 @@ cap for an imposter of $D$.  But if the client wants to achieve that,
 it could just follow the protocol with the imposter as the destination
 task.
 
-\subsubsection{The destination task $D$ is malicious}
+\paragraph{The destination task $D$ is malicious}
 
 The destination task has not as many possibilities as $C$ to attack
 the protocol.  This is because it is trusted by $C$.  So the only
@@ -937,7 +937,7 @@ it can only cause other transactions in its own task to fail.
   The destination task $D$ is welcome to shoot itself in its foot.
 \end{comment}
 
-\subsubsection{The client $C$ and the destination task $D$ are malicious}
+\paragraph{The client $C$ and the destination task $D$ are malicious}
 
 The final question we want to raise is what can happen if the client
 $C$ and the destination task $D$ are malicious.  Can $C$ and $D$
diff --git a/doc/posix.tex b/doc/posix.tex
index 953f1ea..708bde1 100644
--- a/doc/posix.tex
+++ b/doc/posix.tex
@@ -5,6 +5,164 @@ implemented in the GNU C library which uses the services provided by
 the Hurd servers.  Several system servers support the C library.
 
 
+\section{Authentication}
+\label{auth}
+
+Capabilities are a good way to give access to protected objects and
+services.  They are flexible, lightweight and generic.  However, Unix
+traditionally uses access control lists (ACL) to restrict access to
+objects like files.  Any task running with a certain user ID can
+access all files that are readable for the user with that user ID.
+Although all objects are implemented as capabilities in the Hurd, the
+Hurd also supports the use of user IDs for access control.
+
+The system authentication server \texttt{auth} implements the Unix
+authentication scheme using capabilities.  It provides auth
+capabilities, which are associated with a list of effective and
+available user and group IDs.  The holder of such a capability can use
+it to authenticate itself to other servers, using the protocol below.
+
+Of course, these other servers must use (and trust) the same
+\texttt{auth} server as the user.  Otherwise, the authentication will
+fail.  Once a capability is authenticated in the server, the server
+will know the user IDs of the client, and can use them to validate
+further operations.
+
+The \texttt{auth} server provides two types of capabilities:
+
+\paragraph{Auth capabilities}
+An auth capability is associated with four vectors of IDs: The
+effective user and group IDs, which should be used by other servers to
+authenticate operations that require certain user or group IDs, and
+the available user and group IDs.  Available IDs should not be used
+for authentication purposes, but can be turned into effective IDs by
+the holder of an auth capability at any time.
+
+New auth capabilities can be created from existing auth capabilities,
+but only if the requested IDs are a subsets from the union of the
+(effective and available) IDs in the provided auth capabilities.  If
+an auth capability has an effective or available user ID 0, then
+arbitrary new auth objects can be created from that.
+
+\paragraph{Passport capabilities}
+A passport capability can be created from an auth capability and is
+only valid for the task that created it.  It can be provided to a
+server in an authentication process (see below).  For the client, the
+passport capability does not directly implement any useful operation.
+For the server, it can be used to verify the identity of a user and
+read out the effective user and group IDs.
+
+The auth server should always create new passport objects for
+different tasks, even if the underlying auth object is the same, so
+that a task having the passport capability can not spy on other tasks
+unless they were given the passport capability by that task.
+
+\subsection{Authenticating a client to a server}
+
+A client can authenticate itself to a server with the following
+protocol:
+
+\paragraph{Preconditions}
+The client $C$ has an auth capability implemented by the \texttt{auth}
+server $A$.  It also has a capability implemented by the server $S$.
+It wants to reauthenticate this capability with the auth capability,
+so the server associates the new user and group IDs with it.
+
+The server also has an auth capability implemented by its trusted
+\texttt{auth} server.  For the reauthentication to succeed, the
+\texttt{auth} server of the client and the server must be identical.
+If this is the case, the participating tasks hold task info caps for
+all other participating tasks (because of the capabilities they hold).
+
+\begin{enumerate}
+\item The client $C$ requests the passport capability for itself from
+  the auth capability from $A$.
+
+  \begin{comment}
+    Normally, the client will request the passport capability only
+    once and store it together with the auth capability.
+  \end{comment}
+  
+\item The \texttt{auth} server receives the request and creates a new
+  passport capability for this auth capability and this client.  The
+  passport capability is returned to the user.
+  
+\item The user receives the reply from the \texttt{auth} server.
+  
+  It then sends the reauthentication request to the server $S$, which
+  is invoked on the capability the client wants to reauthenticate.  It
+  provides the passport capability as an argument.
+  
+\item The server $S$ can accept the passport capability, if it
+  verifies that it is really implemented by the \texttt{auth} server
+  it trusts.  If the client does not provide a passport capability to
+  the trusted \texttt{auth} server, the authentication process is
+  aborted with an error.
+  
+  Now the server can send a request to the \texttt{auth} server to
+  validate the passport capability.  The RPC is invoked on the
+  passport capability.
+  
+\item The \texttt{auth} server receives the validation request on the
+  passport capability and returns the task ID of the client $C$ that
+  this passport belongs to, and the effective user and group IDs for
+  the auth cap to which this passport cap belongs.
+
+  \begin{comment}
+    The Hurd on Mach returned the available IDs as well.  This feature
+    is not used anywhere in the Hurd, and as the available IDs should
+    not be used for authentication anyway, this does not seem to be
+    useful.  If it is needed, it can be added in an extended version
+    of the validation RPC.
+  \end{comment}
+  
+\item The server receives the task ID and the effective user and group
+  IDs.  The server now verifies that the task ID is the same as the
+  task ID of the sender of the reauthentication request.  Only then
+  was the reauthentication request made by the owner of the auth cap.
+  It can then return a new capability authenticated with the new user
+  and group IDs.
+
+  \begin{comment}
+    The verification of the client's task ID is necessary.  As the
+    passport cap is copied to other tasks, it can not serve as a proof
+    of identity alone.  It is of course absolutely crucial that the
+    server holds the task info cap for the client task $C$ for the
+    whole time of the protocol.  But the same is actually true for any
+    RPC, as the server needs to be sure that the reply message is sent
+    to the sender thread (and not any imposter).
+  \end{comment}
+  
+\item The client receives the reply with the new, reauthenticated
+  capability.  Usually this capability is associated in the server
+  with the same abstract object, but different user credentials.
+
+  \begin{comment}
+    Of course a new capability must be created.  Otherwise, all other
+    users holding the same capability would be affected as well.
+  \end{comment}
+
+  The client can now deallocate the passport cap.
+
+  \begin{comment}
+    As said before, normally the passport cap is cached by the client
+    for other reauthentications.
+  \end{comment}
+\end{enumerate}
+
+\paragraph{Result}
+The client $C$ has a new capability that is authenticated with the new
+effective user and group IDs.  The server has obtained the effective
+user and group IDs from the \texttt{auth} server it trusts.
+
+\begin{comment}
+  The Hurd on Mach uses a different protocol, which is more complex
+  and is vulnerable to DoS attacks.  The above protocol can not
+  readily be used on Mach, because the sender task of a message can
+  not be easily identified.
+\end{comment}
+
+
 \section{Process Management}
 \label{proc}
 
diff --git a/doc/threads-tasks.tex b/doc/threads-tasks.tex
index 07e691f..4a8f2fd 100644
--- a/doc/threads-tasks.tex
+++ b/doc/threads-tasks.tex
@@ -14,7 +14,7 @@ threads, and to destroy them.
 
 The \texttt{task} server provides three different capability types.
 
-\subsubsection{Task control capabilities}
+\paragraph{Task control capabilities}
 If a new task is created, it is always associated with a task control
 capability.  The task control capability can be used to create and
 destroy threads in the task, and destroy the task itself.  So the task
@@ -31,7 +31,7 @@ that task.
   capability reference is released.
 \end{comment}
 
-\subsubsection{Task info capabilities}
+\paragraph{Task info capabilities}
 \label{taskinfocap}
 Any task can create task info capabilities for other tasks.  Such task
 info capabilities are used mainly in the IPC system (see section
@@ -74,7 +74,7 @@ capabilities for that task.
   do not need anymore.
 \end{comment}
 
-\subsubsection{Task manager capability}
+\paragraph{Task manager capability}
 A task is a relatively simple object, compared to a full blown POSIX
 process, for example.  As the \texttt{task} server is enforced system
 code, the Hurd does not impose POSIX process semantics in the task