head	1.6;
access;
symbols;
locks
	crosser:1.6; strict;
comment	@# @;


1.6
date	99.01.16.23.17.54;	author crosser;	state Exp;
branches;
next	1.5;

1.5
date	98.07.12.23.04.34;	author crosser;	state Exp;
branches;
next	1.4;

1.4
date	98.07.05.11.57.00;	author crosser;	state Exp;
branches;
next	1.3;

1.3
date	98.07.05.00.07.13;	author crosser;	state Exp;
branches;
next	1.2;

1.2
date	98.07.04.23.39.35;	author crosser;	state Exp;
branches;
next	1.1;

1.1
date	98.07.02.18.01.15;	author crosser;	state Exp;
branches;
next	;


desc
@README file
@


1.6
log
@Add RFC-formatted protocol description
@
text
@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)

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


1.5
log
@refer to "protocol.txt"
@
text
@d20 1
a20 1
is defined in a separate document "protocol.txt".
d45 1
d81 1
@


1.4
log
@clean up
@
text
@d20 1
a20 1
is defined in a separate document (to be written yet).
@


1.3
log
@Mention Perl module
@
text
@d7 2
d11 1
a11 1
suggested "whoson" internet protocol.  The protocol is supposed to be
d19 1
a19 1
"Received" header along with the source IP address.  The protocol itself
d34 8
a41 3
Then create configuration file "/etc/whoson.conf", using the example in
the source directory.  This file is used by both the server and the API
library.  See comments in the example file for more information.
d51 4
a54 4
user accounting information (e.g. userid).  In 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
executed, return code 0 or +1 means that the request was successfully
d58 4
a61 4
parameter.  In other cases, may or may not contain description of the
situation, e.g. the text "Access denied" or something like that.
If "retbuf" variable is NULL or "buflen" is zero, the buffer is not
filled.
d64 1
a64 1
(and wso_logout() if appropriate) and not check the result.  When
d66 1
a66 1
the database, retirn code +1 means that the address is not in the
a76 3
For 1.01: write *some* documentation and change copyright.  Make the
thing installable; include experimantal perl5 interface module.

d79 1
a79 2
Eugene Crosser <crosser@@average.org>
04 Jul 1998
@


1.2
log
@Rewritten
@
text
@d63 2
@


1.1
log
@Initial revision
@
text
@d1 63
d65 7
a71 11
	1. Use multiple file descriptors and select()/poll()
	2. Use Eric Young's lhash to speed up search
	3. Use congiguration file to restrict access
	4. Use configuration file to set parameters
	5. Allow connections over UDP and AF_UNIX

Done in version 0.05

	6. Allow connections with SSL (can wait...)
	7. Fix keepalive in the server (currently broken)
	8. Make API use keepalive connections when possible.
d74 1
@
