
Contents:
* Installation Instructions
* Module Configuration
* Credential Formatmo   

Installation Instructions
*************************

1. Copy the 'mod_auth_cookie_mysql.c' file into the src/modules/extra
directory in your Apache distribution.

2. Run 'configure' with the following options and variable settings:
        
        LDFLAGS="-L/usr/local/mysql/lib/" LIBS="-lz -lmysqlclient" INCLUDES="-I/usr/local/mysql/include" ./configure --add-module=src/modules/extra/mod_auth_cookie_mysql.c

plus whatever you normally add.    Probably the easy way to do this is
to add these settings to the 'config.status' file and then use

        sh config.status

3. Rebuild the httpd.  Run './httpd -l' (list compiled-in modules) and
make sure that 'mod_auth_cookie_mysql.c' apears in the output.

4. Install new httpd.


================================================================

Module Configuration
********************

To protect a directory with mod_auth_cookie_mysql, put these lines into
the .htaccess file:

        AuthType MySQL_Cookie
        MySQL_Cookie_Auth_CookieName thecookie
        MySQL_Cookie_Auth_DBName test
        MySQL_Cookie_Auth_FailureURL /cgi-bin/putcookie.cgi
        require valid-user

Or put them in your httpd.conf file.  You can enclose these directives
inside of <Files ...> ... </Files>, <Directory ...> ... </Directory>,
<Location ...> ... </Location>, or <Limit ...> ... </Limit> as you
would expect.

You can replace 'require valid-user' with 'require user fred bill
jake' to allow access only for users fred, bill, and jake.
'mod_auth_cookie_mysql' does not presently support any other 'require'
directives; if any are present, it will ignore them.  But if you want
new ones, such as 'require group', for example, I can put them in
quickly.

'mod_auth_cookie_mysql' supports the following directives in the
httpd.conf or .htaccess file:

    MySQL_Cookie_Auth_CookieName the-cookie-name
    (required)

        This is the name of the cookie that will be examined for the
        user's credential.

    MySQL_Cookie_Auth_FailureURL (URL for failure page)
    (required)

        If the user has no credentials, or invalid credentials, they
        will be redirected to this URL.

        (Actually, if the FailureURL is U, they will be redirected to 
          "U?return=R&cookie=C", where R is the URL they were
          requesting access to, and C is the CookieName.)

    MySQL_Cookie_Auth_ExpireTime 
    (optional; defaults to infinity)

        Credentials older than this many seconds are ignored.  An
        expire time of '0' is the default and is interpreted as infinity.
    
    MySQL_Cookie_Auth_MatchIP 
    (optional; defaults to 'off')

        If 'on', the user's remote address will be checked against the
        address stored in the credential.  If the addresses don't
        match, the credential will be ignored.

    MySQL_Cookie_Auth_DBName 
    (required)

        Name of the MySQL database in which usernames and passwords
        are stored.

    MySQL_Cookie_Auth_DBHost
    (optional; defaults to 'localhost')

        Name of the host on which the MySQL server resides.

    MySQL_Cookie_Auth_DBTable
    (optional; defaults to 'auth')

        Name of the table in which the usernames and passwords are stored.

    MySQL_Cookie_Auth_DBUser
    (optional; defaults to none)

        Name of the database user to access the database as.
        
    MySQL_Cookie_Auth_DBPassword
    (optional; defaults to none)

        Database password for user DBUser.

    MySQL_Cookie_Auth_DBUsernameField
    (optional; defaults to 'user')

        Name of the table field in which usernames are stored.

    MySQL_Cookie_Auth_DBPasswordField
    (optional; defaults to 'password')

        Name of the table field in which passwords are stored.

================================================================

Credential Format
*****************

The credential is a cookie with four fields:

        IIIITTTTHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHUSERNAME 

1. IIII = 4-byte IP address; used only if MatchIP option is enabled
2. TTTT = 4-byte creation time
3. HH...HH = 16-byte MD5 checksum, encoded as 32 hex digits
4. USERNAME = variable length username

The module checks the credential for validity as follows:

1. If the ExpireTime option is nonzero, then TTTT + ExpireTime must be
   less than or equal to the current time.  If not, the credential is
   rejected. 

2. If the MatchIP option is enabled, then IIII must match the client
   connection's IP address.  If not, the credential is rejected.

3. The USERNAME is looked up in the specified MySQL database, and the
   corresponding password is extracted from the database.  If the
   username does not appear in the table, or if it appears more than
   once, the credential is rejected.

4. The MD5 checksum of (USERNAME, IIII, TTTT, password) is computed.
   It must match HH...HH.  If not, the credential is rejected.

5. If the credential is rejected, the client is redirected to the
   FailureURL.  If not, the module instructs Apache to allow access to
   the protected resource.


To manufacture a credential, prompt the user for username and
password.  Construct the MD5 checksum of the username, the client's IP
address, the current time, and the password.  Throw the password away.
Format the username, address, time, and checksum as above.  This is
the credential.  If the user-supplied password was incorect, the
checksum will also be incorrect, and 'mod_auth_cookie_mysql' will
reject the credential when it looks up the password.  The program
'putcookie.cgi' demonstrates how to do this.

