WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING
===============================================================

Do not use this code.  The Postfix SASL support is based on the
Cyrus SASL library, which has not enough documentation about how
the software is supposed to work. It is not clear if the code is
safe enough for security-critical applications.

Postfix+SASL 1.5.5 appears to work on RedHat 6.1 (pwcheck_method
set to shadow or sasldb), Solaris 2.7 (pwcheck_method set to shadow
or sasldb), and FreeBSD 3.4 (pwcheck_method set to sasldb).  On
RedHat 6.1, SASL 1.5.5 insisted on write access to /etc/sasldb.

SASL is a lot of complex code. In a future version the Postfix SASL
code is likely to be put outside the SMTP server.

Introduction
============

The Postfix SASL support (RFC 2554) was originally implemented by
Till Franke of SuSE Rhein/Main AG.  The present code is a trimmed-down
version with only the bare necessities.  

When receiving mail, Postfix logs the client-provided username,
authentication method, and sender address to the maillog file, and
optionally grants mail access via the permit_sasl_authenticated
UCE restriction.  SASL authentication information is not passed on
via message headers or via SMTP.  It is no-one's business what
username and authentication method the poster was using in order
to access the mail server.

When sending mail, Postfix looks up the server hostname or destination
domain (the address remote part) in a table, and if a username/password
is found, it will use that username and password to authenticate
to the server.

Building the SASL library
=========================

Postfix appears to work with cyrus-sasl-1.5.5, which is available
from:

    ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/

IMPORTANT: if you install the Cyrus SASL libraries as per the default,
you will have to symlink /usr/lib/sasl -> /usr/local/lib/sasl.

Building Postfix with SASL authentication support
=================================================

To build Postfix with SASL authentication support, the following
assumes that the Cyrus SASL include files are in /usr/local/include,
and that the Cyrus SASL libraries are in /usr/local/lib.

On some systems this generates the necessary Makefile definitions:

    % make tidy # if you have left-over files from a previous build
    % make makefiles CCARGS=-DUSE_SASL_AUTH" -I/usr/local/include" \
	AUXLIBS="-L/usr/local/lib -lsasl"

On Solaris 2.x you need to specify run-time link information,
otherwise ld.so will not find the SASL shared library:

    % make tidy # if you have left-over files from a previous build
    % make makefiles CCARGS=-DUSE_SASL_AUTH" -I/usr/local/include" \
	AUXLIBS="-L/usr/local/lib -R/usr/local/lib -lsasl"

Enabling SASL authentication in the Postfix SMTP server
=======================================================

If you installed the Cyrus SASL libraries as per the default, you
will have to symlink /usr/lib/sasl -> /usr/local/lib/sasl.

See conf/sample-sasl.cf for examples. 

In order to enable SASL support in the SMTP server:

    /etc/postfix/main.cf:
	smtpd_sasl_auth_enable = yes

In order to allow mail relaying by authenticated clients:

    /etc/postfix/main.cf:
	smtpd_recipient_restrictions = 
	    permit_mynetworks permit_sasl_authenticated ...

In /usr/local/lib/sasl/smtpd.conf you need to specify how the server
should validate client passwords. For example:

    /usr/local/lib/sasl/smtpd.conf:
	pwcheck_method:  sasldb

This will use the SASL password file (default: /etc/sasldb), which
is maintained with the saslpasswd command (part of the Cyrus SASL
software). On some poorly-supported systems the saslpasswd command
needs to be run multiple times before it stops complaining.  The
Postfix SMTP server needs read access to the sasldb file - you may
have to play games with group access permissions. On RedHat 6.1,
SASL 1.5.5 insists on write access to /etc/sasldb.

Instead of the SASL-specific password file you can configure the
Postfix SMTP server to validate client passwords against the UNIX
shadow password file:

    /usr/local/lib/sasl/smtpd.conf:
	pwcheck_method:  shadow

However this requires that Postfix has read access to the UNIX shadow
password file, which is normally readable only by root.  Shadow
password support has been found to work for Solaris 2.7 and RedHat
6. 1 but not with freeBSD 3.4.

To run software chrooted with SASL support is an interesting exercise.
This is one of the many problems with the present SASL support.

To test the whole mess, connect to the SMTP server, and you should
be able to have a conversation like this:

    220 server.host.name ESMTP Postfix
    EHLO client.host.name
    250-server.host.name
    250-PIPELINING
    250-SIZE 10240000
    250-ETRN
    250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
    250 8BITMIME
    AUTH PLAIN dGVzdAB0ZXN0AHRlc3RwYXNz
    235 Authentication successful

Instead of dGVzdAB0ZXN0AHRlc3RwYXNz, specify the base64 encoded
form of username\0username\0password (the \0 is a null byte). The
example above is for a user named `test' with password `testpass'.

Enabling SASL authentication in the Postfix SMTP client
=======================================================

Turn on client-side SASL authentication, and specify a table with
per-host or per-destination username and password information.
Postfix first looks up the server hostname; if no entry is found,
then Postfix looks up the destination domain name (usually, the
remote part of an email address).

    /etc/postfix/main.cf:
	smtp_sasl_auth_enable = yes
	smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd

    /etc/postfix/sasl_passwd:
	foo.com		username:password
	bar.com		username

The SASL client password file is opened before the SMTP server
enters the optional chroot jail, so you can keep the file in
/etc/postfix.