

                   Mod_Auth_External version 2.1.2

     Original Coder: Nathan Neulinger <nneul@umr.edu>
Previous Maintainer: Tyler Allison <allison@nas.nasa.gov>
 Current Maintainer: Jan Wolter <janc@cyberspace.org>
   Development Team:
		    allison@nas.nasa.gov
		    nneul@umr.edu
	            br@ota.fr.socgen.com
	            janc@cyberspace.org

Introduction:
-------------

Mod_Auth_External is an Apache module used for authentication.  The Apache
HTTP Daemon can be configured to require users to supply logins and passwords
before accessing pages in some directories.  Authentication is the process
of checking if the password given is correct for a user.  Apache has
standard modules for authenticating out of several different kinds of
databases.  Mod_Auth_External is a flexible tool for creating authentication
systems based on other databases.

Mod_Auth_External can be used in either of two somewhat divergent ways:

 External Authentication:

    When a user supplies a login and password, mod_auth_external runs a
    program you write, passing it the login and password.  Your program
    does whatever checking and logging it needs to, and then returns a
    Accept/Reject flag to Apache.

    This is slower than doing the authentication internally because it
    has the overhead of launching an external program for each authentication.
    However, there are at least two situations where it is very useful:

      - Rapid prototyping.  The external authentication program can be
        a shell script or perl program.  It can be written without knowing
        much about building Apache modules.  Bugs in it will not endanger
        the overall integrity of the Apache server.

      - Access restrictions.  There are situations where you do not want to
        make your user database readable to the user-id that Apache runs
        under.  In these cases the external authentication program can be
        an suid program that has access to databases Apache cannot access.
        For example, if you want to authentication out of a Unix shadow
        password database, and you aren't foolish enough to run Apache
        as root, a carefully written suid-root external authentication
        program can do the job for you.

    An example external authentication program for authenticating out of
    a Unix shadow password database is included in this distribution.

 Hardcoded Authentication:

    Some hooks have been inserted into mod_auth_external to make it easy
    to replace the call to the external authentication program with a
    call to a hardcoded internal authentication routine that you write.

    This is sort of a half-way measure to just writing your own Apache
    module from scratch, allowing you to use some of the logic from
    mod_auth_external.

    Example functions for authenticating out of a RADIUS server or Sybase
    database are included in this distribution.

Compatibility:
--------------

The current version of mod_auth_external is designed for use with Apache 1.3.
We have no idea if it will still work with Apache 1.2.

We also have no idea if this will work under Windows, but we rather doubt it.
It's quite possible that it could be extended to Windows without that much
difficulty by making more use of the existing Apache functions for running
CGI's in that environment.

Security Considerations:
------------------------

By default, mod_auth_external passes the user's login and password to the
external authentication program by putting them in environment variables
called USER and PASS.  On some versions of Unix (including SunOS and IRIX)
any user logged onto the server can see these values by doing a "ps -e"
command.  This would obviously be a problem if there are ever untrusted users
on your server.  Other versions of Unix (including Linux) restrict "ps -e" so
you can only see your own processes, but this may still be a problem if
untrusted people can put CGI programs on your server, since those may run
as the same user as your authentication program does.  Some versions of
Unix (including Solaris) don't have a "ps -e" command at all, so this problem
doesn't exist.

However, mod_auth_external can easily be configured to pass the user's login
and password program to the external authentication program via a pipe.  If
this is done (and it should be), then there should be no problems on any
version of Unix.

Use of this module requires development of an external authentication program
or a hardcoded internal function.  There are more ways to screw up your
security by doing those badly than we could possibly list.  A few things to
keep in mind:

  - Don't make any assumptions about the length of the login names and
    passwords given by the user.  I *think* it is impossible for them to
    be longer than 8192 characters, but don't take my word on it.  Check
    for buffer overflows.

  - Think about locking.  It is possible to get lots of hits on your website
    very fast, so there may be many programs simultaneously reading your
    database, plus updates of your database may be going on at the same time.
    Probably some form of locking is needed to make all this work right.

  - Think about core dumps.  On some systems core dump file can be publicly
    readable.  A core dump from your authenticator is likely to contain
    the user's plain text password, and may include large chunks of your
    password database that may have been in buffers.

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

Q: Aren't system() calls a security risk under Unix?
A: Only if unchecked user input is included in the command, if full paths
   aren't given on commands, or if the user can fiddle with certain specific
   environment variables before the call gets executed.  None of these were
   possible problems even in older versions of mod_auth_external.  For
   efficiency reasons, versions of mod_auth_external since 2.1.0 don't even
   do system() calls, so the issue is even more moot than before.

Q: Why add a hardcode extension?
A: Speed.  The overhead of launching a external authentication program is
   significant.


Example External Authentication Routines in this Distribution:
--------------------------------------------------------------

 test/
    Several small dummy external authentication programs written in Perl.
    This are meant only for testing of mod_auth_external.  They accept
    any user whose password and login name are identical.  They write
    lots of debugging info to the error_log file.

    Author and Maintainer:  Jan Wolter <janc@cyberspace.org>

 pwauth/
    A setuid-root external authentication program for securely authenticating
    out of most flavors of Unix shadow password files.  Supports some Unix
    lastlog and faillog options.

    Author and Maintainer:  Jan Wolter <janc@cyberspace.org>


Example Hardcoded Internal Authentication Routines in this Distribution:
------------------------------------------------------------------------

 radius/
    A Radius client using code from the publicly available Merit Radius
    source code.

    Author:  Tyler Allison <allison@nas.nasa.gov>
    Unmaintained.

 sybase/
    A function that queries a sybase database and compares the passwords
    for said user.

    Author:  <br@ota.fr.socgen.com>
    Unmaintained.

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
janc@cyberspace.org and include a short description.
