README qmail Authentication
===========================


Scope:
------

This patch supports RFC 2554 "SMTP Service Extension for Authentication" for 

- qmail-smtpd (AUTH types LOGIN, PLAIN, and CRAM-MD5) and
- qmail-remote (AUTH types LOGIN, PLAIN).

Additionally, RFC 1870 is honoured ("SMTP Service Extension for Message Size Declaration").
For more technical details see: http://www.fehcom.de/qmail/docu/smtpauth.html.


History:
--------

This patch was based on Krzysztof Dabrowski's qmail-smtpd-auth-0.31 patch 
which itself uses "Mrs. Brisby's" initial code. 
Version 0.41 of this patch fixes the "CAPS-LOCK" typo announcing
'CRAM_MD5' instead of 'CRAM-MD5' (german keyboard) - tx to Mike Garrison.
Version 0.42 fixes the '421 unable to read controls (#4.3.0)' problem
(can't read control/morercpthosts.cdb) because FD 3 was already closed - tx Richard Lyons.
Version 0.43 fixes the ba64decode() failure in case CRAM_MD5 is not enabled - tx Vladimir Zidar.
Version 0.51 includes the evaluation of the 'Auth' and the 'Size' parameter in the 'Mail From:' command.
Version 0.52 uses DJB functions to copy FDs.
Version 0.56 corrects some minor mistakes displaying the 'Auth' userid.

Starting with version 0.60 the patch includes the qmail-smtp-auth-send enhancement
from Bjoern Kalkbrenner to support SMTP autentication for qmail-remote.

Version 0.60 includes SMTP authentication for qmail-remote.
Version 0.61 transmitts 'user' in Mail From: as xtext; flexible AUTH recognition.


Installation:
-------------

* Untar the source in the qmail-1.03 home directory.
* Run ./install_auth.
* Modify the compile time option "#define CRAM_MD5" to your needs.
* Re-make qmail.


Setup for qmail-smtpd:
----------------------

In order to use SMTP Authentication you have to use a 'Pluggable Authentication Module'
PAM to be called by qmail-smtpd; typically

	/var/qmail/bin/qmail-smtpd /bin/checkpassword true 2>&1

Since qmail-smtpd does not run as root, checkpassword has to be made sticky.
There is no need to include additionally the hostname in the call.
In order to compute the CRAM-MD5 challenge, qmail-smtpd uses the 'tcplocalhost' information.


Setup for qmail-remote:
-----------------------

See man page qmail-remote.

A control file control/authsenders has to be generated and populated accordingly.


Changes wrt. Krysztof Dabrowski's patch:
----------------------------------------

* Avoid the 'hostname' in the call of the PAM.
* Confirm to Dan Bernstein's checkpassword interface even for CRAM-MD5.
* Doesn't close FD 2; thus not inhibiting logging to STDERR.
* Fixed bugs in base64.c.
* Modified unconditional close of FD 3 in order to sustain reading of 'control/morecpthosts.cdb'.
* Evaluation of the (informational) Mail From: < > Auth=username.
* Additional support for the advertised "Size" via 'Mail From: <return-path> SIZE=123456780' (RFC 1870).


Changes wrt. Bjoern Kalkbrenner's patch:
----------------------------------------

* Included AUTH PLAIN support.
* Fixed wrong use of 'MAIL FROM: <return-path> AUTH=user'.
* Modular design.
* Renamed "smtproutes_user" to "authsenders".
* Added man page for qmail-remote including AUTH behaviour.
* Modified qmail-control man page to include "authsenders".
* Modified qmail-showctl to parse "authsenders".


Erwin Hoffmann - Cologne 2004-09-30 (www.fehcom.de)