WHAT IS IT:
	Implementation of "whoson" protocol
AUTHOR:
	Eugene G. Crosser <crosser@average.org>
COPYRIGHT:
	Public domain
	(NOTE: files "lhash.c" and "lhash.h" are borrowed from SSLeay
	package and covered by different copyright)
HOMEPAGE:
	http://www.average.org/whoson/
FTP:
	ftp://ftp.average.org/pub/whoson/

DESCRIPTION:

This software is supposed to work as a "reference implementation" of the
suggested "whoson" internet protocol.  The protocol is expected to be
employed on "spam relay protected" mail servers to allow travelling
customers still send their email via the protected server.  For this, a
realtime database of "temporarily trusted" IP addresses is maintained by
a special daemon program.  The database may be filled by, e.g. POP/IMAP
servers, and used by SMTP server.  Another possible use of the protocol
is to have the database filled by RADIUS/TACACS server for all dialup
clients, and SMTP server using it to put the user identity into the
"Recieved" header along with the source IP address.  The protocol itself
is defined in a separate document "whoson.txt".

To compile the daemon and the API library, run

	./configure

and then

	make

To install the programs, the library and the API header file, run

	make install

Then edit the configuration file "/etc/whoson.conf" according to your
needs.  This file is used by both the server and the API library.  See
comments in the example file for more information.

Both the server and the API library functions report errors via
syslog(3); the server uses LOG_DAEMON facility, the API functions do not
use openlog(3) and thus do logging using the same facility as the
hosting application.

API functions (prototypes in the header file "whoson.h") are:

	char *wso_version(void);
	int wso_login(char *addr, char *name, char *retbuf, int buflen);
	int wso_logout(char *addr, char *retbuf, int buflen);
	int wso_query(char *addr, char *retbuf, int buflen);

"addr" is the IP address of the remote system specified as a character
string in dotted quad notation (e.g. "123.45.67.89"), and name is the
user accounting information (e.g. userid).  Upon completion, all
functions return integer return code, and the buffer is filled with
relevant information.  Return code -1 means that the request could not
be completed, return code 0 or +1 mean that the request was successfully
completed.  For wso_query() function, return code 0 means that the
requested address is present in the database.  In this case, retbuf may
contain the data that was passed to the wso_login() in the "name"
parameter.  In other cases, retbuf may or may not contain description of
the situation, e.g. the text "Access denied" or "Not found" or something
like that.  If "retbuf" parameter is NULL or "buflen" is zero, the
buffer is not filled.

Normally, when filling the database, you can blindly call wso_login()
(and wso_logout() if appropriate) and ignore the return code unless you
wish to perhaps log errors to indicate when the daemon is down.  When
querying the database, return code 0 means that the address is in the
database, return code +1 means that the address is not in the database,
and return code -1 means that the information is unavailable or
inaccessable.

There is a WHOSON subdirectory, it contains a Perl5 interface module.

==========================================================================
TO DO:

	6. Allow connections with SSL - can wait...

Start over TODO list:  any suggestions ? :-)

05 Jul 1998
mod: 17 Jan 1999
