Tons of fixes, debugging, changes, added apache module

1 files changed, 76 insertions, 19 deletions

diff --git a/doc/protocol.txt b/doc/protocol.txt
index 05e32f2..b6bc0ba 100644
--- a/doc/protocol.txt
+++ b/doc/protocol.txt
@@ -1,22 +1,39 @@
 
-                    HTTP/AUTH PROTOCOL
+                       HTTPAUTH PROTOCOL
 
 The protocol used between the stateful authenticator and the web servers
 that wish to authenticate is described below. It's a simple text protocol,
-similar to HTTP. The web servers send commands and headers to the daemon,
+similar to HTTP. The web server sends commands and headers to the daemon,
 which replies with HTTP codes and headers.
 
 Multiple authentication requests can be processed on the same connection,
-although the connection is not stateful. A authentication request initially
-processed through one connection to the daemon can later be completed
-through another. The commands are described below.
+although the connection is not necessarily stateful. A authentication
+request initially processed through one connection to the daemon can
+later be completed through another. The commands are described below.
 
-AUTH method uri
+After connecting to the daemon, you'll need to retrieve the initial
+'ready' response before sending requests. See below. If the server
+responds with a 5xx message then something's gone wrong and no requests
+will be accepted on the connection.
+
+
+REQUESTS -------------------------------------------------------------------
+
+AUTH authmethod connid method uri
 
   The AUTH command asks the daemon to perform authentication
-  for a given set of headers.
+  for a given set of header from the client. None of the
+  arguments should contain spaces.
+
+  authmethod: is the authentication method. Methods are
+       defined by the daemon in it's config file.
+
+  connid: a unique string identifying the connection from
+       the client. This is only important when NTLM is
+       being used. If not, pass a random string.
+
+  method: The HTTP method employed. 'GET' or 'POST' etc...
 
-  method: is the authentication type. It might be 'NTLM'.
   uri: the URI being authenticated.
 
   The AUTH command is followed by HTTP headers, one per line
@@ -24,23 +41,63 @@ AUTH method uri
   authentication headers for the authentication protocol being
   used. Extraneous headers are ignored.
 
-  If multiple HTTP headers with the same name are received, then
-  the last one is used. Note that this is somewhat different than
-  the HTTP protocol.
+  Headers should be specified on one line, not 'wrapped' as is
+  permissible in HTTP.
 
 QUIT
 
   This closes the connection to the daemon.
 
 
-The response from the daemon consists of an HTTP code, followed by headers
-one per line. Note that only the headers to be added for authentication are
-returned. For example:
 
-  401
-  Header: value
-  Header2: value
+RESPONSES -------------------------------------------------------------------
+
+The response from the daemon consists of a code, followed by a detail
+message value or set of values. This is separated from the code by a
+space. The content of the detail message is described below.
+
+The codes are similar to HTTP:
+
+  100 Ready
+    (detail is the list of available authmethods)
+
+  200 Successful Request
+    (detail is described below)
+
+  4xx Request Error
+    (detail is an error message)
+
+  5xx Server Error
+    (detail is an error message)
+
+
+READY
+
+After opening a connection to the daemon, you should receive a response
+(outlined below) of 100 indicating ready. The 'detail' value is set
+to the list of authmethods that the daemon is configured to provide.
+These are separated by spaces:
+
+  100 Domain Simple Test LDAP
+
+
+SUCCESS
+
+Successful processing of a request returns a 200. The detail constists of,
+an HTTP code to send to the client and the user name (when authentication is
+successful). These are separated by spaces.
+
+In addition the daemon might send a set of headers that must be sent to
+the client. These are ended by a blank line.
+
+A response after client authentication failed might look like this:
+
+  200 401
+  WWW-Authenticate: realm="blah"
+
+... or a client authentication success response like this:
+
+  200 200 testo
+  Authorization-Info: Digest rspauth="2034980294820398" nonce="2049823094328" ...
 
-Success returns a 200, just like normal HTTP. Note that success can contain
-headers that must also be sent to the client.