********************
*** INTRODUCTION ***
********************

SMTP AUTH is the standard (RFC 2554) way of authenticating yourself to
an (E)SMTP server, usually in order to gain the right to relay.

qmail-smtpd doesn't have native support for SMTP AUTH.  smtp_auth adds
it on by acting as a proxy, intercepting the SMTP AUTH command if it
is the first command sent.  If the user authenticates succesfully,
qmail-smtpd is fired up with the RELAYCLIENT environment variable set,
giving the user permission to relay.  If authentication fails, or is
not attempted, qmail-smtpd is fired up with the RELAYCLIENT
environment variable unchanged.

This differs from the approach taken by Mrs. Brisby at:

    http://www.nimh.org/code/

because it does not involve modifying qmail or qmail-smtpd at all, and
instead uses the qmail-smtpd included with qmail.  It also doesn't
require a setuid checkpassword.

It differs from the approach taken by Bruce Guenter's mailfront at:

    http://untroubled.org/mailfront/

because it uses the standard qmail-smtpd.

It's dubious whether either of these differences offer any real
advantage; I was interested in playing around with ways to extend
qmail-smtpd without modifying it, and this is the result of that.

********************
*** INSTRUCTIONS ***
********************

WARNING: These are not for the faint-hearted.  They are confusing and
may not work for you.  This is still experimental; if you get stuck,
email me at <sgifford@suspectclass.com>.

An example run file is available in smtp-auth-run.

1. Download and install qmail according to Life with qmail.

2. Download and unpack checkpassword.  Rename checkpassword-0.81 to
   checkpassword-0.81_nosu.  Apply the patch checkpassword0.81-nosu.patch
   to this copy of checkpassword, then install.  It will create a copy
   of checkpassword which authenticates the user, but doesn't switch
   to them afterwards.

3. Download smtp_auth, and install it in /usr/local/bin.

4. Download smtpproxy, and install it in /usr/local/bin.

5. Modify your run file for qmail-smtpd to set the environment
   variable GREETING to contain what smtp_auth should give as the
   SMTP greeting line, including the trailing newline.  I use:

     GREETING="220 accept.mailweb.flinthomes.net ESMTP
     "

6. Modify your run file for qmail-smtpd to set the environment
   variable EHLORESP to contain what smtp_auth should give as the
   response to an an EHLO command.  Don't include anything about SMTP
   AUTH; this will be added automatically.  Make all of your response
   lines continuation lines (with a 4th character of -); the SMTP AUTH
   line will be added last.  I use:

     EHLORESP="250-accept.mailweb.flinthomes.net
     250-PIPELINING
     250-8BITMIME
     "

7. export both GREETING and EHLORESP.  I use:

      export GREETING EHLORESP

8. On the exec line, before qmail-smtpd, add:

      smtp_auth \
        checkpassword_nosu \
        setuidgid qmaild \
        smtpproxy \                                                

   This runs the SMTP AUTH program and tells it to authenticate users
   with the checkpassword_nosu we built in Step 2.  When smtp_auth is
   done, it will run setuidgid qmaild to drop root privileges (which
   were required to do authentication), which will run smtpproxy.
   smtpproxy sends along any EHLO commands that have already been sent
   by the client, and hides any responses which have already been sent
   by the server; after that, it acts as a passthrough proxy.  It runs
   qmail-smtpd to provide the SMTP service.

************
*** BUGS ***
************

  * AUTH PLAIN is only supported if no other commands besides EHLO are
    sent before it.

  * This will degrade performance somewhat, since all commands are
    passed through smtpproxy.  This can't be fixed without a design
    change to qmail-smtpd.