aebf40
Quick Start to Authenticate with SASL and PAM:
aebf40
----------------------------------------------
aebf40
aebf40
If you don't need the details and are an experienced system
aebf40
administrator you can just do this, otherwise read on.
aebf40
aebf40
1) Edit /etc/postfix/main.cf and set this:
aebf40
aebf40
smtpd_sasl_auth_enable = yes
aebf40
smtpd_sasl_security_options = noanonymous
aebf40
broken_sasl_auth_clients = yes
aebf40
aebf40
smtpd_recipient_restrictions = 
aebf40
  permit_sasl_authenticated,
aebf40
  permit_mynetworks,
aebf40
  reject_unauth_destination
aebf40
aebf40
2) Turn on saslauthd:
aebf40
aebf40
   /sbin/chkconfig --level 345 saslauthd on
aebf40
   /sbin/service saslauthd start
aebf40
aebf40
3) Edit /etc/sysconfig/saslauthd and set this:
aebf40
aebf40
   MECH=pam
aebf40
aebf40
4) Restart Postfix:
aebf40
aebf40
   /sbin/service postfix restart
aebf40
aebf40
A crash course in using SASL with Postfix:
aebf40
------------------------------------------
aebf40
aebf40
Red Hat's Postfix RPMs include support for both SASL and TLS.  SASL, the
aebf40
Simple Authentication and Security Layer, allows Postfix to implement RFC
aebf40
2554, which defines an extension to ESMTP, SMTP AUTH, which compliant
aebf40
ESMTP clients can use to authenticate themselves to ESMTP servers.
aebf40
Typically, this is used to allow roaming users to relay mail through a
aebf40
server safely without configuring the SMTP server to be an open relay.
aebf40
Inclusion of TLS support allows Postfix to implement RFC 2487, which
aebf40
defines an extension to ESMTP, SMTP STARTTLS, which compliant ESMTP
aebf40
clients and servers can use to encrypt the SMTP session.  This is a
aebf40
security enhancement -- normally SMTP is transmitted as cleartext over the
aebf40
wire, making it vulnerable to both passive sniffing and active alteration
aebf40
via monkey-in-the-middle attacks.  In addition, STARTTLS can also be
aebf40
used by either or both server and client to verify the identity of the
aebf40
other end, making it useful for the same sorts of purposes as SMTP AUTH.
aebf40
The two can even be combined.  Typically, this is done by first starting
aebf40
TLS, to encrypt the SMTP session, and then issuing the SMTP AUTH command,
aebf40
to authenticate the client; this combination ensures that the username
aebf40
and password transferred as part of the SMTP AUTH are protected by the
aebf40
TLS encrypted session.
aebf40
aebf40
SMTP AUTH is implemented using SASL, an abstraction layer which can
aebf40
authenticate against a variety of sources.  On Red Hat, SASL can use
aebf40
the /etc/shadow file, or it can use PAM libraries, or it can use its own
aebf40
password database (/etc/sasldb), or it can do various more exotic things.
aebf40
aebf40
Authentication raises a number of security concerns for obvious
aebf40
reasons. As a consequence authentication services on Red Hat systems
aebf40
are restricted to processes running with root privileges. However for
aebf40
security reasons it is also essential that a mail server such as
aebf40
Postfix run without root privileges so that mail operations cannot
aebf40
compromise the host system. This means that Postfix cannot directly
aebf40
use authentication services because it does not execute with root
aebf40
privileges. The answer to this this problem is to introduce an
aebf40
intermediary process that runs with root privileges which Postfix can
aebf40
communicate with and will perform authentication on behalf of
aebf40
Postfix. The SASL package includes an authentication daemon called
aebf40
saslauthd which provided this service, think of it as an
aebf40
authentication proxy.
aebf40
aebf40
Using Saslauthd:
aebf40
---------------- 
aebf40
aebf40
To use saslauthd there are several things you must assure are
aebf40
configured. 
aebf40
aebf40
Selecting an Authentication Method:
aebf40
-----------------------------------
aebf40
aebf40
Recall that it is saslauthd which is authenticating, not
aebf40
Postfix. To start with you must tell Postfix to use saslauthd, in
aebf40
main.cf edit this configuration parameter:
aebf40
aebf40
   smtpd_sasl_auth_enable = yes
aebf40
aebf40
It is also recommended that you disable anonymous logins otherwise
aebf40
you've left your system open, so also add this configuration
aebf40
parameter. 
aebf40
aebf40
   smtpd_sasl_security_options = noanonymous
aebf40
aebf40
Now you must tell saslauthd which authentication method to use. To
aebf40
determine the authentication methods currently supported by saslauthd
aebf40
invoke saslauthd with the -v parameter, it will print its version and
aebf40
its list of methods and then exit, for example:
aebf40
aebf40
   /usr/sbin/saslauthd -v
aebf40
   saslauthd 2.1.10
aebf40
   authentication mechanisms: getpwent kerberos5 pam rimap shadow 
aebf40
aebf40
When saslauthd starts up it reads its configuration options from the
aebf40
file /etc/sysconfig/saslauthd. Currently there are two parameters
aebf40
which can be set in this file, MECH and FLAGS. MECH is the
aebf40
authentication mechanism and FLAGS is any command line flags you may
aebf40
wish to pass to saslauthd. To tell saslauthd to use a specific
aebf40
mechanism edit /etc/sysconfig/saslauthd and set the MECH parameter,
aebf40
for example to use PAM it would look like this:
aebf40
aebf40
   MECH=pam
aebf40
aebf40
Of course you may use any of the other authentication mechanisms that
aebf40
saslauthd reported it supports. PAM is an excellent choice as PAM
aebf40
supports many of the same authentication methods that saslauthd does,
aebf40
but by using PAM you will have centralized all of your authentication
aebf40
configuration under PAM which is one of PAM's greatest assets.
aebf40
aebf40
How Postfix Interacts with SASL to Name its Authentication Services:
aebf40
--------------------------------------------------------------------
aebf40
aebf40
It can be very helpful to understand how Postfix communicates with
aebf40
SASL to name its authentication services. Knowing this will let you
aebf40
identify the configuration files the various components will access.
aebf40
aebf40
When Postfix invokes SASL it must give SASL an application name that
aebf40
SASL will use among other things to locate a configuration file for
aebf40
the application. The application name Postfix identifies itself as is
aebf40
"smtpd". SASL will append ".conf" to the application name and look for
aebf40
a config file in its library and config directories. Thus SASL will
aebf40
read Postfix's configuration from
aebf40
aebf40
   /etc/sasl2/smtpd.conf
aebf40
aebf40
This file names the authentication method SASL will use for Postfix
aebf40
(actually for smtpd, other MTA's such as sendmail may use the same
aebf40
file). Because we want to use the saslauthd authentication proxy
aebf40
daemon the contents of this file is:
aebf40
aebf40
   pwcheck_method: saslauthd
aebf40
aebf40
This tells SASL when being invoked to authentication for Postfix that
aebf40
it should use saslauthd. Saslauthd's mechanism is set in
aebf40
/etc/sysconfig/saslauthd (see below).
aebf40
aebf40
When Postfix calls on SASL to authenticate it passes to SASL a service
aebf40
name. This service name is used in authentication method specific
aebf40
way. The service name Postfix passes to SASL is "smtp" (note this is
aebf40
not the same as the application name which is "smtpd"). To understand
aebf40
this better consider the case of using PAM authentication. When SASL,
aebf40
or in our case saslauthd, invokes PAM it passes the service name of
aebf40
"smtp" to PAM which means that when PAM wants to read configuration
aebf40
information for this client it will find it under the name of "smtp". 
aebf40
aebf40
Turning on the Authentication Daemon:
aebf40
-------------------------------------
aebf40
aebf40
Red Hat security policy is not to automatically enable services
aebf40
belonging to a package when the package is installed. The system
aebf40
administrator must explicitly enable the service. To enable saslauthd
aebf40
do the following:
aebf40
aebf40
1) Tell the init process to launch saslauthd when entering various run
aebf40
   levels. Assuming you want saslauthd to run at run levels 3,4,5
aebf40
   invoke chkconfig.
aebf40
aebf40
   /sbin/chkconfig --level 345 saslauthd on
aebf40
aebf40
2) You will probably want to start saslauthd now without having to
aebf40
   reboot, to do this:
aebf40
aebf40
   /sbin/service saslauthd start
aebf40
aebf40
Trouble Shooting Authentication:
aebf40
--------------------------------
aebf40
aebf40
The best way to debug authentication problems is to examine log
aebf40
messages from the authentication components. However, normally these
aebf40
log messages are suppressed. There are two principle reasons the
aebf40
messages are suppressed. The first is that they are typically logged
aebf40
at the DEBUG logging priority level which is the lowest priority and
aebf40
the syslog configuration typically logs only higher priority
aebf40
messages. The second reason is that for security reasons authentication
aebf40
logging is considered a risk. Authentication logging has been divided
aebf40
into two different facilities, auth and authpriv. authpriv is private
aebf40
and is typically shunted off to a different log file with higher
aebf40
protection. You will want to be able to see both auth and authpriv
aebf40
messages at all priorities. To do this as root edit /etc/syslog.conf
aebf40
file, find the following line
aebf40
aebf40
authpriv.*					/var/log/secure
aebf40
aebf40
edit the line to:
aebf40
aebf40
authpriv.*;auth.*				/var/log/secure
aebf40
aebf40
Then restart syslogd so the syslog configuration changes will be
aebf40
picked up:
aebf40
aebf40
       /sbin/service syslog restart
aebf40
aebf40
Now all authentication messages at all priorities will log to
aebf40
/var/log/secure. 
aebf40
aebf40
Using PAM to Authenticate:
aebf40
--------------------------
aebf40
aebf40
Edit /etc/sysconfig/saslauthd and set MECH to PAM like this:
aebf40
aebf40
   MECH=pam
aebf40
aebf40
When PAM is invoked via SASL it is passed a service name of
aebf40
"smtp". This means that PAM will read its configuration parameters for
aebf40
Postfix from the file: /etc/pam.d/smtp. By default this file is set to
aebf40
refer to the global system PAM authentication policy, thus by default
aebf40
you'll get whatever PAM authentication your system is configured for
aebf40
and virtually all applications use. Configuring PAM authentication is
aebf40
beyond the scope of this document, please refer to the PAM
aebf40
documentation if you which to modify PAM.
aebf40
aebf40
Trouble Shooting PAM Authentication:
aebf40
------------------------------------
aebf40
aebf40
1) One possible reason PAM may fail to authenticate even if the user
aebf40
is known to the system is if PAM fails to find the service
aebf40
configuration file in /etc/pam.d. Service configuration files are not
aebf40
required by PAM, if it does not find a service configuration file it
aebf40
will default to "other". Since PAM does not consider the absence of a
aebf40
service configuration file a problem it does not log anything nor does
aebf40
it return an error to the calling application. In other words it is
aebf40
completely silent about the fact it did not find a service
aebf40
configuration file. On Red Hat system the default implementation of
aebf40
"other" for PAM is to deny access. This means on Red Hat systems the
aebf40
absence of a PAM service configuration file will mean PAM will
aebf40
silently fail authentication. The PAM service configuration file for
aebf40
postfix is /etc/pam.d/smtp and is intalled by the Red Hat Postfix rpm
aebf40
and put under control of "alternatives" with name mta. Alternatives
aebf40
allows one to select between the sendmail and postfix MTA's and
aebf40
manages symbolic links for files the two MTA's share. /etc/pam.d/smtp
aebf40
is one such file, if you have not selected Postfix as your prefered
aebf40
MTA the link to this file will not be present. To select Postfix as
aebf40
your MTA do this: "/usr/sbin/alternatives --config mta" and follow the
aebf40
prompt to select postfix.
aebf40
aebf40
2) Is SASL appending a realm or domain to a username? PAM
aebf40
   authentication requires a bare username and password, other
aebf40
   authentication methods require the username to be qualified with a
aebf40
   realm. Typically the username will be rewritten as user@realm
aebf40
   (e.g. user@foo.com) PAM does not understand a username with
aebf40
   "@realm" appended to it and will fail the authentication with the
aebf40
   message that the user is unknown. If the log files shows saslauthd
aebf40
   usernames with "@realm" appended to it then the
aebf40
   smtpd_sasl_local_domain configuration parameter is likely set in
aebf40
   /etc/postfix/main.cf file, make sure its either not set or set it
aebf40
   to an empty string. Restart postfix and test authtentication again,
aebf40
   the log file should show only a bare username.
aebf40
aebf40
aebf40
aebf40
Using saslpasswd to Authenticate:
aebf40
---------------------------------
aebf40
aebf40
SASL can maintain its own password database independent of the host
aebf40
system's authentication setup, it is called saslpasswd. You may wish
aebf40
to use saslpasswd if you want to isolate who can smtp authenticate
aebf40
from general system users. However, it does add another password
aebf40
database that a system administrator must maintain.
aebf40
aebf40
To authenticate against sasldb, you'll first have to create accounts.
aebf40
These accounts are entirely separate from system accounts, and are used
aebf40
only by connecting SMTP clients to authenticate themselves.  Use the
aebf40
saslpassword command:
aebf40
aebf40
saslpasswd -u `postconf -h myhostname` -c user
aebf40
aebf40
to create an account named user which can log into realm.  For the
aebf40
realm, make absolutely certain that you use the same value as is set for
aebf40
myhostname in /etc/postfix/main.cf.  If you don't, it likely won't work.
aebf40
aebf40
Also, be aware that saslpasswd is somewhat buggy.  The first time you
aebf40
run it, it may generate an error message while initializing the sasldb.
aebf40
If it does, just add that user a second time.
aebf40
aebf40
You'll need to set permissions on the SASL password database so that
aebf40
the Postfix daemons can read it:
aebf40
aebf40
   chgrp postfix /etc/sasldb
aebf40
   chmod g+r /etc/sasldb
aebf40
aebf40
Now, you'll need to modify /etc/postfix/main.cf to tell it to
aebf40
support SASL.  The complete options you might want to use are in the
aebf40
sample-auth.cf file in the Postfix documentation directory.  An option
aebf40
you will definitely need is:
aebf40
aebf40
# enable SASL support
aebf40
smtpd_sasl_auth_enable = yes
aebf40
aebf40
You might also need to set the SASL authentication realm to whatever
aebf40
realm you used when you created your sasldb; by default, this is set to
aebf40
$myhostname, but you instead might need something like:
aebf40
aebf40
# set SASL realm to domain instead
aebf40
smtpd_sasl_local_domain = $mydomain
aebf40
aebf40
Other Postfix Authentication Parameters:
aebf40
----------------------------------------
aebf40
aebf40
If you want to allow your already configured users to still use your SMTP
aebf40
server, and to allow users authenticated via SMTP AUTH to use your server
aebf40
as well, then modify your existing smtpd_recipient_restrictions line to;
aebf40
aebf40
# also allow authenticated (RFC 2554) users
aebf40
smtpd_recipient_restrictions = permit_sasl_authenticated ...
aebf40
aebf40
If you want to restrict use of your server to just authenticated clients
aebf40
(Note: this is a bad idea for public mail servers), then instead use:
aebf40
aebf40
# restrict server access to authenticated (RFC 2554) clients
aebf40
smtpd_delay_reject = yes
aebf40
smtpd_client_restrictions = permit_sasl_authenticated ...
aebf40
aebf40
SASL supports several password types which have differing security
aebf40
properties.  Different SMTP clients may support some or all of these
aebf40
password types.  When the client issues an EHLO command, the server
aebf40
tells it which types it supports:
aebf40
aebf40
$ telnet station6 25
aebf40
Trying 10.100.0.6...
aebf40
Connected to station6.example.com.
aebf40
Escape character is '^]'.
aebf40
220 station6.example.com ESMTP Postfix
aebf40
ehlo station7
aebf40
250-station6.example.com
aebf40
250-PIPELINING
aebf40
250-SIZE 10240000
aebf40
250-VRFY
aebf40
250-ETRN
aebf40
250-STARTTLS
aebf40
250-AUTH PLAIN LOGIN DIGEST-MD5 CRAM-MD5
aebf40
250-XVERP
aebf40
250 8BITMIME
aebf40
aebf40
Here, the server supports PLAIN, LOGIN, DIGEST-MD5, and CRAM-MD5 password
aebf40
methods.
aebf40
aebf40
The client then chooses the first of these listed methods which it also
aebf40
supports, and issues an SMTP AUTH request.
aebf40
aebf40
For security, PLAIN and LOGIN methods are typically disabled.  These two
aebf40
methods use trivially decryptable encryption, making the username and
aebf40
password issued by the client vulnerable to interception via a sniffer
aebf40
in between the server and client.  Unfortunately, they can't always
aebf40
be disabled.  Some popular SMTP clients, including MS Outlook 5.x,
aebf40
only support PLAIN authentication, for example.
aebf40
aebf40
To limit the login methods offered by the server:
aebf40
aebf40
# disable unsafe password methods
aebf40
smtpd_sasl_security_options = noplaintext noanonymous
aebf40
aebf40
Available options are:
aebf40
aebf40
noplaintext, which disables LOGIN and PLAIN
aebf40
noanonymous, which disables disables ANON
aebf40
nodictionary, which disables methods vulnerable to dictionary attacks
aebf40
noactive, which disables methods vulnerable to active attacks
aebf40
aebf40
The last two are rarely used, since almost all supported methods are
aebf40
vulnerable to those attacks ;-).
aebf40
aebf40
Also be aware that some broken clients mis-implement the SMTP AUTH
aebf40
protocol, and send commands using incorrect syntax (AUTH=foo instead of
aebf40
the correct AUTH foo).  MS Outlook 4.x clients have this bug, among
aebf40
a legion of others....  If you need to support these clients, use:
aebf40
aebf40
# support braindead MS products
aebf40
broken_sasl_auth_clients = yes
aebf40
aebf40
To help prevent spoofing, you can also create a map file of SASL login
aebf40
names which are allowed to use specific envelope sender (MAIL FROM)
aebf40
addresses.  If you choose to do this, you also have to tell Postfix to
aebf40
reject addresses which don't match login names:
aebf40
aebf40
# prevent spoofing by authenticated users
aebf40
reject_sender_login_mismatch
aebf40
smtpd_sender_login_maps=type:/path/to/file
aebf40
aebf40
Configuration of SASL clients is much simpler.  Postfix itself can be
aebf40
made a SASL client; this is typically useful when roaming users run Linux
aebf40
on their laptop and need to relay mail back through the organization's
aebf40
main server.
aebf40
aebf40
To enable Postfix to act as an SMTP AUTH client, simply add to
aebf40
/etc/postfix/main.cf:
aebf40
aebf40
# support authentication (RFC 2557) when relaying through a server
aebf40
smtp_sasl_auth_enable = yes
aebf40
aebf40
and tell Postfix where to find the usernames and passwords it should
aebf40
use to authenticate:
aebf40
aebf40
# location of passwords for authentication client
aebf40
smtp_sasl_password_maps = type:/path/to/file
aebf40
aebf40
The file itself should have the format:
aebf40
aebf40
destination     username:password
aebf40
aebf40
where destination is the name of the server, and username:password are
aebf40
the username and password which should be presented to that server to
aebf40
authenticate when connecting to it as a client.
aebf40
aebf40
Optionally, the authentication methods to be used can be specified for
aebf40
the Postfix client, just as they can be for the Postfix server:
aebf40
aebf40
# disable plaintext and anonymous
aebf40
smtp_sasl_security_options = noplaintext noanonymous
aebf40
aebf40
Many popular end-user MUAs can also be configured as SMTP AUTH clients.
aebf40
Clients capable of this supplied with Red Hat include pine, Netscape,
aebf40
and Mozilla.
aebf40
aebf40
Other Sources of Documentation:
aebf40
-------------------------------
aebf40
aebf40
/usr/share/doc/postfix-<version>/README_FILES/SASL_README
aebf40
aebf40
Local configuration examples:
aebf40
aebf40
/usr/share/doc/postfix-*/samples
aebf40
aebf40
Postfix Howtos, Guides and Tips by Ralf Hildebrandt and Patrick
aebf40
Koetter can be found at: http://postfix.state-of-mind.de
aebf40
aebf40
------------------------------------------------------------------------------
aebf40
aebf40
Please send any comments / corrections to Chris Ricker
aebf40
<kaboom@gatech.edu>.  This material can be freely modified and
aebf40
redistributed. Additional material provided by John Dennis
aebf40
<jdennis@redhat.com> and Dax Kelson <dax@gurulabs.com>.