$Id: README 1.12 Thu, 10 Jul 2003 20:42:07 +0200 warwick $

This program may be used to manage an /etc/passwd-like file of
username:crypted_password pairs, either from the command line
(chpwdfile) or using a cgi-bin version (chpwdfile-cgi).  This could be
useful when authenticating users for some service without giving them
system accounts.  We use this for the cyrus IMAP mail service in
conjunction with the PAM module pam_pwdfile by Charl Botha
(http://cpbotha.net/pam_pwdfile.html).

To compile as chpwdfile-cgi, you need the cgilib CGI wrapper library by
Martin Schulze (http://www.infodrom.north.de/cgilib/).


Operation
---------

chpwdfile uses the group ownership of the password file being modified
to determine whether the is operation is permitted.  If the executing
user is a member of the group that owns the file he is assumed to be
trusted and may make any modifications he likes.  If not, he is prompted
for an optional administrative password (defined in the password file
being operated on), success again being translated into trust.  If the
user (as defined by the USER environment variable) is attempting to
modify his own entry, he may authenticate with his existing password.
Only admin users may add and delete entries.  The UNIX root user (UID=0)
is always trusted.

Note that the password file must exist before chpwdfile is able to
operate on it.

Default values for various configurable parameters are defined at the
top of chpwdfile.h.  The config file may be specified on the command
line by the root user; all others must use the default
(/etc/chpwdfile.conf).  Minimum username and password lengths and the
password hashing algorithm (DES or MD5) may be specified on the command
line by admin users, which override the alternative defaults given in
the config file.  The admin password is that of the user defined by
ADMIN in chpwdfile.h, by default "admin".  DEFAULTOPERATION defines the
behaviour of chpwdfile if not given an operation on the command line.

The configuration file optionally defines the behaviour of chpwdfile
toward specific password files.  Each entry is started with
	file = /path/to/password/file
followed by username=keyword pairs
	minusername = <number>	# minimum username length
	minpassword = <number>	# minimum password length
	hashtype = [d|m]	# DES or MD5 passwords
and finished off with
	end
Repeat as necessary.  All whitespace is ignored, as is anything
following a hash (`#').

It is safe to change the default password crypt type for an existing
password file; new and modified entries will then be hashed in the new
format.

The cgi-bin version operates similarly with the following restriction
that only one configuration file (/etc/chpwdfile.conf) and one password
file (the first mentioned in /etc/chpwdfile.conf) are supported.  The
configuration file is required.  An example HTML form is included
(examples/demoform.html); read it to see how the program should be
called and what variables should be passed to it via the POST method.

Further information may be found in the man page.


File Permissions
----------------

The user running the program must have write permission to both the
password file and the directory it is in, as well as the configuration
file.  I recommend creating a password admin group (say `pwdfile'), then
making the chpwdfile setgid and the password file and its parent
directory writeable by that group.  Admin users are made members of this
group.  This has the disadvantage that the ownership of the file changes
when entries are deleted or modified, although the group ownership
remains the same because of the setgid, so it's not too serious.

File ownership may be preserved by making the binary setuid.  This will
probably also be necessary if you want to maintain different password
files being administered by different groups of users.  As far as I can
tell from chown(2) (I haven't tested it) the setuid does not have to be
to root, as long as the user whose ID is set is a member of all the
relevant groups.

-----

This code has been written, tested and used on a Debian GNU/Linux
system.  It apparently also works on FreeBSD.

Many thanks to Tobias Richter for his comments and suggestions, not to
mention being brave enough to use chpwdfile.  Also to MJ Turner for
giving me a project.

Thanks to Martin Dvorak for providing the -s switch that will allow the
program to read from STDIN (useful in scripts), e.g.
    echo $GENERATEDPASSWORD | pwadd -f /etc/ftppasswd -s someuser

Yet more thanks, this time to Mark Valiukas for making the beast compile
with GCC 3.3 (but multi-line printf()'s are just so convenient...).

You can obtain the most recent version of this code from
	ftp://eclipse.che.uct.ac.za/chpwdfile/

--
Warwick Duncan <warwick@chemeng.uct.ac.za>
