The postscreen(8) server can be put "in front" of Postfix
+smtpd(8) processes. Its purpose is to accept connections from the
+network and to decide what SMTP clients are allowed to talk to
+Postfix. According to the 2008 MessageLabs annual report, 81% of
+all email was spam, and 90% of that was sent by botnets. While
+postscreen(8) keeps the zombies away, more smtpd(8) processes remain
+available for legitimate clients.
+
+ The postscreen(8) server is still evolving, and is likely to
+undergo changes that break compatibility with earlier versions.
+For this reason the postscreen(8) server is not installed with the
+stable Postfix release.
+
+
+
+ | zombie |
+
+ | | \ |
+
+ | zombie | - |
+ | | | - |
+ smtpd(8) |
+
+ | | \ | |
+ / |
+
+ | other |
+--- |
+postscreen(8) |
+
+ | | / | |
+ \ |
+
+ | other |
+ - | | | |
+ - | smtpd(8)
|
+ | | / |
+
+ | zombie |
+
+
diff --git a/postfix/proto/SASL_README.html b/postfix/proto/SASL_README.html
index f62692288..3c6e558e9 100644
--- a/postfix/proto/SASL_README.html
+++ b/postfix/proto/SASL_README.html
@@ -1,8 +1,6 @@
-
-
Postfix SASL Howto
@@ -17,231 +15,1107 @@
-WARNING
+Warning
People who go to the trouble of installing Postfix may have the
expectation that Postfix is more secure than some other mailers.
-The Cyrus SASL library is a lot of code. With this, Postfix becomes
-as secure as other mail systems that use the Cyrus SASL library.
-Dovecot provides an alternative that may be worth considering.
-
+The Cyrus SASL library contains a lot of code. With this, Postfix
+becomes as secure as other mail systems that use the Cyrus SASL
+library. Dovecot provides an alternative that may be worth
+considering.
-
+
- Postfix SASL support (RFC 4954, formerly RFC 2554) can be used
-to authenticate
-remote SMTP clients to the Postfix SMTP server, and to authenticate
-the Postfix SMTP client to a remote SMTP server.
+ When an SMTP client connects to an SMTP server, the server needs
+to decide whether that client is authorized to send mail to remote
+destinations, or whether the client can send mail only to the
+destinations that the server itself is responsible for. Usually,
+the SMTP server will allow mail to remote destinations only if the
+client's IP address is in the "same network" as the server's IP
+address.
- When receiving mail, the Postfix SMTP server 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.
+ Sometimes the SMTP client and server are in different networks,
+but the client still needs "same network" privileges. To address
+this problem, Postfix supports SASL authentication (RFC 4954,
+formerly RFC 2554). With this a remote SMTP client can authenticate
+to the Postfix SMTP server, and the Postfix SMTP client can
+authenticate to a remote SMTP server. Once the client is authenticated
+the server can give it "same network" privileges.
- When sending mail, the Postfix SMTP client can look up the
-remote SMTP server hostname or
-destination domain (the address right-hand part) in a SASL password
-table, and if a username/password is found, it will use that username
-and password to authenticate to the remote SMTP server. And as of
-version 2.3,
-Postfix can be configured to search its SASL password table by the
-sender email address.
+ Postfix does not implement SASL itself, but instead uses existing
+implementations as building blocks. This means that some SASL-related
+configuration will involve files that belong to Postfix, while other
+configuration will involve files that belong to the specific SASL
+implementation that Postfix will use. This document covers both the
+Postfix and non-Postfix configuration.
-This document covers the following topics:
+ You can read more about the following topics:
-
+
- This document describes Postfix with the following SASL
-implementations:
+ As mentioned earlier, SASL is implemented separately from
+Postfix. For this reason, configuring SASL authentication in the
+Postfix SMTP server involves two different steps:
--
Cyrus SASL version 1 (client and server).
+ -
Configuring the SASL implementation to offer a list of
+mechanisms that are suitable for SASL authentication and, depending
+on the SASL implementation used, configuring authentication backends
+that verify the remote SMTP client's authentication data against
+the system password file or some other database.
--
Cyrus SASL version 2 (client and server).
-
- -
Dovecot protocol version 1 (server only, Postfix version
-2.3 and later)
+ -
Configuring the Postfix SMTP server to enable SASL
+authentication, and to authorize clients to relay mail or to control
+what envelope sender addresses the client may use.
- Postfix version 2.3 introduces a plug-in mechanism that provides
-support for multiple SASL implementations. To find out what
-implementations are built into Postfix, use the following commands:
+
Successful authentication in the Postfix SMTP server requires
+a functional SASL framework. Configuring SASL should therefore
+always be the first step.
+
+ You can read more about the following topics:
+
+
+
+
+
+
+ Currently the Postfix SMTP server supports the Cyrus SASL and
+Dovecot SASL implementations.
+
+
+
+Note
+
+ Before Postfix version 2.3, Postfix had support only for Cyrus
+SASL. Current Postfix versions have a plug-in architecture that
+can support multiple SASL implementations.
+
+
+
+ To find out what SASL implementations are compiled into Postfix,
+use the following commands:
+
+
+
+% postconf -a (SASL support in the SMTP server)
+% postconf -A (SASL support in the SMTP+LMTP client)
+
+
+
+ These commands are available only with Postfix version 2.3 and
+later.
+
+
+
+ Dovecot is a POP/IMAP server that must be configured to
+authenticate POP/IMAP clients. When the Postfix SMTP server uses
+Dovecot SASL, it also reuses this configuration. Consult the Dovecot documentation for how
+to configure and operate the Dovecot authentication server.
+
+
+
+ Communication between the Postfix SMTP server
+and Dovecot SASL happens via a UNIX-domain socket. The socket
+pathname and the list of mechanisms offered to Postfix need to be
+specified on the Dovecot server side in dovecot.conf.
+
+
+ The following example assumes that the Postfix queue is under
+/var/spool/postfix/.
+
+
+
+ 1 /etc/dovecot.conf:
+ 2 auth default {
+ 3 mechanisms = plain login
+ 4 passdb pam {
+ 5 }
+ 6 userdb passwd {
+ 7 }
+ 8 socket listen {
+ 9 client {
+10 path = /var/spool/postfix/private/auth
+11 mode = 0660
+12 user = postfix
+13 group = postfix
+14 }
+15 }
+16 }
+
+
+
+ Line 3 provides plain and login as
+mechanisms for the Postfix SMTP server, line 10 places the Dovecot
+SASL socket in /var/spool/postfix/private/auth, and
+lines 11-13 limit read+write permissions to user and group
+postfix only.
+
+ Proceed with the section "Enabling SASL authentication and
+authorization in the Postfix SMTP server" to turn on and use
+SASL in the Postfix SMTP server.
+
+
+
+ The Cyrus SASL framework was supports a wide variety of
+applications. Different applications may require different
+configurations. As a consequence each application may have its own
+configuration file.
+
+ The first step configuring Cyrus SASL is to determine name and
+location of a configuration file that describes how the Postfix
+SMTP server will use the SASL framework.
+
+
+
+ The name of the configuration file (default: smtpd.conf)
+is configurable. It is a concatenation from a value that the Postfix
+SMTP server sends to the Cyrus SASL library, and the suffix
+.conf, added by Cyrus SASL.
+
+ The value sent by Postfix is the name of the server component
+that will use Cyrus SASL. It defaults to smtpd and
+is configured with one of the following variables:
+
+
+
+/etc/postfix/main.cf:
+ # Postfix 2.3 and later
+ smtpd_sasl_path = smtpd
+
+ # Postfix < 2.3
+ smtpd_sasl_application_name = smtpd
+
+
+
+
+
+ The location where Cyrus SASL searches for the named file depends
+on the Cyrus SASL version and the OS/distribution used.
+
+ You can read more about the following topics:
+
+
+
+-
Cyrus SASL version 2.x searches for the configuration file
+in /usr/lib/sasl2/.
+
+-
Cyrus SASL version 2.1.22 and newer additionally search
+in /etc/sasl2/.
+
+-
Some Postfix distributions are modified and look for the
+Cyrus SASL configuration file in /etc/postfix/sasl/,
+/var/lib/sasl2/ etc. See the distribution-specific
+documentation to determine the expected location.
+
+
+
+
+
+Note
+
+ Cyrus SASL searches /usr/lib/sasl2/ first. If it
+finds the specified configuration file there, it will not examine
+other locations.
+
+
+
+
+
+ As the Postfix SMTP server is linked with the Cyrus SASL library
+libsasl, communication between Postfix and Cyrus SASL
+takes place by calling functions in the SASL library.
+
+ The SASL library may use an external password verification
+service, or an internal plugin to connect to authentication backends
+and verify the SMTP client's authentication data against the system
+password file or other databases.
+
+ The following table shows typical combinations discussed in
+this document:
+
+
+
+
+
+
+
+| authentication backend |
+
+password verification service / plugin |
+
+
+
+
+
+| /etc/shadow |
+
+saslauthd |
+
+
+
+
+
+| PAM |
+
+saslauthd |
+
+
+
+
+
+| IMAP server |
+
+saslauthd |
+
+
+
+
+
+| sasldb |
+
+sasldb |
+
+
+
+
+
+| MySQL, PostgreSQL, SQLite |
+
+sql |
+
+
+
+
+
+| LDAP |
+
+ldapdb |
+
+
+
+
+
+
+
+
+
+Note
+
+ Read the Cyrus SASL documentation for other backends it can
+use.
+
+
+
+
+
+ Communication between the Postfix SMTP server (read: Cyrus SASL's
+libsasl) and the saslauthd server takes
+place over a UNIX-domain socket.
+
+ saslauthd usually establishes the UNIX domain
+socket in /var/run/saslauthd/ and waits for authentication
+requests. The Postfix SMTP server must have read+execute permission
+to this directory or authentication attempts will fail.
+
+
+
+Important
+
+ Some distributions require the user postfix to be
+member of a special group e.g. sasl, otherwise it
+will not be able to access the saslauthd socket
+directory.
+
+
+
+ The following example configures the Cyrus SASL library to
+contact saslauthd as its password verification service:
-% postconf -a (SASL support in the SMTP server)
-% postconf -A (SASL support in the SMTP+LMTP client)
+/etc/sasl2/smtpd.conf:
+ pwcheck_method: saslauthd
+ mech_list: PLAIN LOGIN
- Needless to say, these commands are not available in earlier
-Postfix versions.
+
-
+Important
- These instructions assume that you build Postfix from source
-code as described in the INSTALL document. Some modification may
-be required if you build Postfix from a vendor-specific source
-package.
+ Do not specify any other mechanisms in mech_list
+than PLAIN or LOGIN when using
+saslauthd! It can only handle these two mechanisms,
+and authentication will fail if clients are allowed to choose other
+mechanisms.
- Support for the Dovecot version 1 SASL protocol is available
-in Postfix 2.3 and later. At the time
-of writing, only server-side SASL support is available, so you can't
-use it to authenticate to your network provider's server. Dovecot
-uses its own daemon process for authentication. This keeps the
-Postfix build process simple, because there is no need to link extra
-libraries into Postfix.
+
- To generate the necessary Makefiles, execute the following
-in the Postfix top-level directory:
+
+
+Important
+
+ Plaintext mechanisms (PLAIN, LOGIN)
+send credentials unencrypted. This information should be protected
+by an additional security layer such as a TLS-encrypted SMTP session
+(see: TLS_README).
+
+
+
+ Additionally the saslauthd server itself must be
+configured. It must be told which authentication backend to turn
+to for password verification. The backend is choosen as a command
+line option when saslauthd is started and will be shown
+in the following examples.
+
+
+
+Note
+
+ Some distributions use a configuration file to provide saslauthd
+command line options to set e.g. the authentication backend. Typical
+locations are /etc/sysconfig/saslauthd or
+/etc/default/saslauthd.
+
+
+
+
+
+ Access to the /etc/shadow system password file
+requires root privileges. The Postfix SMTP server
+(and in consequence libsasl linked to the server) runs
+with the least privilege possible. Direct access to
+/etc/shadow would not be possible without breaking the
+Postfix security architecture.
+
+ The saslauthd socket builds a safe bridge. Postfix,
+running as limited user postfix, can access the
+UNIX-domain socket that saslauthd receives commands
+on; saslauthd, running as privileged user root,
+has the privileges required to access the shadow file.
+
+ The saslauthd server verifies passwords against the
+authentication backend /etc/shadow if started like this:
-% make makefiles CCARGS='-DUSE_SASL_AUTH -DDEF_SERVER_SASL_TYPE=\"dovecot\"'
+% saslauthd -a shadow
- After this, proceed with "make" as described in the
-INSTALL document.
+ See section "Testing saslauthd
+authentication" for test instructions.
- Notes:
+
-
-
--
The "-DDEF_SERVER_SASL_TYPE" stuff is not necessary; it just
-makes Postfix configuration a little more convenient because you
-don't have to specify the SASL plug-in type in the Postfix main.cf
-file.
-
- -
If you also want support for LDAP or TLS, you will have to merge
-their CCARGS and AUXLIBS into the above command line.
-
-
-
-
-
- Postfix appears to work with cyrus-sasl-1.5.x or cyrus-sasl-2.1.x,
-which are available from:
+ Cyrus SASL can use the PAM framework to authenticate credentials.
+saslauthd uses the PAM framework when started like
+this:
-ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/
+% saslauthd -a pam
- 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.x or /usr/lib/sasl2 -> /usr/local/lib/sasl2 for
-version 2.1.x.
+
- Reportedly, Microsoft Outlook (Express) requires the
-non-standard LOGIN authentication method. To enable this
-authentication method, specify ``./configure --enable-login''.
+Note
-
+ PAM configuration for the Postfix SMTP server is usually given
+in /etc/pam.d/smtp and is beyond the scope of this
+document.
- These instructions assume that you build Postfix from source
-code as described in the INSTALL document. Some modification may
-be required if you build Postfix from a vendor-specific source
-package.
+
- 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.
+ See section "Testing saslauthd
+authentication" for test instructions.
- On some systems this generates the necessary Makefile definitions:
-
+
+
+ saslauthd can verify the SMTP client credentials
+by using them to log into an IMAP server. If the login succeeds,
+SASL authentication also succeeds. saslauthd contacts
+an IMAP server when started like this:
+
+
+
+% saslauthd -a rimap -O imap.example.com
+
+
+
+
+
+Note
+
+ The option "-O imap.example.com" specifies the
+IMAP server saslauthd should contact when it verifies
+credentials.
+
+
+
+
+
+Important
+
+ saslauthd sends IMAP login information unencrypted.
+Any IMAP session leaving the local host should be protected by an
+additional security layer such as an SSL tunnel.
+
+
+
+ See section "Testing saslauthd
+authentication" for test instructions.
+
+
+
+ Cyrus SASL provides the testsaslauthd utility to
+test saslauthd authentication. The username and password
+are given as command line arguments. The example shows the response
+when authentication is successful:
+
+
+
+% testsaslauthd -u username -p password
+0: OK "Success."
+
+
+
+
+
+Note
+
+ Sometimes the testsaslauthd program is not distributed
+with a the Cyrus SASL main package. In that case, it may be
+distributed with -devel, -dev or -debug packages.
+
+
+
+ Specify an additional "-s smtp" if saslauthd
+was configured to contact the PAM authentication framework and an
+additional "-f /path/to/socketdir/mux" if
+saslauthd establishes the UNIX-domain socket in a
+non-default location.
+
+ If authentication succeeds, proceed with the section "Enabling SASL authentication and authorization
+in the Postfix SMTP server".
+
+
+
+ Cyrus SASL uses a plugin infrastructure (called auxprop)
+to expand libsasl's capabilities. Currently Cyrus
+SASL sources provide three authentication plugins.
+
+
-- (for Cyrus SASL version 1.5.x):
-
-
-
-% make tidy # if you have left-over files from a previous build
-% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include" AUXLIBS="-L/usr/local/lib -lsasl"
-
+ - sasldb
-- (for Cyrus SASL version 2.1.x):
-
-
-
-% make tidy # if you have left-over files from a previous build
-% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib -lsasl2"
-
+-
Accounts are stored stored in a Cyrus SASL Berkeley DB
+database
+
+ - sql
+
+-
Accounts are stored in a SQL database
+
+- ldapdb
+
+-
Accounts are stored stored in an LDAP database
- On Solaris 2.x you need to specify run-time link information,
-otherwise ld.so will not find the SASL shared library:
+
+
+
+
+Important
+
+ These three plugins support shared-secret mechanisms i.e.
+CRAM-MD5, DIGEST-MD5 and NTLM. These mechanisms send credentials
+encrypted but their verification process requires the password to
+be available in plaintext. Consequently passwords cannot (!) be
+stored in encrypted form.
+
+
+
+
+
+ The sasldb auxprop plugin authenticates credentials stored in a Berkeley
+DB database. The database schema is specific to Cyrus SASL. The
+database is usually located at /etc/sasldb2.
+
+
+
+Note
+
+ The sasldb2 file contains passwords in
+plaintext, and should have read+write access only to user
+postfix or a group that postfix is member
+of.
+
+
+
+ The saslpasswd2 command-line utility creates
+and maintains the database:
+
+
+
+% saslpasswd2 -c -u example.com username
+Password:
+Again (for verification):
+
+
+
+ This command creates an account
+username@example.com.
+
+
+
+Important
+
+ users must specify username@example.com
+as login name, not username.
+
+
+
+ Run the following command to reuse the Postfix mydomain
+parameter value as the login domain:
+
+
+
+% saslpasswd2 -c -u `postconf -h mydomain` username
+Password:
+Again (for verification):
+
+
+
+
+
+Note
+
+ Run saslpasswd2 without any options for further
+help on how to use the command.
+
+
+
+ The sasldblistusers2 command lists all existing
+users in the sasldb database:
+
+
+
+% sasldblistusers2
+username1@example.com: password1
+username2@example.com: password2
+
+
+
+ Configure libsasl to use sasldb with the following instructions:
+
+
+
+/etc/sasl2/smtpd.conf:
+ pwcheck_method: auxprop
+ auxprop_plugin: sasldb
+ mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5 NTLM
+
+
+
+
+
+Note
+
+ In the above example adjust mech_list to the
+mechanisms that are applicable for your environment.
+
+
+
+
+
+ The sql auxprop plugin is a generic SQL plugin. It provides
+access to credentials stored in a MySQL, a PostgreSQL or a SQLite
+database.
+
+
+
+Note
+
+ The shared-secret mechanisms (CRAM-MD5, etc.) require that the
+SASL client passwords are stored as plaintext.
+
+
+
+
+
+Tip
+
+
+
+ Use "saslauthd > pam > (pam database module)" to
+verify encrypted passwords in an SQL database.
+
+
+
+ The following example configures libsasl to use the sql plugin and connects
+it to a PostgreSQL server:
+
+
+
+/etc/sasl2/smtpd.conf:
+ pwcheck_method: auxprop
+ auxprop_plugin: sql
+ mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5 NTLM
+ sql_engine: pgsql
+ sql_hostnames: 127.0.0.1, 192.0.2.1 sql_user: username
+ sql_passwd: secret
+ sql_database: dbname
+ sql_select: SELECT password FROM users WHERE user = '%u'@'%r'
+
+
+
+
+
+Note
+
+ Set appropriate permissions if smtpd.conf contains
+a password. The file should be readable by the postfix
+user.
+
+
+
+
+
+Note
+
+ In the above example, adjust mech_list to the
+mechanisms that are applicable for your environment.
+
+
+
+ The sql plugin has the following configuration options:
+
+
-- (for Cyrus SASL version 1.5.x):
-
-
-
-% make tidy # if you have left-over files from a previous build
-% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include" AUXLIBS="-L/usr/local/lib \
- -R/usr/local/lib -lsasl"
-
+ - sql_engine
-- (for Cyrus SASL version 2.1.x):
-
-
-% make tidy # if you have left-over files from a previous build
-% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib \
- -R/usr/local/lib -lsasl2"
-
+
+ Specify mysql to connect to a MySQL server,
+pgsql for a PostgreSQL server or sqlite
+for an SQLite database
+
+
+
+- sql_hostnames
+
+-
+
+
Specify one or more servers (hostname or hostname:port) separated
+by commas.
+
+
+
+Note
+
+ With MySQL servers, specify localhost to connect
+over a UNIX-domain socket, and specify 127.0.0.1 to
+connect over a TCP socket.
+
+
+
+
+
+- sql_user
+
+-
+
+
The login name to gain access to the database.
+
+
+
+- sql_passwd
+
+-
+
+
The password to gain access to the database.
+
+
+
+- sql_database
+
+-
+
+
The name of the database to connect to.
+
+
+
+- sql_select
+
+-
+
+
The SELECT statement that should retrieve the plaintext password
+from a database table.
+
+
+
+Important
+
+ Do not enclose the statement in quotes! Use single quotes to
+escape macros!
+
+
+
+
-
+
- In order to enable SASL support in the Postfix SMTP server:
+ The sql plugin provides macros to build sql_select
+statements. They will be replaced with arguments sent from the client. The
+following macros are available:
+
+
+
+
+
+- %u
+
+-
+
+
The name of the user whose properties are being selected.
+
+
+
+- %p
+
+-
+
+
The name of the property being selected. While this could technically be
+anything, Cyrus SASL will try userPassword and cmusaslsecretMECHNAME (where
+MECHNAME is the name of a SASL mechanism).
+
+
+
+- %r
+
+-
+
+
The name of the realm to which the user belongs. This could be
+the KERBEROS realm, the fully-qualified domain name of the computer
+the SASL application is running on, or the domain after the "@" in a
+username.
+
+
+
+
+
+
+
+
+
+ The ldapdb auxprop plugin provides access to credentials stored
+in an OpenLDAP LDAP server. It is the only plugin that implements
+proxy authorization.
+
+ Proxy authorization in this context means: The ldapdb plugin
+must SASL authenticate with the OpenLDAP server. The server then
+decides if the ldapdb plugin should be authorized to read the
+authenticating user's password. Once the ldapdb plugin has gone
+through proxy authorization it may proceed and authenticate the
+remote SMTP client's credentials.
+
+ In a nutshell: Configuring ldapdb means authentication and
+authorization must be configured twice - once in the Postfix SMTP
+server to authenticate and authorize the remote SMTP client, and
+once in the OpenLDAP slapd server to authenticate and
+authorize the ldapdb plugin.
+
+ This example configures libsasl to use the ldapdb plugin and
+the plugin to connect to an OpenLDAP server:
+
+
+
+/etc/sasl2/smtpd.conf:
+ pwcheck_method: auxprop
+ auxprop_plugin: ldapdb
+ mech_list: PLAIN LOGIN NTLM CRAM-MD5 DIGEST-MD5
+ ldapdb_uri: ldap://localhost
+ ldapdb_id: proxyuser
+ ldapdb_pw: password
+ ldapdb_mech: DIGEST-MD5
+
+
+
+
+
+Important
+
+ Set appropriate permissions if smtpd.conf contains a
+password. The file should be readable by the postfix
+user.
+
+
+
+
+
+Note
+
+ The shared-secret mechanisms (CRAM-MD5, etc.) require that the
+SASL client passwords are stored as plaintext.
+
+
+
+ The following is a summary of applicable smtpd.conf
+file entries:
+
+
+
+
+
+- auxprop_plugin
+
+-
Specify ldapdb to enable the plugin.
+
+- ldapdb_uri
+
+-
Specify either ldapi:// for to connect over
+a UNIX-domain socket, ldap:// for an unencrypted TCP
+connection or ldaps:// for an encrypted TCP connection.
+
+
+- ldapdb_id
+
+-
The login name to authenticate the ldapdb plugin to the
+LDAP server (proxy authorization).
+
+- ldapdb_pw
+
+-
The password (in plaintext) to authenticate the ldapdb
+plugin to the LDAP server (proxy authorization).
+
+- ldapdb_mech
+
+-
The mechanism to authenticate the ldapdb plugin to the
+OpenLDAP slapd server.
+
+
+
+Note
+
+ Specify a mechanism here that is supported by the OpenLDAP slapd
+server.
+
+
+
+
+
+- ldapdb_rc (optional)
+
+-
The path to a file containing individual configuration
+options for the ldapdb LDAP client (libldap). This allows to specify
+a TLS client certificate which in turn can be used to use the SASL
+EXTERNAL mechanism.
+
+
+
+Note
+
+ This mechanism supports authentication over an encrypted transport
+layer, which is recommended if the plugin must connect to an OpenLDAP
+server on a remote machine.
+
+
+
+
+
+- ldapdb_starttls (optional)
+
+-
The TLS policy for connecting to the LDAP server. Specify
+either try or demand. If the option is
+try the plugin will attempt to establish a TLS-encrypted
+connection with the LDAP server, and will fallback to an unencrypted
+connection if TLS fails. If the policy is demand and
+a TLS-encrypted connection cannot be established, the connection
+fails immediately.
+
+
+
+
+
+ When the ldapdb plugin connects to the OpenLDAP server and
+successfully authenticates, the OpenLDAP server decides if the
+plugin user is authorized to read SASL account information.
+
+ The following configuration gives an example of authorization configuration
+in the OpenLDAP slapd server:
+
+
+
+/etc/openldap/slapd.conf:
+ authz-regexp
+ uid=(.*),cn=.*,cn=auth
+ ldap:///dc=example,dc=com??sub?cn=$1
+ authz-policy to
+
+
+
+ Here, the authz-regexp option serves for authentication
+of the ldapdb user. It maps its login name to a DN in the LDAP
+directory tree where slapd can look up the SASL account
+information. The authz-policy options defines the
+authentication policy. In this case it grants authentication
+privileges "to" the ldapdb plugin.
+
+ The last configuration step is to tell the OpenLDAP slapd
+server where ldapdb may search for usernames matching the one given
+by the mail client. The example below adds an additional attribute
+ldapdb user object (here: authzTo because the authz-policy
+is "to") and configures the scope where the login name
+"proxyuser" may search:
+
+
+
+dn: cn=proxyuser,dc=example,dc=com
+changetype: modify
+add: authzTo
+authzTo: dn.regex:uniqueIdentifier=(.*),ou=people,dc=example,dc=com
+
+
+
+ Use the ldapmodify or ldapadd command
+to add the above attribute.
+
+
+
+Note
+
+ Read the chapter "Using SASL" in the OpenLDAP Admin Guide
+for more detailed instructions to set up SASL authentication in
+OpenLDAP.
+
+
+
+
+
+ By default the Postfix SMTP server uses the Cyrus SASL
+implementation. If the Dovecot SASL implementation should be used,
+specify an smtpd_sasl_type value of dovecot
+instead of cyrus:
+
+
+
+/etc/postfix/main.cf:
+ smtpd_sasl_type = dovecot
+
+
+
+ Additionally set the path where the Postfix SMTP server can
+find the Dovecot SASL socket:
+
+
+
+/etc/postfix/main.cf:
+ smtpd_sasl_path = private/auth
+
+
+
+
+
+Note
+
+ This example uses a pathname relative to the Postfix queue
+directory, so that it will work whether or not the Postfix SMTP
+server runs chrooted.
+
+
+
+
+
+ Regardless of the SASL implementation type, enabling SMTP
+authentication in the Postfix SMTP server always requires seting
+the smtpd_sasl_auth_enable option:
@@ -250,38 +1124,32 @@ SMTP server
- In order to allow mail relaying by authenticated remote SMTP
-clients:
+ After a "postfix reload", SMTP clients will see the additional
+capability AUTH in an SMTP session, followed by a list of
+authentication mechanisms the server supports:
-/etc/postfix/main.cf:
- smtpd_recipient_restrictions =
- permit_mynetworks
- permit_sasl_authenticated
- reject_unauth_destination
+% telnet server.example.com 25
+...
+220 server.example.com ESMTP Postfix
+EHLO client.example.com
+250-server.example.com
+250-PIPELINING
+250-SIZE 10240000
+250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
+...
- To report SASL login names in Received: message headers
-(Postfix version 2.3 and later):
+ However not all clients recognize the AUTH capability as defined
+by the SASL authentication RFC. Some historical implementations expect the
+server to send an "=" as separator between the AUTH
+verb and the list of mechanisms that follows it.
-
-
-/etc/postfix/main.cf:
- smtpd_sasl_authenticated_header = yes
-
-
-
- Note: the SASL login names will be shared with the entire world.
-
-
- 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=mechanism-list" instead of
-"250 AUTH mechanism-list". To accommodate such clients (in addition
-to conformant
-clients) use the following:
+ The broken_sasl_auth_clients configuration option
+lets Postfix repeat the AUTH statement in a form that these broken
+clients understand:
@@ -290,454 +1158,507 @@ clients) use the following:
-
+
- Dovecot SASL support is available in Postfix 2.3 and later. On
-the Postfix side you need to specify the location of the
-Dovecot authentication daemon socket. We use a pathname relative
-to the Postfix queue directory, so that it will work whether or not
-the Postfix SMTP server runs chrooted:
+Note
+
+ Enable this option for Outlook up to and including version 2003
+and Outlook Express up to version 6. This option does not hurt other
+clients.
+
+
+
+ After "postfix reload", the Postfix SMTP server will propagate
+the AUTH capability twice - once for compliant and once for broken
+clients:
+
+
+
+% telnet server.example.com 25
+...
+EHLO client.example.com
+250-server.example.com
+250-PIPELINING
+250-SIZE 10240000
+250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
+250-AUTH=DIGEST-MD5 PLAIN CRAM-MD5
+...
+
+
+
+
+
+ The Postfix SMTP server provides a way to specify the properties
+of SASL mechanisms that can be made available to the remote SMTP
+client.
+
+
+
+ The default policy is to allow any mechanism in the Postfix SMTP server
+except for those based on anonymous authentication:
/etc/postfix/main.cf:
- smtpd_sasl_type = dovecot
- smtpd_sasl_path = private/auth
+ # Specify a list of properties separated by comma or whitespace
+ smtpd_sasl_security_options = noanonymous
- On the Dovecot side you also need to specify the Dovecot
-authentication daemon socket. In this case we specify an
-absolute pathname. In the example we assume that the
-Postfix queue is under /var/spool/postfix/.
-
-
-/some/where/dovecot.conf:
- auth default {
- mechanisms = plain login
- passdb pam {
- }
- userdb passwd {
- }
- socket listen {
- client {
- path = /var/spool/postfix/private/auth
- mode = 0660
- user = postfix
- group = postfix
- }
- }
- }
-
+
+Important
+
+ Always set at least the noanonymous option.
+Otherwise, the Postfix SMTP server can give strangers the same
+authorization as a properly-authenticated client.
+
- See the Dovecot documentation for how to configure and operate
-the Dovecot authentication server.
+ Postfix can enforce the following policies on SASL authentication
+mechanisms:
-
+
- You need to configure how the Cyrus SASL library should
-authenticate a remote SMTP client's username and password. These
-settings must
-be stored in a separate configuration file.
+
- The name of the configuration file (default: smtpd.conf) will
-be constructed from a value that the Postfix SMTP server sends to
-the Cyrus SASL
-library, which adds the suffix .conf. The value is configured using
-one of the following variables:
+- noanonymous
+
+-
Don't use mechanisms that permit anonymous authentication.
+
+
+- noplaintext
+
+-
Don't use mechanisms that transmit unencrypted username
+and password information.
+
+- nodictionary
+
+-
Don't use mechanisms that are vulnerable to dictionary
+attacks.
+
+
+
+- forward_secrecy
+
+-
Use only mechanisms that support forward secrecy (Dovecot
+SASL only).
+
+
+
+- mutual_auth
+
+-
Use only mechanisms that authenticate both the client and
+the server to each other.
+
+
+
+
+
+
+
+ A separate parameter controls Postfix SASL mechanism policy
+during a TLS-encrypted SMTP session. The default is to copy the
+settings from the unencrypted session:
/etc/postfix/main.cf:
- # Postfix 2.3 and later
- smtpd_sasl_path = smtpd
- # Postfix < 2.3
- smtpd_sasl_application_name = smtpd
+ smtpd_sasl_tls_security_options = $smtpd_sasl_security_options
- Cyrus SASL searches for the configuration file in /usr/local/lib/sasl/
-(Cyrus SASL version 1.5.5) or /usr/local/lib/sasl2/ (Cyrus SASL
-version 2.1.x).
+ A more sophisticated policy allows plaintext mechanisms, but
+only over a TLS-encrypted connection:
- Note: some Postfix distributions are modified and look for
-the smtpd.conf file in /etc/postfix/sasl.
+
+
+/etc/postfix/main.cf:
+ smtpd_sasl_security_options = noanonymous, noplaintext
+ smtpd_sasl_tls_security_options = noanonymous
+
+
- Note: some Cyrus SASL distributions look for the smtpd.conf
-file in /etc/sasl2.
+ To offer SASL authentication only after a TLS-encrypted session has been
+established specify this:
+
+
+
+/etc/postfix/main.cf:
+ smtpd_tls_auth_only = yes
+
+
+
+
+
+ After the client has authenticated with SASL, the Postfix SMTP
+server decides what the remote SMTP client will be authorized
+for. Examples of possible SMTP clients authorizations are:
- IMPORTANT: pwcheck establishes a UNIX domain socket in /var/pwcheck
-and waits for authentication requests. The Postfix SMTP server must have
-read+execute permission to this directory or authentication attempts
-will fail.
+ These permissions are not enabled by default.
- The pwcheck daemon is contained in the cyrus-sasl source tarball.
+
- (Cyrus SASL version 1.5.26)
-
-
-/usr/local/lib/sasl/smtpd.conf:
- pwcheck_method: saslauthd
-
-
- (Cyrus SASL version 2.1.x)
-
-
-/usr/local/lib/sasl2/smtpd.conf:
- pwcheck_method: saslauthd
- mech_list: PLAIN LOGIN
-
-
-
-
- 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. To use PAM,
-start saslauthd with "-a pam".
-
- IMPORTANT: saslauthd usually establishes a UNIX domain socket
-in /var/run/saslauthd and waits for authentication requests. The Postfix
-SMTP server must have read+execute permission to this directory or
-authentication attempts will fail.
-
- Note: The directory where saslauthd puts the socket is configurable.
-See the command-line option "-m /path/to/socket" in the saslauthd
---help listing.
-
- To authenticate against Cyrus SASL's own password database:
-
-
-- (Cyrus SASL version 1.5.x)
-
-
-
-/usr/local/lib/sasl/smtpd.conf:
- pwcheck_method: sasldb
-
-
- - (Cyrus SASL version 2.1.x)
-
-
-
-/usr/local/lib/sasl2/smtpd.conf:
- pwcheck_method: auxprop
- auxprop_plugin: sasldb
- mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5
-
-
-
-
- This will use the Cyrus SASL password file (default: /etc/sasldb in
-version 1.5.x, or /etc/sasldb2 in version 2.1.x), 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. With the OTP authentication mechanism,
-the Postfix SMTP server also needs WRITE access to /etc/sasldb2 or
-/etc/sasldb
-(or the back end SQL database, if used).
-
- IMPORTANT: To get sasldb running, make sure that you set the SASL
-domain (realm) to a fully qualified domain name.
-
- EXAMPLE:
-
-
-- (Cyrus SASL version 1.5.x)
-
-
-
-% saslpasswd -c -u `postconf -h myhostname` exampleuser
-
-
- - (Cyrus SASL version 2.1.x)
-
-
-
-% saslpasswd2 -c -u `postconf -h myhostname` exampleuser
-
-
-
-
- You can find out SASL's idea about the realms of the users
-in sasldb with sasldblistusers (Cyrus SASL version 1.5.x) or
-sasldblistusers2 (Cyrus SASL version 2.1.x).
-
- On the Postfix side, you can have only one realm per smtpd(8)
-instance, and only the users belonging to that realm would be able to
-authenticate. The Postfix variable smtpd_sasl_local_domain controls the
-realm used by smtpd(8):
+ The permit_sasl_authenticated restriction allows
+SASL-authenticated SMTP clients to send mail to remote destinations.
+Add it to the list of smtpd_recipient_restrictions as
+follows:
/etc/postfix/main.cf:
- smtpd_sasl_local_domain = $myhostname
+ smtpd_recipient_restrictions =
+ ...
+ permit_mynetworks
+ permit_sasl_authenticated
+ reject_unauth_destination
+ ...
-
+
- IMPORTANT: The Cyrus SASL password verification services pwcheck
-and saslauthd can only support the plaintext mechanisms PLAIN or
-LOGIN. However, the Cyrus SASL library doesn't know this, and will
-happily advertise other authentication mechanisms that the SASL
-library implements, such as DIGEST-MD5. As a result, if a remote SMTP
-client chooses any mechanism other than PLAIN or LOGIN while pwcheck
-or saslauthd are used, authentication will fail. Thus you may need
-to limit the list of mechanisms advertised by the Postfix SMTP
-server.
+ By default an SMTP client may specify any envelope sender address
+in the MAIL FROM command. That is because the Postfix SMTP server
+only knows the remte SMTP client hostname and IP address, but not
+the user who controls the remote SMTP client.
-
-
--
With older Cyrus SASL versions you remove the corresponding
-library files from the SASL plug-in directory (and again whenever
-the system is updated).
-
- -
With Cyrus SASL version 2.1.x or later the mech_list variable
-can specify a list of authentication mechanisms that Cyrus SASL may
-offer:
+ This changes the moment an SMTP client uses SASL authentication.
+Now, the Postfix SMTP server knows who the sender is. Given a table
+of envelope sender addresses and SASL login names, the Postfix SMTP
+server can decide if the SASL authenticated client is allowed to
+use a particular envelope sender address:
-/usr/local/lib/sasl2/smtpd.conf:
- mech_list: plain login
+/etc/postfix/main.cf:
+ smtpd_sender_login_maps = hash:/etc/postfix/controlled_envelope_senders
+
+ smtpd_recipient_restrictions =
+ ...
+ reject_sender_login_mismatch
+ permit_sasl_authenticated
+ permit_mynetworks
+ reject_unauth_destination
+ ...
-
-
- For the same reasons you might want to limit the list of plugins
-used for authentication.
-
-
-
--
With Cyrus SASL version 1.5.x your only choice is to
-delete the corresponding library files from the SASL plug-in
-directory.
-
- -
With SASL version 2.1.x:
+ The controlled_envelope_senders table specifies
+the binding between the sender envelope addresses and its their
+SASL login names:
-/usr/local/lib/sasl2/smtpd.conf:
- pwcheck_method: auxprop
- auxprop_plugin: sql
+/etc/postfix/controlled_envelope_senders
+ # envelope sender owners (SASL login names)
+ john@example.com john@example.com
+ helpdesk@example.com john@example.com, mary@example.com
+ postmaster admin@example.com
+ @example.net barney, fred, john@example.com, mary@example.com
-
+ With this, the reject_sender_login_mismatch
+restriction above will reject the sender address in the MAIL FROM
+command if smtpd_sender_login_maps does not specify
+the SMTP client's login name as an owner of that address.
- To run software chrooted with SASL support is an interesting
-exercise. It probably is not worth the trouble.
+ See also reject_authenticated_sender_login_mismatch and
+reject_unauthenticated_sender_login_mismatch for additional
+control over the SASL login name and the envelope sender.
-
+
- To test the server side, connect (for example, with telnet) to the
-Postfix SMTP server port and you should
-be able to have a conversation as shown below. Information sent by the
-client (that is, you) is shown in bold font.
+ Postfix provides a wide range of SASL authentication configuration
+options. The next section lists a few that are discussed frequently.
+See postconf(5) for a complete list.
+
+
+
+ Postfix can append a domain name (or any other string) to a
+SASL login name that does not have a domain part, e.g. "john"
+instead of "john@example.com":
-$ telnet server.example.com 25
-. . .
+/etc/postfix/main.cf:
+ smtpd_sasl_local_domain = example.com
+
+
+
+ This is useful as a default setting and safety net for misconfigured
+clients, or during a migration to an authentication method/backend
+that requires an authentication REALM or domain name, before all
+SMTP clients are configured to send such information.
+
+
+
+ Some clients insist on using SASL authentication if it is offered, even
+when they are not configured to send credentials - and therefore
+they will always fail and disconnect.
+
+ Postfix can hide the AUTH capability from these clients/networks:
+
+
+
+/etc/postfix/main.cf:
+ smtpd_sasl_exceptions_networks = !192.0.2.171/32, 192.0.2.0/24
+
+
+
+
+
+ To report SASL login names in Received: message headers (Postfix
+version 2.3 and later):
+
+
+
+/etc/postfix/main.cf:
+ smtpd_sasl_authenticated_header = yes
+
+
+
+
+
+Note
+
+ The SASL login names will be shared with the entire world.
+
+
+
+
+
+ To test the server side, connect (for example, with
+telnet) to the Postfix SMTP server port and you should
+be able to have a conversation as shown below. Information sent by
+the client (that is, you) is shown in bold font.
+
+
+
+% telnet server.example.com 25
+...
220 server.example.com ESMTP Postfix
-EHLO client.example.com
+EHLO client.example.com
250-server.example.com
250-PIPELINING
250-SIZE 10240000
250-ETRN
250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
250 8BITMIME
-AUTH PLAIN AHRlc3QAdGVzdHBhc3M=
+AUTH PLAIN AHRlc3QAdGVzdHBhc3M=
235 Authentication successful
- Instead of AHRlc3QAdGVzdHBhc3M=, specify the base64 encoded
-form of \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:
-
+ Instead of AHRlc3QAdGVzdHBhc3M=, specify the
+base64-encoded form of \0username\0password (the \0
+is a null byte). The example above is for a user named `test'
+with password `testpass'.
-
-% printf '\0username\0password' | mmencode
-
-
-
-
-% perl -MMIME::Base64 -e \
- 'print encode_base64("\0username\0password");'
-
-
+Caution
- The mmencode command is part of the metamail software.
-MIME::Base64 is available from http://www.cpan.org/.
-
- Caution: when posting logs of the SASL negotiations to public
-lists,
+
When posting logs of the SASL negotiations to public lists,
please keep in mind that username/password information is trivial
to recover from the base64-encoded form.
-
+