rework documentationv0.100

remove stuff in contrib, it is outdated or explained in the service's
documentation

5 files changed, 45 insertions, 197 deletions

diff --git a/INSTALL b/INSTALL
index 5fe4680..80846dd 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,38 +1,7 @@
-INSTALL for pam_pwdfile PAM module - Charl P. Botha <cpbotha@ieee.org>
----------------------------------------------------------------------------
-
-This file is the quick and dirty on how to get pam_pwdfile compiled on your
-system.  As per usual, I can not be held responsible for the results of the
-application of this information.
-
-1. Get the Linux PAM source code tarball.  Currently, this is at:
-http://www.us.kernel.org/pub/linux/libs/pam/pre/library/Linux-PAM-0.75.tar.bz2
-
-2. Extract the tarball somewhere convenient:
-bunzip2 -c Linux-PAM-0.75.tar.bz2 | tar -xvf -
-
-3. Prepare pam_pwdfile
-cd Linux-PAM-0.75/modules
-tar -xzvf /where/you/put/it/pam_pwdfile-x.y.tar.gz
-cd ..
-(x.y represents the pam_pwdfile version, e.g. 0.7)
-
-4. Prepare Linux-PAM
-rm default.defs
-ln -s defs/whatever.defs default.defs (on my system whatever == debian)
-
-5. in Linux-PAM-0.75/ do:
-   make all
-   NOTE: if you only need pam_pwdfile and some of the other modules are
-         causing you problems during compilation, go and delete them (i.e.
-	 delete the whole module dir, e.g. rm -rf modules/pam_pwdb) and then
-	 restart make all in the top level directory.
-	 
-6. When you're done, there should be a pam_pwdfile.so in modules/pam_pwdfile;
-   copy this into your pam modules directory. (this is /lib/security/ on my
-   debian 2.2. system)
-   
-7. You should now be operational.  See the README for more info.
-
-Remember that pam_pwdfile is packaged as a .deb and is part of the official
-Debian distribution.
+* install needed packages (if not installed already):
+  * make
+  * C compiler (e.g. gcc or clang)
+  * libc development headers (package libc6-dev on Debian, glibc-headers on Hat)
+  * PAM development headers (package libpam-dev on Debian, pam-devel on Hat)
+* make
+* make install
diff --git a/README b/README
index 4f07913..568cf5a 100644
--- a/README
+++ b/README
@@ -1,53 +1,38 @@
-README for pam_pwdfile PAM module - Charl P. Botha <cpbotha@ieee.org>
----------------------------------------------------------------------------
-
-This pam module can be used for the authentication service only, in cases
-where one wants to use a different set of passwords than those in the main
-system password database.  E.g. in our case we have an imap server running,
-and prefer to keep the imap passwords different from the system passwords
-for security reasons.
-
-The /etc/pam.d/imap looks like this (e.g.)
-#%PAM-1.0
-auth       required	/lib/security/pam_pwdfile.so pwdfile /etc/imap.passwd
-account    required	/lib/security/pam_pwdb.so
-
-At the moment the only parameters that pam_pwdfile.so parses for is
-"pwdfile", followed by the name of the ASCII password database, as in the
-above example.  Also, thanks to Jacob Schroeder <jacob@quantec.de>,
-pam_pwdfile now supports password file locking.  Adding a "flock" parameter
-activates this feature: pam_pwdfile uses and honours flock() file locking on
-the specified password file.  Specifying "noflock" or no flock-type
-parameter at all deactivates this feature.
-
-Example:
-auth  required /lib/security/pam_pwdfile.so pwdfile /etc/blah.passwd flock
-
-Like other PAM modules, pam_pwdfile causes a 2 second delay when an
-incorrect password is supplied.  This is too discourage brute force testing;
-however, this behaviour can be disabled with a "nodelay" parameter.  Thanks
-to Ethan Benson for this patch.
-
-The ASCII password file is simply a list of lines, each looking like this:
-username:crypted_passwd[13] in the case of vanilla crypted passwords and
-username:crypted_passwd[34] in the case of MD5 crypted passwords.  The
-latter is thanks to Warwick Duncan <warwick@chemeng.uct.ac.za>.  pam_pwdfile
-also handles bigcrypt passwords.
-
-NOTES:
------
-
-* Also have a look at the files in the contrib subdirectory.
-  Especially if you're having trouble building paw_pwdfile, the
-  Makefile.standalone could be your new friend.
-
-* Warwick has also written a utility for managing the password files that
-pam_pwdfile uses.  The website has disappeared, but I've mirrored the
-source code here: http://cpbotha.net/files/mirror/chpwdfile-0.24.tar.gz
-
-* Note that we still expect users to have accounts in the usual place, as we
-make use of the pam_pwdb.so module for the account service.  This module is
-just so that one can have multiple sets of passwords for different services,
-e.g. with our /etc/imap.passwd.  It is however possible with certain
-applications patched for pam (Cyrus IMAP server e.g.) that one does not need
-the users to exist in the system database.
+This pam module provides the authentication service using an own set of user/password pairs.
+
+CONFIGURATION
+=============
+
+simple PAM config
+-----------------
+
+Just add/change the config file for service to contain the line:
+
+auth		required	pam_pwdfile.so pwdfile=/path/to/passwd_file
+
+If your service does more with PAM than auth there will be a fallback to the service "other".
+If that is not what you want, you can use pam_permit.so or pam_deny.so for that:
+
+account		required	pam_permit.so
+session		required	pam_permit.so
+password	required	pam_deny.so
+
+
+options
+-------
+
+* pwdfile=<file>
+* debug: produce a bit of debug output
+* nodelay: don't tell the PAM stack to cause a delay on auth failure
+* flock: use a shared (read) advisory lock on pwdfile, you should better move new versions into place instead
+* legacy_crypt: turns on bigcrypt and "broken md5_crypt", you will only need that if you use password hashes from another system that uses those algorithms
+
+
+PASSWORD FILE
+=============
+
+The password file basically looks like passwd(5): one line for each user with two or more colon-separated fields.
+First field contains the username, the second the crypt()ed password.
+Other field are optional.
+
+crypt()ed passwords in various formats can be generated with mkpasswd from the whois package.
diff --git a/contrib/README.txt b/contrib/README.txt
deleted file mode 100644
index 1c0f886..0000000
--- a/contrib/README.txt
+++ /dev/null
@@ -1,13 +0,0 @@
-* Makefile.standalone-0.95 and pam-pwdfile.spec were contributed by Jason F.
-  McBrayer <jason@xeran.com>.  You can use these for building RPMs of
-  pam_pwdfile; you should also be able to use the Makefile to build
-  pam_pwdfile on other platforms _without_ the Linux-PAM hierarchy.
-
-* warwick_duncan-cyrus_without_system_accounts.txt is a short explanation by
-  Warwick Duncan on how to get Cyrus IMAPD + pam_pwdfile to work WITHOUT
-  having to create system accounts for IMAPD users.
-  
-* Makefile.standalone was contributed by Gerald Richter and should be more
-  up to date than Makefile.standalone-0.95.  The primary difference is that
-  Gerald's Makefile also takes into account the new md5 code.
-
diff --git a/contrib/pam-pwdfile.spec b/contrib/pam-pwdfile.spec
deleted file mode 100644
index cbcd88a..0000000
--- a/contrib/pam-pwdfile.spec
+++ /dev/null
@@ -1,44 +0,0 @@
-%define nam pam-pwdfile
-%define ver 0.95
-%define prefix /usr
-%define docdir %{prefix}/doc/%{nam}-%{ver}
-
-%define installer /usr/bin/install
-
-Summary: A PAM module that allows users to authenticate on htpasswd-type files separate from /etc/passwd.
-Name: pam-pwdfile
-Version: %{ver}
-Release: 1
-Copyright: LGPL
-Group: System Environment/Base
-Source0: %{nam}-%{ver}.tar.gz
-Source1: pam-pwdfile-Makefile.standalone
-URL: http://cpbotha.net/pam_pwdfile.html
-Distribution: Xeran Internal Packages
-Vendor: Xeran Technologies
-Packager: Jason F. McBrayer <jason@xeran.com>
-BuildRoot:	/var/tmp/%{nam}-%{ver}-root
-BuildPrereq: pam
-Requires: pam
-
-%description
-This pam module can be used for the authentication service only, in cases
-where one wants to use a different set of passwords than those in the main
-system password database.  E.g. in our case we have an imap server running,
-and prefer to keep the imap passwords different from the system passwords
-for security reasons.
-
-%prep
-%setup
-cp $RPM_SOURCE_DIR/pam-pwdfile-Makefile.standalone $RPM_BUILD_DIR/%{nam}-%{ver}/Makefile.standalone
-
-%build
-make -f Makefile.standalone
-
-%install
-make -f Makefile.standalone PAM_LIB_DIR="$RPM_BUILD_ROOT/lib/security" install
-
-%files
-%attr(0755, root, root) /lib/security/pam_pwdfile.so
-%attr(-, root, root) %doc README
-%attr(-, root, root) %doc changelog
diff --git a/contrib/warwick_duncan-cyrus_without_system_accounts.txt b/contrib/warwick_duncan-cyrus_without_system_accounts.txt
deleted file mode 100644
index 0144af1..0000000
--- a/contrib/warwick_duncan-cyrus_without_system_accounts.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-On Tue, Jan 14, 2003 at 01:06:02AM +0100, Charl P. Botha wrote:
-[...]
-> ----- Forwarded message from Darren Gibbons -----
-[...]
->   It is however possible with certain applications patched for pam
->   (Cyrus IMAP server e.g.) that one does not need the users to
->   exist in the system database.
-[...]
-
-I've got it working with cyrus 2.0 and 2.1, so I'll give some pointers
-on both.  When I say `cyrus x' I mean cyrus imapd version x and
-whichever version of sasl you need with it.
-
-Cyrus 2.0
----------
-
-- sasl must be configured with `--with-pam --enable-plain'; it doesn't
-  hurt to add `--disable cram --disable-digest'
-- imapd must be configured with `--with-auth=unix' (sounds like you got
-  that right)
-- in imapd.conf you need the line
-	sasl_pwcheck_method: PAM
-- in /etc/pam.d/imap (on FreeBSD I believe you use /etc/pam.conf, but
-  the idea is similar) you need
-  	auth  required  pam_pwdfile.so pwdfile /path/to/passwordfile
-	account  required  pam_permit.so
-- make sure your password file is readable by user cyrus
-
-The idea of all this is to use the SASL PLAIN mechanism to get the
-password in plaintext and then get SASL to leave the authentication to
-PAM, which will use pam_pwdfile.
-
-Cyrus 2.1
----------
-
-- same as above, but different ;) in the details
-- sasl must be configured with `--with-pam --with-saslauthd
-  --enable-plain' and I disable the rest (checkapop, digest, otp, krb4,
-  etc.)
-- imapd should be configured with `--with-auth=unix'
-- in imapd.conf you need the line
-	sasl_pwcheck_method: saslauthd
-- start up saslauthd with `saslauthd -a pam'
-- you need the /etc/pam.d/imap as above, as well as (an identical)
-  /etc/pam.d/sieve if you use timsieved
-
-I think that about covers it.  One tricky bit with SASL is to get the
-right mechanisms advertised; I do this by only compiling in support for
-PLAIN and LOGIN.  If the rest don't exist they can't cause problems.