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

This code is not blessed by Wietse.

People who go to the trouble of installing Postfix may have the
expectation that Postfix is more secure than some other mailers.

With SASL authentication enabled in the Postfix SMTP client and
SMTP server, Postfix becomes no more secure than other mail systems
that use the Cyrus SASL library.

The Cyrus SASL library has too little documentation about how the
software is supposed to work; and it is too much code to be used
in a security-sensitive program such as an SMTP client or server.

However, you are pretty much required to build with SASL support
if you are going to use the LMTP interface of the Cyrus delivery
agent.  This interface is much faster than forking a new process
for every message delivery.

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.
Note that this seems to be related to the auto_transition switch in
SASL. Note also that the Cyrus SASL documentation says that it is
pointless to enable that if you use "sasldb" for "pwcheck_method".

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.

Reportedly, Microsoft Internet Explorer version 5 requires the
non-standard SASL LOGIN authentication method. To enable this
authentication method, specify ``./configure --enable-login''.

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
=======================================================

See conf/sample-auth.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. 

In order to authenticate against the UNIX password database, try:

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

The pwcheck daemon is contained in the cyrus-sasl source tarball.

In order to authenticate against SASL's own password database:

    /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.

IMPORTANT: To get sasldb running, make sure that you set the SASL domain
(realm) to a fully qualified domain name. 

EXAMPLE: saslpasswd -c -u `postconf -h myhostname` exampleuser

To run software chrooted with SASL support is an interesting
exercise.  It probably is not worth the trouble.

Older Microsoft SMTP client software implements a non-standard 
version of the AUTH protocol syntax, and expects that the SMTP
server replies to EHLO with "250 AUTH=stuff" instead of "250 AUTH
stuff".  To accomodate such clients in addition to conformant
clients, set "broken_sasl_auth_clients = yes" in the main.cf file.

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

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

    220 server.host.tld ESMTP Postfix
    EHLO client.host.tld
    250-server.host.tld
    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'.

In order to generate base64 encoded authentication information you
can use one of the following commands:

    % printf 'username\0username\0password' | mmencode 

    % perl -MMIME::Base64 -e \
	'print encode_base64("username\0username\0password");'

MIME::Base64 is available from www.cpan.org.

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

Note: some SMTP servers support PLAIN or LOGIN authentication only.
By default, the Postfix SMTP client does not use authentication
methods that send plaintext passwords, and defers delivery with
the following error message:  "Authentication failed: cannot SASL
authenticate to server". To enable plaintext authentication specify,
for example:

    /etc/postfix/main.cf:
	smtp_sasl_security_options = 

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.

The Postfix SMTP client is backwards compatible with SMTP servers
that use the non-standard AUTH=stuff... syntax in response to the
EHLO command.

