 README FOR THE QPASSWD PACKAGE
================================

The qpasswd tools are a collection of various tools (checkpasswd, checkqpasswd,
multicheckpw, and others). They are meant for use with checkpassword-compatible
authentication programs like qmail-popup and qmail-smtpd. Currently, the
following auth mechanism are supported: plain, login, apop, cram-md5, cram-sha1,
cram-ripemd, and digest-md5. No special libraries are required, and it compiles
against dietlibc.


We have currently 5 tools:

1. multicheckpw
   - with this program, you can use multiple program, which use the
     checkpassword interface

2. checkqpasswd
   - with this program, you can authenticate virtual users, which don't
     really exist on your system
   - authentication is done against the /etc/qpasswd database, which
     consists on 'user:homedir' pairs ... the clean text password is
     saved in the .qpasswd in the home directory of the user
   - see qpasswd.5 + checkqpasswd.8 for more information about this

3. checkpasswd
   - with this program, you can authenticate users against the /etc/passwd
     database

4. qpasswd
   - with this program, you can manage the accounts of the virtual users of
     the /etc/qpasswd database (xxx: not ready yet!)

5. test-cases
   - during compilation this program is executed for testing the correctness of
     the crypto functions: hmac_md5 + hmac_ripemd + hmac_sha1

/TR 2004-04-08

last change: 2015-03-25 @ 12:53

ENVIRON

 ENVIRONMENT VARIABLES FOR THE QPASSWD PACKAGE
===============================================


READFD (default: 3 - taken from params.h)
 - is used as the reading fd for multicheckpw, checkqpasswd, checkpasswd
 - checkpassword-compatible tools should always use fd 3
 - this variable is used for testing, with READFD=0


FD_QPASSWD       (default: 20 - taken from params.h)
FD_CHECKPASSWD   (default: 21 - taken from params.h)
FD_CHECKQPASSWD  (default: 22 - taken from params.h)
FD_MULTICHECKPW  (default: 23 - taken from params.h)
 - when ERRFD's is enabled in params.h, you can set with these variables
   the logging file descriptor for each program


LOG_VHOME_FOUND (logging for checkqpasswd)
 - if set to sth., the string 'virtual home found: /some/path' is logged


SASL (logging for checkqpasswd)
 - if set, checkqpasswd will only authenticate against this type
 - the values can be:
   - PLAIN (also used for AUTH LOGIN and pop3 USER/PASS)
   - APOP (only for pop3, apop style pass/greeting hash)
   - CRAM-MD5
   - CRAM-SHA1
   - CRAM-RIPEMD
   - DIGEST-MD5
 - the case is ignored


TCPREMOTEIP and TCPREMOTEPORT
 - is used for creating the .lastpop file
 - see tcp-environ(5)


/TR 2004-01-13

last change: 2015-03-25 @ 12:53

CHANGES

0.5
- updated documentation
- added environment variable $SASL check in checkqpasswd
  - if we set it to some authentication method, only this method is tried,
    instead of all (will save some time on servers)
- added die_shell.c
- fixed THANKS, tw=80 now
- added case_diffb.c - for reading the SASL environment variable

0.4
- changed docs
- updated copyright notice @ m_multicheckpw.c

0.3
- again, fixed serveral typos in the documentation
- added a docs/README
- fixed digest-md5:
  - for smtpd it writes the digest response just to a file
  - for qmail-popup it writes the filename to a special ENV variable,
    which is read by qmail-pop3d ...

0.2
- oh no: corrected testvalues @ params.h, alls FD's were set to 1
- corrected some typos in the manpages
- security: install multicheckpw with 4510 perms, not 4511!

0.1
- first version
- lastpop stuff isn't ready :(

last change: 2015-03-25 @ 12:53

THANKS

Thanks to lots of people for success and failure reports, code, ideas,
and documentation.


AAH =  Andreas Aardal Hanssen <andreaha-qmail@lexx.infeline.org>
       - multi password checking

FL  =  Felix von Leitner <der@fefe.de>
       - dietlibc

DJB =  D. J. Bernstein <djb@pobox.com>
       - qmail @ all

KB  =  Krzysztof Dabrowski
       - wide aviable smtp-auth patch
       - cmd5checkpw checkpassword

SK  =  Sascha Klockow <der@dreamz-box.de>
       - for testing

last change: 2015-03-25 @ 12:53

TODO

- begin qpasswd

- .lastpop verification

/TR 2004-01-15

last change: 2015-03-25 @ 12:53

INSTALL

 INSTALL
=========

1. Possibly, edit the Makefile (compilertuning etc)
	$ vi Makefile

2. Read the comments in params.h, and edit the #define's for your needs:
	$ vi params.h

3. Build it:
	$ make it

4. Install the binaries and the manpages:
	# make setup check

5. Read the documentation @ docs!
	$ for i in docs/*; do less $i;done

5. Read the manpages @ man!
	$ for i in man/*; do man $i; done

6. Edit your /service/qmail-*/run or /etc/minit/qmail-*/run files ...

last change: 2015-03-25 @ 12:53