Blame SOURCES/README-Postfix-SASL-RedHat.txt

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