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 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 necessarily stateful. A authentication
request initially processed through one connection to the daemon can
later be completed through another. The commands are described below.

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 connid method uri

  The AUTH command asks the daemon to perform authentication
  for a given set of header from the client. None of the
  arguments should contain spaces.

  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...

  uri: the URI being authenticated.

  The AUTH command is followed by HTTP headers, one per line
  until a blank line is found. These should contain the
  authentication headers for the authentication protocol being
  used. Extraneous headers are ignored.

  Headers should be specified on one line, not 'wrapped' as is
  permissible in HTTP.

SET name value

  Sets a given value for the connection. Examples are listed below:

  Handler: The name of handler to use for authentication (as
  		configured in httpauthd.conf).

  Domain: The domains for digest authentication.

QUIT

  This closes the connection to the daemon.



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)

  202 Accepted

  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" ...