postfix/README-Postfix-SASL-RedHat.txt

Quick Start to Authenticate with SASL and PAM:
----------------------------------------------

If you don't need the details and are an experienced system
administrator you can just do this, otherwise read on.

1) Edit /etc/postfix/main.cf and set this:

smtpd_sasl_auth_enable = yes
smtpd_sasl_security_options = noanonymous
broken_sasl_auth_clients = yes

smtpd_recipient_restrictions = 
  permit_sasl_authenticated,
  permit_mynetworks,
  reject_unauth_destination

2) Turn on saslauthd:

   /sbin/chkconfig --level 345 saslauthd on
   /sbin/service saslauthd start

3) Edit /etc/sysconfig/saslauthd and set this:

   MECH=pam

4) Restart Postfix:

   /sbin/service postfix restart

A crash course in using SASL with Postfix:
------------------------------------------

Red Hat's Postfix RPMs include support for both SASL and TLS.  SASL, the
Simple Authentication and Security Layer, allows Postfix to implement RFC
2554, which defines an extension to ESMTP, SMTP AUTH, which compliant
ESMTP clients can use to authenticate themselves to ESMTP servers.
Typically, this is used to allow roaming users to relay mail through a
server safely without configuring the SMTP server to be an open relay.
Inclusion of TLS support allows Postfix to implement RFC 2487, which
defines an extension to ESMTP, SMTP STARTTLS, which compliant ESMTP
clients and servers can use to encrypt the SMTP session.  This is a
security enhancement -- normally SMTP is transmitted as cleartext over the
wire, making it vulnerable to both passive sniffing and active alteration
via monkey-in-the-middle attacks.  In addition, STARTTLS can also be
used by either or both server and client to verify the identity of the
other end, making it useful for the same sorts of purposes as SMTP AUTH.
The two can even be combined.  Typically, this is done by first starting
TLS, to encrypt the SMTP session, and then issuing the SMTP AUTH command,
to authenticate the client; this combination ensures that the username
and password transferred as part of the SMTP AUTH are protected by the
TLS encrypted session.

SMTP AUTH is implemented using SASL, an abstraction layer which can
authenticate against a variety of sources.  On Red Hat, SASL can use
the /etc/shadow file, or it can use PAM libraries, or it can use its own
password database (/etc/sasldb), or it can do various more exotic things.

Authentication raises a number of security concerns for obvious
reasons. As a consequence authentication services on Red Hat systems
are restricted to processes running with root privileges. However for
security reasons it is also essential that a mail server such as
Postfix run without root privileges so that mail operations cannot
compromise the host system. This means that Postfix cannot directly
use authentication services because it does not execute with root
privileges. The answer to this this problem is to introduce an
intermediary process that runs with root privileges which Postfix can
communicate with and will perform authentication on behalf of
Postfix. The SASL package includes an authentication daemon called
saslauthd which provided this service, think of it as an
authentication proxy.

Using Saslauthd:
---------------- 

To use saslauthd there are several things you must assure are
configured. 

SASL has been shipped in various versions, currently there is SASL V1
and SASL V2. The implementation of saslauthd is not compatible between
SASL V1 and V2 libraries. You must use the V2 implementation of
SASL. Note that currently the V1 SASL libraries install in
/usr/lib/sasl and the V2 SASL libraries install in /usr/lib/sasl2.

Selecting an Authentication Method:
-----------------------------------

Recall that it is saslauthd which is authenticating, not
Postfix. To start with you must tell Postfix to use saslauthd, in
main.cf edit this configuration parameter:

   smtpd_sasl_auth_enable = yes

It is also recommended that you disable anonymous logins otherwise
you've left your system open, so also add this configuration
parameter. 

   smtpd_sasl_security_options = noanonymous

Now you must tell saslauthd which authentication method to use. To
determine the authentication methods currently supported by saslauthd
invoke saslauthd with the -v parameter, it will print its version and
its list of methods and then exit, for example:

   /usr/sbin/saslauthd -v
   saslauthd 2.1.10
   authentication mechanisms: getpwent kerberos5 pam rimap shadow 

When saslauthd starts up it reads its configuration options from the
file /etc/sysconfig/saslauthd. Currently there are two parameters
which can be set in this file, MECH and FLAGS. MECH is the
authentication mechanism and FLAGS is any command line flags you may
wish to pass to saslauthd. To tell saslauthd to use a specific
mechanism edit /etc/sysconfig/saslauthd and set the MECH parameter,
for example to use PAM it would look like this:

   MECH=pam

Of course you may use any of the other authentication mechanisms that
saslauthd reported it supports. PAM is an excellent choice as PAM
supports many of the same authentication methods that saslauthd does,
but by using PAM you will have centralized all of your authentication
configuration under PAM which is one of PAM's greatest assets.

How Postfix Interacts with SASL to Name its Authentication Services:
--------------------------------------------------------------------

It can be very helpful to understand how Postfix communicates with
SASL to name its authentication services. Knowing this will let you
identify the configuration files the various components will access.

When Postfix invokes SASL it must give SASL an application name that
SASL will use among other things to locate a configuration file for
the application. The application name Postfix identifies itself as is
"smtpd". SASL will append ".conf" to the application name and look for
a config file in its library directory. Thus SASL will read Postfix's
configuration from

   /usr/lib/sasl2/smtpd.conf

if postfix has been linked against the version 2 library of cyrus-sasl, or:

   /usr/lib/sasl/smtpd.conf

if postfix has been linked against the version 1 library of cyrus-sasl


This file names the authentication method SASL will use for Postfix
(actually for smtpd, other MTA's such as sendmail may use the same
file). Because we want to use the saslauthd authentication proxy
daemon the contents of this file is:

   pwcheck_method: saslauthd

This tells SASL when being invoked to authentication for Postfix that
it should use saslauthd. Saslauthd's mechanism is set in
/etc/sysconfig/saslauthd (see below).

A note about cyrus-sasl versions and saslauthd. Red Hat cyrus-sasl
RPM's parallel install both the v1 and v2 versions of cyrus-sasl
libraries into /usr/lib/sasl and /usr/lib/sasl2 respectively. However
only the v2 version of saslauthd is installed. The v1 and v2 versions
saslauthd are not compatible, the protocol used to communicate between
a client which has linked cyrus-sasl and the saslauthd daemon was
changed between the v1 and v2 versons of sasluathd. The saslauthd
daemon that the Red Hat package installs is the v2 version. Therefore
for a client which has linked against a v1 version of cyrus-sasl must
communicate using the v2 version of the saslauthd protocol because
only the v2 version of saslauthd is installed. Red Hat has modified
the v1 version of the cyrus-sasl library to generate v2 protocol if
the client is configured to use the v2 protocol. This is accomplished
by adding a parameter to the sasl service configuration file. Since
the service is smtpd this file is /usr/lib/sasl/smtpd.conf. Note
/usr/lib/sasl2/smtpd.conf does not need this extra configuration
parameter because it will by default speak version 2 of the saslauthd
protocol. Therefore /usr/lib/sasl/smtpd.conf need the following extra
line it its file in addition to the pwcheck_method of saslauthd.

saslauthd_version: 2

When Postfix calls on SASL to authenticate it passes to SASL a service
name. This service name is used in authentication method specific
way. The service name Postfix passes to SASL is "smtp" (note this is
not the same as the application name which is "smtpd"). To understand
this better consider the case of using PAM authentication. When SASL,
or in our case saslauthd, invokes PAM it passes the service name of
"smtp" to PAM which means that when PAM wants to read configuration
information for this client it will find it under the name of "smtp". 

Turning on the Authentication Daemon:
-------------------------------------

Red Hat security policy is not to automatically enable services
belonging to a package when the package is installed. The system
administrator must explicitly enable the service. To enable saslauthd
do the following:

1) Tell the init process to launch saslauthd when entering various run
   levels. Assuming you want saslauthd to run at run levels 3,4,5
   invoke chkconfig.

   /sbin/chkconfig --level 345 saslauthd on

2) You will probably want to start saslauthd now without having to
   reboot, to do this:

   /sbin/service saslauthd start

Trouble Shooting Authentication:
--------------------------------

The best way to debug authentication problems is to examine log
messages from the authentication components. However, normally these
log messages are suppressed. There are two principle reasons the
messages are suppressed. The first is that they are typically logged
at the DEBUG logging priority level which is the lowest priority and
the syslog configuration typically logs only higher priority
messages. The second reason is that for security reasons authentication
logging is considered a risk. Authentication logging has been divided
into two different facilities, auth and authpriv. authpriv is private
and is typically shunted off to a different log file with higher
protection. You will want to be able to see both auth and authpriv
messages at all priorities. To do this as root edit /etc/syslog.conf
file, find the following line

authpriv.*					/var/log/secure

edit the line to:

authpriv.*;auth.*				/var/log/secure

Then restart syslogd so the syslog configuration changes will be
picked up:

       /sbin/service syslog restart

Now all authentication messages at all priorities will log to
/var/log/secure. 

Using PAM to Authenticate:
--------------------------

Edit /etc/sysconfig/saslauthd and set MECH to PAM like this:

   MECH=pam

When PAM is invoked via SASL it is passed a service name of
"smtp". This means that PAM will read its configuration parameters for
Postfix from the file: /etc/pam.d/smtp. By default this file is set to
refer to the global system PAM authentication policy, thus by default
you'll get whatever PAM authentication your system is configured for
and virtually all applications use. Configuring PAM authentication is
beyond the scope of this document, please refer to the PAM
documentation if you which to modify PAM.

Trouble Shooting PAM Authentication:
------------------------------------

1) One possible reason PAM may fail to authenticate even if the user
is known to the system is if PAM fails to find the service
configuration file in /etc/pam.d. Service configuration files are not
required by PAM, if it does not find a service configuration file it
will default to "other". Since PAM does not consider the absence of a
service configuration file a problem it does not log anything nor does
it return an error to the calling application. In other words it is
completely silent about the fact it did not find a service
configuration file. On Red Hat system the default implementation of
"other" for PAM is to deny access. This means on Red Hat systems the
absence of a PAM service configuration file will mean PAM will
silently fail authentication. The PAM service configuration file for
postfix is /etc/pam.d/smtp and is intalled by the Red Hat Postfix rpm
and put under control of "alternatives" with name mta. Alternatives
allows one to select between the sendmail and postfix MTA's and
manages symbolic links for files the two MTA's share. /etc/pam.d/smtp
is one such file, if you have not selected Postfix as your prefered
MTA the link to this file will not be present. To select Postfix as
your MTA do this: "/usr/sbin/alternatives --config mta" and follow the
prompt to select postfix.

2) Is SASL appending a realm or domain to a username? PAM
   authentication requires a bare username and password, other
   authentication methods require the username to be qualified with a
   realm. Typically the username will be rewritten as user@realm
   (e.g. user@foo.com) PAM does not understand a username with
   "@realm" appended to it and will fail the authentication with the
   message that the user is unknown. If the log files shows saslauthd
   usernames with "@realm" appended to it then the
   smtpd_sasl_local_domain configuration parameter is likely set in
   /etc/postfix/main.cf file, make sure its either not set or set it
   to an empty string. Restart postfix and test authtentication again,
   the log file should show only a bare username.



Using saslpasswd to Authenticate:
---------------------------------

SASL can maintain its own password database independent of the host
system's authentication setup, it is called saslpasswd. You may wish
to use saslpasswd if you want to isolate who can smtp authenticate
from general system users. However, it does add another password
database that a system administrator must maintain.

To authenticate against sasldb, you'll first have to create accounts.
These accounts are entirely separate from system accounts, and are used
only by connecting SMTP clients to authenticate themselves.  Use the
saslpassword command:

saslpasswd -u `postconf -h myhostname` -c user

to create an account named user which can log into realm.  For the
realm, make absolutely certain that you use the same value as is set for
myhostname in /etc/postfix/main.cf.  If you don't, it likely won't work.

Also, be aware that saslpasswd is somewhat buggy.  The first time you
run it, it may generate an error message while initializing the sasldb.
If it does, just add that user a second time.

You'll need to set permissions on the SASL password database so that
the Postfix daemons can read it:

   chgrp postfix /etc/sasldb
   chmod g+r /etc/sasldb

Now, you'll need to modify /etc/postfix/main.cf to tell it to
support SASL.  The complete options you might want to use are in the
sample-auth.cf file in the Postfix documentation directory.  An option
you will definitely need is:

# enable SASL support
smtpd_sasl_auth_enable = yes

You might also need to set the SASL authentication realm to whatever
realm you used when you created your sasldb; by default, this is set to
$myhostname, but you instead might need something like:

# set SASL realm to domain instead
smtpd_sasl_local_domain = $mydomain

Other Postfix Authentication Parameters:
----------------------------------------

If you want to allow your already configured users to still use your SMTP
server, and to allow users authenticated via SMTP AUTH to use your server
as well, then modify your existing smtpd_recipient_restrictions line to;

# also allow authenticated (RFC 2554) users
smtpd_recipient_restrictions = permit_sasl_authenticated ...

If you want to restrict use of your server to just authenticated clients
(Note: this is a bad idea for public mail servers), then instead use:

# restrict server access to authenticated (RFC 2554) clients
smtpd_delay_reject = yes
smtpd_client_restrictions = permit_sasl_authenticated ...

SASL supports several password types which have differing security
properties.  Different SMTP clients may support some or all of these
password types.  When the client issues an EHLO command, the server
tells it which types it supports:

$ telnet station6 25
Trying 10.100.0.6...
Connected to station6.example.com.
Escape character is '^]'.
220 station6.example.com ESMTP Postfix
ehlo station7
250-station6.example.com
250-PIPELINING
250-SIZE 10240000
250-VRFY
250-ETRN
250-STARTTLS
250-AUTH PLAIN LOGIN DIGEST-MD5 CRAM-MD5
250-XVERP
250 8BITMIME

Here, the server supports PLAIN, LOGIN, DIGEST-MD5, and CRAM-MD5 password
methods.

The client then chooses the first of these listed methods which it also
supports, and issues an SMTP AUTH request.

For security, PLAIN and LOGIN methods are typically disabled.  These two
methods use trivially decryptable encryption, making the username and
password issued by the client vulnerable to interception via a sniffer
in between the server and client.  Unfortunately, they can't always
be disabled.  Some popular SMTP clients, including MS Outlook 5.x,
only support PLAIN authentication, for example.

To limit the login methods offered by the server:

# disable unsafe password methods
smtpd_sasl_security_options = noplaintext noanonymous

Available options are:

noplaintext, which disables LOGIN and PLAIN
noanonymous, which disables disables ANON
nodictionary, which disables methods vulnerable to dictionary attacks
noactive, which disables methods vulnerable to active attacks

The last two are rarely used, since almost all supported methods are
vulnerable to those attacks ;-).

Also be aware that some broken clients mis-implement the SMTP AUTH
protocol, and send commands using incorrect syntax (AUTH=foo instead of
the correct AUTH foo).  MS Outlook 4.x clients have this bug, among
a legion of others....  If you need to support these clients, use:

# support braindead MS products
broken_sasl_auth_clients = yes

To help prevent spoofing, you can also create a map file of SASL login
names which are allowed to use specific envelope sender (MAIL FROM)
addresses.  If you choose to do this, you also have to tell Postfix to
reject addresses which don't match login names:

# prevent spoofing by authenticated users
reject_sender_login_mismatch
smtpd_sender_login_maps=type:/path/to/file

Configuration of SASL clients is much simpler.  Postfix itself can be
made a SASL client; this is typically useful when roaming users run Linux
on their laptop and need to relay mail back through the organization's
main server.

To enable Postfix to act as an SMTP AUTH client, simply add to
/etc/postfix/main.cf:

# support authentication (RFC 2557) when relaying through a server
smtp_sasl_auth_enable = yes

and tell Postfix where to find the usernames and passwords it should
use to authenticate:

# location of passwords for authentication client
smtp_sasl_password_maps = type:/path/to/file

The file itself should have the format:

destination     username:password

where destination is the name of the server, and username:password are
the username and password which should be presented to that server to
authenticate when connecting to it as a client.

Optionally, the authentication methods to be used can be specified for
the Postfix client, just as they can be for the Postfix server:

# disable plaintext and anonymous
smtp_sasl_security_options = noplaintext noanonymous

Many popular end-user MUAs can also be configured as SMTP AUTH clients.
Clients capable of this supplied with Red Hat include pine, Netscape,
and Mozilla.

Other Sources of Documentation:
-------------------------------

Local configuration examples:

/usr/share/doc/postfix-*/samples

Postfix Howtos, Guides and Tips by Ralf Hildebrandt and Patrick
Koetter can be found at: http://postfix.state-of-mind.de

------------------------------------------------------------------------------

Please send any comments / corrections to Chris Ricker
<kaboom@gatech.edu>.  This material can be freely modified and
redistributed. Additional material provided by John Dennis
<jdennis@redhat.com> and Dax Kelson <dax@gurulabs.com>.