

                   Mod_Auth_External version 2.0.1

   Origional Coder: Nathan Neulinger <nneul@umr.edu>
Current Maintainer: Tyler Allison <allison@nas.nasa.gov>
  Development Team:
		    allison@nas.nasa.gov
		    nneul@umr.edu
	            br@ota.fr.socgen.com

Add to Configuration file:        
	Module external_auth_module    mod_auth_external.o

Add to server configuration file:
	AddExternalAuth <keyword> <path-to-authenticator>         
	AddExternalGroup <keyword> <path-to-group-checker>
        SetExternalAuthMethod <keyword> <method>
        SetExternalGroupMethod <keyword> <method>

The SetExternalMethod directive specifies how the data is to be passed to 
the external routine. There are currently three possible methods:

        environment - pass in environment variables (default - fully tested)
        function - handle as an internal function   (fully tested)
        pipe - pass name=value pairs via stdin      (in development)

For environment and pipe, the option specifies a path to a program to run. 
For function, the option specifies a special internal keyword that indicates
which internal function is to be used.

To Use an internal function use:
	AddExternalAuth <keyword> <function>:<dir/file>

Usage in auth config files:        
	AuthExternal <keyword>        
	AuthExternal afs
	AuthExternal RADIUS:/usr/local/raddb
	GroupExternal <keyword>        
	GroupExternal unix

AuthExternals are passed the userid and passwd in the USER and PASS environment
variables, and return a success code of 0 to indicate successful 
authentication. Non-zero result indicates either a failure to authenticate, or
a failure to execute the authenticator.

GroupExternals are passed the userid and desired group in the USER and GROUP
environment variables, and return a success code of 0 to indicate successful
authentication. Non-zero result indicates non-membersip or a failure to execute
the group checker. The need for this module arises from difficulties the 
origional author had linking apache with other libraries (such as AFS, and 
database access libs).


Using HARDCODE extension:

*** See the INSTALL file for how to impliment your own C function calls
instead of using a system() call.

*** Working functions are available for use, modification, or just as
examples in the examples directory.


                   Common questions and answers
                 --------------------------------

Q: Why add a hardcode extension?
A: System calls are usually a bad thing to do in a program, even worse when
   done on a server that is accessed by non-trusted users, and even worse when
   the password and username are passed via environment variables and in the
   clear.

Q: If system() is such a big risk why even use it?
A: Many developers can bang out a quick shell/perl script in very little
   time, in an attempt to see if the authentication is possible, or how well
   it will work. The system() call allows for new types of authentication to be
   quickly developed as needed. No exploits have been reported that use the
   system() call in mod_auth_external to gain access to the server. However,
   it is theoreticly possible, once an intruder has access, to gather
   password/username information by watching the environment variables. To
   my knowledge an exploit to do this has not been made public.

Q: Why accept the risk and use the system() call?
A: That is what makes this module so unique. If you do not know how to program
   in C, you can still offer your users at least some type of authentication, 
   and program in the language you know best. 

Q: What do I gain by porting my script to C?
A: By porting the script to C you gain multiple degrees of security,
   increased efficency, and you get added to our list of programmers!


             Known Hardcoded Functions Already Coded
           -------------------------------------------

mod_auth_external_radius.c  - A Radius client using code from the publicly
			      available Merit Radius source code.
			      by allison@nas.nasa.gov
mod_auth_external_sybase.c  - A function that queries a sybase database and
			      compares the passwords for said user.
			      by br@ota.fr.socgen.com 

** If you have functions you have coded and would like to add them to the
   examples directory on the next release please email them to
   allison@nas.nasa.gov and include a short description.



Comments/questions to allison@nas.nasa.gov
