/*
    WNDigest
    Version 0.6
    
    Copyright (C) 1996  <by John Franks>

    This program is free software; you can redistribute it and/or modify
    it in any way you choose.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
*/

WN-Digest is an implementation of the proposed Digest authentication
method for HTTP. It was originally called SimpleMD5; hence the name.
The specification for the proposal can be found at

	http://hopf.math.nwu.edu/digestauth/

Some familiarity with this spec will be useful in understanding what
follows.  WN-Digest is an experimental implementation of Digest
Authentication intended for use with the WN http server (see
http://hopf.math.nwu.edu/).

This implementation has several interesting features which are not
part of the specification but are made possible by the flexibility of
the proposed method.  

     1. Timestamps:  The maintainer can set the time period for which
     authentication granted the client is valid.  After this time period
     the client will have to re-authenticate.   The time period can be
     set to any number of seconds (or be unlimited) and is accurate to
     within 1% of the specified value.  The timestamp is encoded in the
     "nonce" header field (see the specification).

2. IP address stamps: The IP address of the client (or the IP address
of the client's proxy) is encoded in the "opaque" header field.  This
means that a replay attack would have to spoof the server with a false
IP address.

The wndigest program is designed as an authorization module for use
with the WN http server, but it may be able to be modified for use
with other servers.


RUNNING WITH WN
---------------

Read the WN manual section on authentication.

To compile the wndigest authentication module first do 

	make md5

to produce the md5 digest program.  Then test the perl script rand
by executing it with "perl rand".  It should produce something like

	#define RANDOMKEY "749ff050b4e0fcc8efa1f3c7d7342d67"

This is not the key that will be used; it is only a test.  Next do a
"make all" which will produce the wndigest module.

If you put the digestauth directory in your data hierarchy and run wndex
on it, it should work. Look at the example index file in this directory.
It should contain: 

	Authorization-realm=testrealm@yourhost.com
	Authorization-module=wndigest -t 600 -d /digestauth -p wnpasswd
	Authorization-type=Digest

The first line specifies realm.  The module line gives the location of
wndigest relative to the data root (you can use a complete path or
start relative to the WN root directory using '~').  The arg -t 600
means authenication is valid for 600 seconds or 10 mins. The domain is
"/digestauth" and the password file is wnpasswd in the current
directory.

The password file has lines of the form 

	username:Encrypted-realm-user-password

You can produce an appropriate entry with the perl program md5passwd
which works like the mkpasswd which comes with the WN distribution.
This perl program calls the public domain program md5 to do the MD5
hashing (and it assumes this program is in the current directory).
The wndigest module for use with WN is self contained) though it uses
the public domain code in the file md5c.c from RSA.

John Franks




