 
mod_auth_msql: authentication

Rob McCool & Brian Behlendorf.
Adapted to Shambhala by rst.

Addapted for use with the mSQL database
(see ftp:/ftp.bond.edu.au/pub/Minerva/mSQL)

Version 1.0 May 1996 - Blame: Dirk.vanGulik jrc.it.

A (sometimes more up to date) version of the documentation
can be found at the http://www.apache.org site or at 
http://me-www.jrc.it/~dirkx/mod_auth_msql.html.

Outline:
This module allows access control using the public domain
mSQL database; a fast but limted SQL engine which can be
contacted over an internal unix domain protocol as well as
over normal inter-machine tcp/ip socket communication.
An example table could be:

create table user_records (
	  User_id  char(32) primary key,
	  Cpasswd  char(32),
	[ Xgroup   char(32) ]
	  ) \g

The user_id can be as long as desired; however some of the
popular web browsers truncate, or stop the user from entering
names longer than 32 characters. Furthermore the 'crypt' function
on your platform might impose further limits. Also use of
the 'require users uid [uid..]' directive in the access.conf file,
where the user ids are separated by spaces can possibly prohibit the
use of spaces in your user-names. Also, not the MAX_FIELD_LEN define
somewhere below.

To use the above, the following example could be in your access.conf
file. Also there is a more elaborate description afther this example.

<directory /web/docs/private>

 Auth_MSQLhost localhost
or
 Auth_MSQLhost datab.machine.your.org

 		        If this directive is ommited, or set to
			localhost, the machine on which apache
			runs is assumed, and the faster /dev/msql
			communication channel will be used. Otherwise
			it is the machine to contact by tcp/ip.

Auth_MSQLdatabase    www

                     The name of the database on the above machine,
			which contains *both* the tables for group and
			for user/passwords. Currently it is not possible
			to have these split over two databases. Make
			sure that the msql.acl (access control file) of
			mSQL does indeed allow the effective uid of the
			web server read access to this database. Check the
			httpd.conf file for this uid.

Auth_MSQLpwd_table   user_records

                     Here the table which contain the uid/password combination
			is specified.

Auth_MSQLuid_field	User_id
Auth_MSQLpwd_field   Cpasswd

			These two directive specify the field names in the 'user_record'
			table. If this module is compiled with the BACKWARD_VITEK
			compatibility switch, the defaults 'user' and 'password' are
			assumed if you do not specify them. Currently the user_id field
			*MUST* be a primary key or one must ensure that each user only
			occurs *once* in the table. If a UID occurs twice access is
			denied by default.

Auth_MSQLgrp_table   user_records
Auth_MSQLgrp_field	Xgroup

                     Optionaly one can also specify a table which contains the
			user/group combinations. This can be the same table which
			also contains the username/password combinations. However
			if a user belongs to two or more groups, one will have to
 		        use a differt table with multiple entries.

Auth_MSQL_nopasswd	        off
Auth_MSQL_Authorative        on
Auth_MSQL_EncryptedPasswords on

                     These three optional fields (all set to the sensible defaults,
			so you really do not have to enter them) are described in more
			detail below. If you choose to set these to any other values than
			the above be very sure you understand the security implications and
			do verify that apache does what you exect it to do.

AuthName 		example mSQL realm
AuthType		basic

                     Normal apache/ncsa tokens for access control

<limit get post head>
  order deny,allow
  allow from all

  require valid-user
   	     	       'valid-user'; allow in any user which has a valid uid/passwd
   	     	       pair in the above pwd_table.
or
  require user smith jones
  	     	      Limit access to users who have a valid uid/passwd pair in the
		      above pwd_table AND whose uid is 'smith' or 'jones'. Do note that
		      the uid's are separated by 'spaces' for historic (ncsa) reasons.
		      So allowing uids with spaces might cause problems.

  require group has_paid
  	     	      Optionally also ensure that the uid has the value 'has_paid' in the group
		      field in the group table.
  </limit>
</directory>

End of the example

- full description of all tokens: -

Directives:

Auth_MSQLhost   	Hostname of the machine running
		   	the mSQL demon. The effective uid
		   	of the server should be allowed
		   	access. If not given, or if it is
		   	the magic name 'localhost', it is
		   	passed to the mSQL libary as a null
	  	 	pointer. This effectively forces it
		   	to use /dev/msql rather than the
		   	(slower) socket communication.

Auth_MSQLdatabase	Name of the database in which the following
			table(s) are contained.

Auth_MSQLpwd_table	Contains at least the fields with the
			username and the (encrypted) password. Each
			uid should only occur once in this table and
			for performance reasons should be a primary key.
			Normally this table is compulsory, but it is
			possible to use a fall-through to other methods
			and use the mSQL module for group control only;
			see the Authorative directive below.

Auth_MSQLgrp_table	Contains at least the fields with the
			username and the groupname. A user which
			is in multiple groups has therefore
			multiple entries; this might be some per-
			formance problems associated with this; and one
			might consider to have separate tables for each
			group (rather than all groups in one table) if
			your directory structure allows for it.
			One only needs to specify this table when doing
			group control.

Auth_MSQLuid_field	Name of the field containing the username
Auth_MSQLpwd_field   Fieldname for the passwords
Auth_MSQLgrp_field	Fieldname for the groupname

                     Only the fields used need to be specified. When this
			module is compiled with the BACKWARD_VITEK option the
			uid and pwd field names default to 'user' and 'password'.

Auth_MSQL_nopasswd	<on|off>
			skip password comparison if passwd field is
			empty; i.e. allow 'any' password. This is off
			by default; thus to ensure that an empty field
			in the mSQL table does not allow people in by
			default with a random password.

Auth_MSQL_Authorative <on|off>
			default is 'on'. When set on, there is no
		     	fall through to other authorization methods. So if a
			user is not in the mSQL dbase table (and perhaps
		        not in the right group) or has the password wrong, then
                     he or she is denied access. When this directive is set to
			'off' control is passed on to any other authorization
			modules, such as the basic auth module wih the htpasswd
			file and or the unix-(g)dbm modules.
			The default is 'ON' to avoid nasty 'fall-through' sur-
			prizes. Do be sure you know what you decide to switch
			it off.

Auth_MSQL_EncryptedPasswords <on|off>
			default is on. When set on, the values in the
			pwd_field are assumed to be crypted using *your*
		        machines 'crypt' function; and the incoming password
		        is 'crypt'ed before comparison. When this function is
			off, the comparison is done directly with the plaintext
			entered password. (Yes; http-basic-auth does send the
			password as plaintext over the wire :-( ). The default
			is a sensible 'on', and I personally thing that it is
			a *very-bad-idea* to change this. However a multi
			vendor or international environment (which sometimes
			leads to different crypts functions) might force you to.

Dirk.vanGulik jrc.it; http://ewse.ceo.org; http://me-www.jrc.it/~dirkx
23 Nov 1995, 24 Feb 1996, 16 May 1996.
 
