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://whoson.sourceforge.net/

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 traveling
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
"Received" 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

If you got the source by CVS see notes at the bottom of this file.

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

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

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

Fresh versions, if any, and related information are available from the
project home page at

	http://whoson.sourceforge.net/

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

	- Allow connections with SSL - can wait...
	- something, probably the 'whoson' client, doesn't check for
	  additional parameters on a "login" command -- too many params
	  should result in a command-line syntax error.

Start over TODO list:  any suggestions ? :-)

---
APPENDIX: Building from the source received by CVS.

You must have cvs, autoconf, automake and libtool installed on your
system.

$ cd $your_src_dir
$ cvs -d :pserver:anonymous@cvs.whoson.sourceforge.net:/cvsroot/whoson login
Password:
   ( -- just press "Enter" for empty password)
$ cvs -d :pserver:anonymous@cvs.whoson.sourceforge.net:/cvsroot/whoson checkout whoson
$ cd whoson
$ aclocal
$ autoheader
$ automake --add-missing
$ autoconf
$ ./configure [various options ...]
$ make

05 Jul 1998
mod: 06 Oct 1999
mod: 14 Aug 2003
mod: 26 Nov 2006
