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".
Later versions of the SASL 1.5.x series should also work.

Postfix+SASL 2.1.1 appears to work on Mandrake Linux 8.1 (pwcheck_method
set to saslauthd or auxprop).  Note that the 'auxprop' pwcheck_method
replaces the 'sasldb' method from SASL 1.5.x.  Postfix may need
write access to /etc/sasldb2 if you use the auto_transition feature,
or if you use an authentication mechanism such as OTP (one-time
passwords) that needs to update secrets in the database.

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.  Support for SASL version 2
was contributed by Jason Hoos.

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. The
people who need to know can find the information in the maillog file.

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 or cyrus-sasl-2.1.1, 
which are 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
for version 1.5.5 or /usr/lib/sasl2 -> /usr/local/lib/sasl2 for
version 2.1.1.

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

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:

(for SASL version 1.5.5):
    % 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"

(for SASL version 2.1.1):
    % make tidy # if you have left-over files from a previous build
    % make makefiles CCARGS="-DUSE_SASL_AUTH -I/usr/local/include/sasl" \
	AUXLIBS="-L/usr/local/lib -lsasl2"

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

(for SASL version 1.5.5):
    % 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"

(for SASL version 2.1.1):
    % make tidy # if you have left-over files from a previous build
    % make makefiles CCARGS="-DUSE_SASL_AUTH -I/usr/local/include/sasl" \
	AUXLIBS="-L/usr/local/lib -R/usr/local/lib -lsasl2"

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 (SASL version 1.5.5) or
/usr/local/lib/sasl2/smtpd.conf (SASL version 2.1.1) you need to
specify how the server should validate client passwords.

IMPORTANT: If you configure SASL to use PAM (pluggable authentication
modules) authentication, the Postfix SMTP server will abort because
the SASL password file does not exist (default:  /etc/sasldb in
version 1.5.5, or /etc/sasldb2 in version 2.1.1), To fix, disable
CRAM-MD5 authentication by deleting /usr/lib/sasl/libcrammd5.so or
/usr/lib/sasl2/libcrammd5.so depending on your SASL library version.

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

(SASL version 1.5.5)
    /usr/local/lib/sasl/smtpd.conf:
	pwcheck_method: pwcheck

(SASL version 2.1.1)
    /usr/local/lib/sasl2/smtpd.conf:
	pwcheck_method: pwcheck

The pwcheck daemon is contained in the cyrus-sasl source tarball.
IMPORTANT: postfix processes need to have group read+execute
permission for the /var/pwcheck directory, otherwise authentication
attempts will fail.

Alternately, in SASL 1.5.5 and later (including 2.1.1), try:

(SASL version 1.5.5)
   /usr/local/lib/sasl/smtpd.conf:
   	pwcheck_method: saslauthd

(SASL version 2.1.1)
   /usr/local/lib/sasl2/smtpd.conf:
   	pwcheck_method: saslauthd

The saslauthd daemon is also contained in the cyrus-sasl source
tarball.  It is more flexible than the pwcheck daemon, in that it
can authenticate against PAM and various other sources.

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

(SASL version 1.5.5)
    /usr/local/lib/sasl/smtpd.conf:
	pwcheck_method:  sasldb

(SASL version 2.1.1)
    /usr/local/lib/sasl2/smtpd.conf:
    	pwcheck_method:  auxprop

This will use the SASL password file (default: /etc/sasldb in
version 1.5.5, or /etc/sasldb2 in version 2.1.1), which is maintained
with the saslpasswd or saslpasswd2 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 accommodate 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");'

mmencode is part of the metamail software.
MIME::Base64 is available from www.cpan.org.

Trouble shooting the SASL internals
===================================

[based on text by Liviu Daia]

In the Cyrus SASL sources you'll find a subdirectory named "sample".
Run make there, then run the resulting sample server and client in
separate terminals.  Strace / ktrace / truss the server to see what
makes it unhappy, fix the problem, then write the authors thanking
them for providing such useful logging.  Repeat the previous step
until you can successfully authenticate with the sample client.
Only then get back to Postfix.

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.