summaryrefslogtreecommitdiffstats
path: root/README_FILES/SASL_README
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--README_FILES/SASL_README1422
1 files changed, 1422 insertions, 0 deletions
diff --git a/README_FILES/SASL_README b/README_FILES/SASL_README
new file mode 100644
index 0000000..94a377e
--- /dev/null
+++ b/README_FILES/SASL_README
@@ -0,0 +1,1422 @@
+PPoossttffiixx SSAASSLL HHoowwttoo
+
+-------------------------------------------------------------------------------
+
+HHooww PPoossttffiixx uusseess SSAASSLL aauutthheennttiiccaattiioonn
+
+SMTP servers need to decide whether an SMTP client is authorized to send mail
+to remote destinations, or only to destinations that the server itself is
+responsible for. Usually, SMTP servers accept mail to remote destinations when
+the client's IP address is in the "same network" as the server's IP address.
+
+SMTP clients outside the SMTP server's network need a different way to get
+"same network" privileges. To address this need, 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 a client is authenticated, a server
+can give it "same network" privileges.
+
+Postfix does not implement SASL itself, but instead uses existing
+implementations as building blocks. This means that some SASL-related
+configuration files will belong to Postfix, while other configuration files
+belong to the specific SASL implementation that Postfix will use. This document
+covers both the Postfix and non-Postfix configuration.
+
+NOTE: 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 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.
+
+You can read more about the following topics:
+
+ * Configuring SASL authentication in the Postfix SMTP server
+ * Configuring SASL authentication in the Postfix SMTP/LMTP client
+ * Building Postfix with SASL support
+ * Using Cyrus SASL version 1.5.x
+ * Credits
+
+CCoonnffiigguurriinngg SSAASSLL aauutthheennttiiccaattiioonn iinn tthhee PPoossttffiixx SSMMTTPP sseerrvveerr
+
+As mentioned earlier, SASL is implemented separately from Postfix. For this
+reason, configuring SASL authentication in the Postfix SMTP server involves two
+different steps:
+
+ * 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.
+
+ * 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.
+
+Successful authentication in the Postfix SMTP server requires a functional SASL
+framework. Configuring SASL should therefore always be the first step, before
+configuring Postfix.
+
+You can read more about the following topics:
+
+ * Which SASL Implementations are supported?
+ * Configuring Dovecot SASL
+
+ o Postfix to Dovecot SASL communication
+
+ * Configuring Cyrus SASL
+
+ o Cyrus SASL configuration file name
+ o Cyrus SASL configuration file location
+ o Postfix to Cyrus SASL communication
+
+ * Enabling SASL authentication and authorization in the Postfix SMTP server
+
+ o Enabling SASL authentication in the Postfix SMTP server
+ o Postfix SMTP Server policy - SASL mechanism properties
+ o Enabling SASL authorization in the Postfix SMTP server
+ o Additional SMTP Server SASL options
+
+ * Testing SASL authentication in the Postfix SMTP server
+
+WWhhiicchh SSAASSLL IImmpplleemmeennttaattiioonnss aarree ssuuppppoorrtteedd??
+
+Currently the Postfix SMTP server supports the Cyrus SASL and Dovecot SASL
+implementations.
+
+ NNoottee
+
+ Current Postfix versions have a plug-in architecture that can support
+ multiple SASL implementations. Before Postfix version 2.3, Postfix had
+ support only for Cyrus SASL.
+
+To find out what SASL implementations are compiled into Postfix, use the
+following commands:
+
+ % ppoossttccoonnff --aa (SASL support in the SMTP server)
+ % ppoossttccoonnff --AA (SASL support in the SMTP+LMTP client)
+
+These commands are available only with Postfix version 2.3 and later.
+
+CCoonnffiigguurriinngg DDoovveeccoott SSAASSLL
+
+Dovecot is a POP/IMAP server that has its own configuration to authenticate
+POP/IMAP clients. When the Postfix SMTP server uses Dovecot SASL, it reuses
+parts of this configuration. Consult the Dovecot documentation for how to
+configure and operate the Dovecot authentication server.
+
+PPoossttffiixx ttoo DDoovveeccoott SSAASSLL ccoommmmuunniiccaattiioonn
+
+Communication between the Postfix SMTP server and Dovecot SASL happens over a
+UNIX-domain socket or over a TCP socket. We will be using a UNIX-domain socket
+for better privacy.
+
+The following fragment for Dovecot version 2 assumes that the Postfix queue is
+under /var/spool/postfix/.
+
+ 1 conf.d/10-master.conf:
+ 2 service auth {
+ 3 ...
+ 4 unix_listener /var/spool/postfix/private/auth {
+ 5 mode = 0660
+ 6 # Assuming the default Postfix user and group
+ 7 user = postfix
+ 8 group = postfix
+ 9 }
+ 10 ...
+ 11 }
+ 12
+ 13 conf.d/10-auth.conf
+ 14 auth_mechanisms = plain login
+
+Line 4 places the Dovecot SASL socket in /var/spool/postfix/private/auth, lines
+5-8 limit read+write permissions to user and group postfix only, and line 14
+provides plain and login as mechanisms for the Postfix SMTP server.
+
+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.
+
+CCoonnffiigguurriinngg CCyyrruuss SSAASSLL
+
+The Cyrus SASL framework supports a wide variety of applications (POP, IMAP,
+SMTP, etc.). 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.
+
+CCyyrruuss SSAASSLL ccoonnffiigguurraattiioonn ffiillee nnaammee
+
+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
+
+CCyyrruuss SSAASSLL ccoonnffiigguurraattiioonn ffiillee llooccaattiioonn
+
+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.
+
+ NNoottee
+
+ Cyrus SASL searches /usr/lib/sasl2/ first. If it finds the specified
+ configuration file there, it will not examine other locations.
+
+PPoossttffiixx ttoo CCyyrruuss SSAASSLL ccoommmmuunniiccaattiioonn
+
+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:
+
+ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
+ | aauutthheennttiiccaattiioonn bbaacckkeenndd |ppaasssswwoorrdd vveerriiffiiccaattiioonn sseerrvviiccee // pplluuggiinn|
+ |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |/etc/shadow |saslauthd |
+ |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |PAM |saslauthd |
+ |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |IMAP server |saslauthd |
+ |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |sasldb |sasldb |
+ |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |MySQL, PostgreSQL, SQLite|sql |
+ |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |LDAP |ldapdb |
+ |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+
+ NNoottee
+
+ Read the Cyrus SASL documentation for other backends it can use.
+
+ssaassllaauutthhdd -- CCyyrruuss SSAASSLL ppaasssswwoorrdd vveerriiffiiccaattiioonn sseerrvviiccee
+
+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.
+
+ IImmppoorrttaanntt
+
+ 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:
+
+ /etc/sasl2/smtpd.conf:
+ pwcheck_method: saslauthd
+ mech_list: PLAIN LOGIN
+
+ IImmppoorrttaanntt
+
+ 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.
+
+ IImmppoorrttaanntt
+
+ 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 selected with a saslauthd command-line option and will be shown in the
+following examples.
+
+ NNoottee
+
+ 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.
+
+UUssiinngg ssaassllaauutthhdd wwiitthh //eettcc//sshhaaddooww
+
+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:
+
+ % ssaassllaauutthhdd --aa sshhaaddooww
+
+See section "Testing saslauthd authentication" for test instructions.
+
+UUssiinngg ssaassllaauutthhdd wwiitthh PPAAMM
+
+Cyrus SASL can use the PAM framework to authenticate credentials. saslauthd
+uses the PAM framework when started like this:
+
+ % ssaassllaauutthhdd --aa ppaamm
+
+ NNoottee
+
+ PAM configuration for the Postfix SMTP server is usually given in /etc/
+ pam.d/smtp and is beyond the scope of this document.
+
+See section "Testing saslauthd authentication" for test instructions.
+
+UUssiinngg ssaassllaauutthhdd wwiitthh aann IIMMAAPP sseerrvveerr
+
+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:
+
+ % ssaassllaauutthhdd --aa rriimmaapp --OO iimmaapp..eexxaammppllee..ccoomm
+
+ NNoottee
+
+ The option "-O imap.example.com" specifies the IMAP server saslauthd should
+ contact when it verifies credentials.
+
+ IImmppoorrttaanntt
+
+ 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.
+
+TTeessttiinngg ssaassllaauutthhdd aauutthheennttiiccaattiioonn
+
+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:
+
+ % tteessttssaassllaauutthhdd --uu uusseerrnnaammee --pp ppaasssswwoorrdd
+ 0: OK "Success."
+
+ NNoottee
+
+ 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 specify an additional "-f //ppaatthh//ttoo//ssoocckkeettddiirr//mmuuxx"
+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".
+
+CCyyrruuss SSAASSLL PPlluuggiinnss -- aauuxxiilliiaarryy pprrooppeerrttyy pplluuggiinnss
+
+Cyrus SASL uses a plugin infrastructure (called auxprop) to expand libsasl's
+capabilities. Currently Cyrus SASL sources provide three authentication
+plugins.
+
+ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
+ |PPlluuggiinn|DDeessccrriippttiioonn |
+ |_ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |sasldb|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 |
+ |_ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+
+ IImmppoorrttaanntt
+
+ 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.
+
+TThhee ssaassllddbb pplluuggiinn
+
+The sasldb auxprop plugin authenticates SASL clients against credentials that
+are stored in a Berkeley DB database. The database schema is specific to Cyrus
+SASL. The database is usually located at /etc/sasldb2.
+
+ NNoottee
+
+ 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:
+
+ % ssaassllppaasssswwdd22 --cc --uu eexxaammppllee..ccoomm uusseerrnnaammee
+ Password:
+ Again (for verification):
+
+This command creates an account uusseerrnnaammee@@eexxaammppllee..ccoomm.
+
+ IImmppoorrttaanntt
+
+ users must specify uusseerrnnaammee@@eexxaammppllee..ccoomm as login name, not uusseerrnnaammee.
+
+Run the following command to reuse the Postfix mydomain parameter value as the
+login domain:
+
+ % ssaassllppaasssswwdd22 --cc --uu ``ppoossttccoonnff --hh mmyyddoommaaiinn`` uusseerrnnaammee
+ Password:
+ Again (for verification):
+
+ NNoottee
+
+ 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:
+
+ % ssaassllddbblliissttuusseerrss22
+ 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
+
+ NNoottee
+
+ In the above example adjust mech_list to the mechanisms that are applicable
+ for your environment.
+
+TThhee ssqqll pplluuggiinn
+
+The sql auxprop plugin is a generic SQL plugin. It provides access to
+credentials stored in a MySQL, PostgreSQL or SQLite database. This plugin
+requires that SASL client passwords are stored as plaintext.
+
+ TTiipp
+
+ If you must store encrypted passwords, you cannot use the sql auxprop
+ plugin. Instead, see section "Using saslauthd with PAM", and configure PAM
+ to look up the encrypted passwords with, for example, the pam_mysql module.
+ You will not be able to use any of the methods that require access to
+ plaintext passwords, such as the shared-secret methods CRAM-MD5 and DIGEST-
+ MD5.
+
+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'
+
+ NNoottee
+
+ Set appropriate permissions if smtpd.conf contains a password. The file
+ should be readable by the postfix user.
+
+ NNoottee
+
+ In the above example, adjust mech_list to the mechanisms that are
+ applicable for your environment.
+
+The sql plugin has the following configuration options:
+
+ sql_engine
+ 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.
+
+ NNoottee
+
+ 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.
+
+ IImmppoorrttaanntt
+
+ Do not enclose the statement in quotes! Use single quotes to escape
+ macros!
+
+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.
+
+TThhee llddaappddbb pplluuggiinn
+
+The ldapdb auxprop plugin provides access to credentials stored in an LDAP
+server. This plugin requires that SASL client passwords are stored as
+plaintext.
+
+ TTiipp
+
+ If you must store encrypted passwords, you cannot use the ldapdb auxprop
+ plugin. Instead, you can use "saslauthd -a ldap" to query the LDAP database
+ directly, with appropriate configuration in saslauthd.conf, as described
+ here. You will not be able to use any of the methods that require access to
+ plaintext passwords, such as the shared-secret methods CRAM-MD5 and DIGEST-
+ MD5.
+
+The ldapdb plugin implements proxy authorization. This means that the ldapdb
+plugin uses its own username and password to authenticate with the LDAP server,
+before it asks the LDAP server for the remote SMTP client's password. The LDAP
+server then decides if the ldapdb plugin is authorized to read the remote SMTP
+client's password.
+
+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 LDAP server to authenticate
+and authorize the ldapdb plugin.
+
+This example configures libsasl to use the ldapdb plugin and the plugin to
+connect to an LDAP 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
+
+ IImmppoorrttaanntt
+
+ Set appropriate permissions if smtpd.conf contains a password. The file
+ should be readable by the postfix user.
+
+ NNoottee
+
+ 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:// 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 LDAP server.
+
+ NNoottee
+
+ Specify a mechanism here that is supported by the LDAP 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.
+
+ NNoottee
+
+ 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.
+
+ NNoottee
+
+ Read the chapter "Using SASL" in the OpenLDAP Admin Guide for more detailed
+ instructions to set up SASL authentication in OpenLDAP.
+
+EEnnaabblliinngg SSAASSLL aauutthheennttiiccaattiioonn aanndd aauutthhoorriizzaattiioonn iinn tthhee PPoossttffiixx SSMMTTPP sseerrvveerr
+
+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 specify how Postfix SMTP server can find the Dovecot
+authentication server. This depends on the settings that you have selected in
+the section "Postfix to Dovecot SASL communication".
+
+ * If you configured Dovecot for UNIX-domain socket communication, configure
+ Postfix as follows:
+
+ /etc/postfix/main.cf:
+ smtpd_sasl_path = private/auth
+
+ NNoottee
+ 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.
+
+ * If you configured Dovecot for TCP socket communication, configure Postfix
+ as follows. If Dovecot runs on a different machine, replace 127.0.0.1 by
+ that machine's IP address.
+
+ /etc/postfix/main.cf:
+ smtpd_sasl_path = inet:127.0.0.1:12345
+
+ NNoottee
+ If you specify a remote IP address, information will be sent as plaintext
+ over the network.
+
+EEnnaabblliinngg SSAASSLL aauutthheennttiiccaattiioonn iinn tthhee PPoossttffiixx SSMMTTPP sseerrvveerr
+
+Regardless of the SASL implementation type, enabling SMTP authentication in the
+Postfix SMTP server always requires setting the smtpd_sasl_auth_enable option:
+
+ /etc/postfix/main.cf:
+ smtpd_sasl_auth_enable = yes
+
+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:
+
+ % tteellnneett sseerrvveerr..eexxaammppllee..ccoomm 2255
+ ...
+ 220 server.example.com ESMTP Postfix
+ EEHHLLOO cclliieenntt..eexxaammppllee..ccoomm
+ 250-server.example.com
+ 250-PIPELINING
+ 250-SIZE 10240000
+ 250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
+ ...
+
+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.
+
+The broken_sasl_auth_clients configuration option lets Postfix repeat the AUTH
+statement in a form that these broken clients understand:
+
+ /etc/postfix/main.cf:
+ broken_sasl_auth_clients = yes
+
+ NNoottee
+
+ 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:
+
+ % tteellnneett sseerrvveerr..eexxaammppllee..ccoomm 2255
+ ...
+ 220 server.example.com ESMTP Postfix
+ EEHHLLOO cclliieenntt..eexxaammppllee..ccoomm
+ 250-server.example.com
+ 250-PIPELINING
+ 250-SIZE 10240000
+ 250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
+ 250-AUTH=DIGEST-MD5 PLAIN CRAM-MD5
+ ...
+
+PPoossttffiixx SSMMTTPP SSeerrvveerr ppoolliiccyy -- SSAASSLL mmeecchhaanniissmm pprrooppeerrttiieess
+
+The Postfix SMTP server supports policies that limit the SASL mechanisms that
+it makes available to clients, based on the properties of those mechanisms. The
+next two sections give examples of how these policies are used.
+
+ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
+ |PPrrooppeerrttyy |DDeessccrriippttiioonn |
+ |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |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|Require forward secrecy between sessions (breaking one |
+ | |session does not break earlier sessions). |
+ |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |mutual_auth |Use only mechanisms that authenticate both the client and|
+ | |the server to each other. |
+ |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+
+UUnneennccrryypptteedd SSMMTTPP sseessssiioonn
+
+The default policy is to allow any mechanism in the Postfix SMTP server except
+for those based on anonymous authentication:
+
+ /etc/postfix/main.cf:
+ # Specify a list of properties separated by comma or whitespace
+ smtpd_sasl_security_options = noanonymous
+
+ IImmppoorrttaanntt
+
+ Always set at least the noanonymous option. Otherwise, the Postfix SMTP
+ server can give strangers the same authorization as a properly-
+ authenticated client.
+
+EEnnccrryypptteedd SSMMTTPP sseessssiioonn ((TTLLSS))
+
+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:
+ smtpd_sasl_tls_security_options = $smtpd_sasl_security_options
+
+A more sophisticated policy allows plaintext mechanisms, but only over a TLS-
+encrypted connection:
+
+ /etc/postfix/main.cf:
+ smtpd_sasl_security_options = noanonymous, noplaintext
+ smtpd_sasl_tls_security_options = noanonymous
+
+To offer SASL authentication only after a TLS-encrypted session has been
+established specify this:
+
+ /etc/postfix/main.cf:
+ smtpd_tls_auth_only = yes
+
+EEnnaabblliinngg SSAASSLL aauutthhoorriizzaattiioonn iinn tthhee PPoossttffiixx SSMMTTPP sseerrvveerr
+
+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:
+
+ * Send a message to a remote recipient.
+
+ * Use a specific envelope sender in the MAIL FROM command.
+
+These permissions are not enabled by default.
+
+MMaaiill rreellaayy aauutthhoorriizzaattiioonn
+
+With permit_sasl_authenticated the Postfix SMTP server can allow SASL-
+authenticated SMTP clients to send mail to remote destinations. Examples:
+
+ # With Postfix 2.10 and later, the mail relay policy is
+ # preferably specified under smtpd_relay_restrictions.
+ /etc/postfix/main.cf:
+ smtpd_relay_restrictions =
+ permit_mynetworks
+ ppeerrmmiitt__ssaassll__aauutthheennttiiccaatteedd
+ reject_unauth_destination
+
+ # Older configurations combine relay control and spam control under
+ # smtpd_recipient_restrictions. To use this example with Postfix >=
+ # 2.10 specify "smtpd_relay_restrictions=".
+ /etc/postfix/main.cf:
+ smtpd_recipient_restrictions =
+ permit_mynetworks
+ ppeerrmmiitt__ssaassll__aauutthheennttiiccaatteedd
+ reject_unauth_destination
+ ...other rules...
+
+EEnnvveellooppee sseennddeerr aaddddrreessss aauutthhoorriizzaattiioonn
+
+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 remote
+SMTP client hostname and IP address, but not the user who controls the remote
+SMTP client.
+
+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:
+
+ /etc/postfix/main.cf:
+ ssmmttppdd__sseennddeerr__llooggiinn__mmaappss == hhaasshh:://eettcc//ppoossttffiixx//ccoonnttrroolllleedd__eennvveellooppee__sseennddeerrss
+
+ smtpd_recipient_restrictions =
+ ...
+ rreejjeecctt__sseennddeerr__llooggiinn__mmiissmmaattcchh
+ permit_sasl_authenticated
+ ...
+
+The controlled_envelope_senders table specifies the binding between a sender
+envelope address and the SASL login names that own that address:
+
+ /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.
+
+See also reject_authenticated_sender_login_mismatch,
+reject_known_sender_login_mismatch, and
+reject_unauthenticated_sender_login_mismatch for additional control over the
+SASL login name and the envelope sender.
+
+AAddddiittiioonnaall SSMMTTPP SSeerrvveerr SSAASSLL ooppttiioonnss
+
+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.
+
+PPeerr--aaccccoouunntt aacccceessss ccoonnttrrooll
+
+Postfix can implement policies that depend on the SASL login name (Postfix 2.11
+and later). Typically this is used to HOLD or REJECT mail from accounts whose
+credentials have been compromised.
+
+ /etc/postfix/main.cf:
+ smtpd_recipient_restrictions =
+ permit_mynetworks
+ check_sasl_access hash:/etc/postfix/sasl_access
+ permit_sasl_authenticated
+ ...
+
+ /etc/postfix/sasl_access:
+ # Use this when smtpd_sasl_local_domain is empty.
+ username HOLD
+ # Use this when smtpd_sasl_local_domain=example.com.
+ username@example.com HOLD
+
+DDeeffaauulltt aauutthheennttiiccaattiioonn ddoommaaiinn
+
+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":
+
+ /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.
+
+HHiiddiinngg SSAASSLL aauutthheennttiiccaattiioonn ffrroomm cclliieennttss oorr nneettwwoorrkkss
+
+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
+
+AAddddiinngg tthhee SSAASSLL llooggiinn nnaammee ttoo mmaaiill hheeaaddeerrss
+
+To report SASL login names in Received: message headers (Postfix version 2.3
+and later):
+
+ /etc/postfix/main.cf:
+ smtpd_sasl_authenticated_header = yes
+
+ NNoottee
+
+ The SASL login names will be shared with the entire world.
+
+TTeessttiinngg SSAASSLL aauutthheennttiiccaattiioonn iinn tthhee PPoossttffiixx SSMMTTPP SSeerrvveerr
+
+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 bboolldd font.
+
+ % tteellnneett sseerrvveerr..eexxaammppllee..ccoomm 2255
+ ...
+ 220 server.example.com ESMTP Postfix
+ EEHHLLOO cclliieenntt..eexxaammppllee..ccoomm
+ 250-server.example.com
+ 250-PIPELINING
+ 250-SIZE 10240000
+ 250-ETRN
+ 250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
+ 250 8BITMIME
+ AAUUTTHH PPLLAAIINN AAHHRRllcc33QQAAddGGVVzzddHHBBhhcc33MM==
+ 235 Authentication successful
+
+To test this over a connection that is encrypted with TLS, use openssl s_client
+instead of telnet:
+
+ % ooppeennssssll ss__cclliieenntt --ccoonnnneecctt sseerrvveerr..eexxaammppllee..ccoomm::2255 --ssttaarrttttllss ssmmttpp
+ ...
+ 220 server.example.com ESMTP Postfix
+ EEHHLLOO cclliieenntt..eexxaammppllee..ccoomm
+ ...see above example for more...
+
+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'.
+
+ CCaauuttiioonn
+
+ 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.
+
+You can use one of the following commands to generate base64 encoded
+authentication information:
+
+ * Using a recent version of the bbaasshh shell:
+
+ % eecchhoo --nnee ''\\000000uusseerrnnaammee\\000000ppaasssswwoorrdd'' || ooppeennssssll bbaassee6644
+
+ Some other shells support similar syntax.
+
+ * Using the pprriinnttff command:
+
+ % pprriinnttff ''\\00%%ss\\00%%ss'' ''uusseerrnnaammee'' ''ppaasssswwoorrdd'' || ooppeennssssll bbaassee6644
+ % pprriinnttff ''\\00%%ss\\00%%ss'' ''uusseerrnnaammee'' ''ppaasssswwoorrdd'' || mmmmeennccooddee
+
+ The mmmmeennccooddee command is part of the metamail software.
+
+ * Using Perl MMIIMMEE::::BBaassee6644 (from http://www.cpan.org/):
+
+ % ppeerrll --MMMMIIMMEE::::BBaassee6644 --ee \\
+ ''pprriinntt eennccooddee__bbaassee6644((""\\00uusseerrnnaammee\\00ppaasssswwoorrdd""));;''
+
+ If the username or password contain "@", you must specify "\@".
+
+ * Using the ggeenn--aauutthh script:
+
+ % ggeenn--aauutthh ppllaaiinn
+ username: uusseerrnnaammee
+ password:
+
+ The ggeenn--aauutthh Perl script was written by John Jetmore and can be found at
+ http://jetmore.org/john/code/gen-auth.
+
+CCoonnffiigguurriinngg SSAASSLL aauutthheennttiiccaattiioonn iinn tthhee PPoossttffiixx SSMMTTPP//LLMMTTPP cclliieenntt
+
+The Postfix SMTP and the LMTP client can authenticate with a remote SMTP server
+via the Cyrus SASL framework. At this time, the Dovecot SASL implementation
+does not provide client functionality.
+
+ NNoottee
+
+ The examples in this section discuss only the SMTP client. Replace smtp_
+ with lmtp_ to get the corresponding LMTP client configuration.
+
+You can read more about the following topics:
+
+ * Enabling SASL authentication in the Postfix SMTP/LMTP client
+ * Configuring sender-dependent SASL authentication
+ * Postfix SMTP/LMTP client policy - SASL mechanism pprrooppeerrttiieess
+ * Postfix SMTP/LMTP client policy - SASL mechanism nnaammeess
+
+EEnnaabblliinngg SSAASSLL aauutthheennttiiccaattiioonn iinn tthhee PPoossttffiixx SSMMTTPP//LLMMTTPP cclliieenntt
+
+This section shows a typical scenario where the Postfix SMTP client sends all
+messages via a mail gateway server that requires SASL authentication.
+
+ TTrroouubbllee ssoollvviinngg ttiippss::
+
+ * If your SASL logins fail with "SASL authentication failure: No worthy
+ mechs found" in the mail logfile, then see the section "Postfix SMTP/
+ LMTP client policy - SASL mechanism pprrooppeerrttiieess".
+
+ * For a solution to a more obscure class of SASL authentication failures,
+ see "Postfix SMTP/LMTP client policy - SASL mechanism nnaammeess".
+
+To make the example more readable we introduce it in two parts. The first part
+takes care of the basic configuration, while the second part sets up the
+username/password information.
+
+ /etc/postfix/main.cf:
+ smtp_sasl_auth_enable = yes
+ smtp_tls_security_level = encrypt
+ smtp_sasl_tls_security_options = noanonymous
+ relayhost = [mail.isp.example]
+ # Alternative form:
+ # relayhost = [mail.isp.example]:submission
+ smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
+
+ * The smtp_sasl_auth_enable setting enables client-side authentication. We
+ will configure the client's username and password information in the second
+ part of the example.
+
+ * The smtp_tls_security_level setting ensures that the connection to the
+ remote smtp server will be encrypted, and smtp_sasl_tls_security_options
+ removes the prohibition on plaintext passwords.
+
+ * The relayhost setting forces the Postfix SMTP to send all remote messages
+ to the specified mail server instead of trying to deliver them directly to
+ their destination.
+
+ * In the relayhost setting, the "[" and "]" prevent the Postfix SMTP client
+ from looking up MX (mail exchanger) records for the enclosed name.
+
+ * The relayhost destination may also specify a non-default TCP port. For
+ example, the alternative form [mail.isp.example]:submission tells Postfix
+ to connect to TCP network port 587, which is reserved for email client
+ applications.
+
+ * The Postfix SMTP client is compatible with SMTP servers that use the non-
+ standard "AUTH=mmeetthhoodd....." syntax in response to the EHLO command; this
+ requires no additional Postfix client configuration.
+
+ * With the setting "smtp_tls_wrappermode = yes", the Postfix SMTP client
+ supports the "wrappermode" protocol, which uses TCP port 465 on the SMTP
+ server (Postfix 3.0 and later).
+
+ * With the smtp_sasl_password_maps parameter, we configure the Postfix SMTP
+ client to send username and password information to the mail gateway
+ server. As discussed in the next section, the Postfix SMTP client supports
+ multiple ISP accounts. For this reason the username and password are stored
+ in a table that contains one username/password combination for each mail
+ gateway server.
+
+ /etc/postfix/sasl_passwd:
+ # destination credentials
+ [mail.isp.example] username:password
+ # Alternative form:
+ # [mail.isp.example]:submission username:password
+
+ IImmppoorrttaanntt
+
+ Keep the SASL client password file in /etc/postfix, and make the file
+ read+write only for root to protect the username/password combinations
+ against other users. The Postfix SMTP client will still be able to read the
+ SASL client passwords. It opens the file as user root before it drops
+ privileges, and before entering an optional chroot jail.
+
+ * Use the postmap command whenever you change the /etc/postfix/sasl_passwd
+ file.
+
+ * If you specify the "[" and "]" in the relayhost destination, then you must
+ use the same form in the smtp_sasl_password_maps file.
+
+ * If you specify a non-default TCP Port (such as ":submission" or ":587") in
+ the relayhost destination, then you must use the same form in the
+ smtp_sasl_password_maps file.
+
+CCoonnffiigguurriinngg SSeennddeerr--DDeeppeennddeenntt SSAASSLL aauutthheennttiiccaattiioonn
+
+Postfix supports different ISP accounts for different sender addresses (version
+2.3 and later). This can be useful when one person uses the same machine for
+work and for personal use, or when people with different ISP accounts share the
+same Postfix server.
+
+To make this possible, Postfix supports per-sender SASL passwords and per-
+sender relay hosts. In the example below, the Postfix SMTP client will search
+the SASL password file by sender address before it searches that same file by
+destination. Likewise, the Postfix trivial-rewrite(8) daemon will search the
+per-sender relayhost file, and use the default relayhost setting only as a
+final resort.
+
+ /etc/postfix/main.cf:
+ smtp_sender_dependent_authentication = yes
+ sender_dependent_relayhost_maps = hash:/etc/postfix/sender_relay
+ smtp_sasl_auth_enable = yes
+ smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
+ relayhost = [mail.isp.example]
+ # Alternative form:
+ # relayhost = [mail.isp.example]:submission
+
+ /etc/postfix/sasl_passwd:
+ # Per-sender authentication; see also /etc/postfix/sender_relay.
+ user1@example.com username1:password1
+ user2@example.net username2:password2
+ # Login information for the default relayhost.
+ [mail.isp.example] username:password
+ # Alternative form:
+ # [mail.isp.example]:submission username:password
+
+ /etc/postfix/sender_relay:
+ # Per-sender provider; see also /etc/postfix/sasl_passwd.
+ user1@example.com [mail.example.com]:submission
+ user2@example.net [mail.example.net]
+
+ * If you are creative, then you can try to combine the two tables into one
+ single MySQL database, and configure different Postfix queries to extract
+ the appropriate information.
+
+ * Specify ddbbmm instead of hhaasshh if your system uses ddbbmm files instead of ddbb
+ files. To find out what lookup tables Postfix supports, use the command
+ "ppoossttccoonnff --mm".
+
+ * Execute the command "ppoossttmmaapp //eettcc//ppoossttffiixx//ssaassll__ppaasssswwdd" whenever you change
+ the sasl_passwd table.
+
+ * Execute the command "ppoossttmmaapp //eettcc//ppoossttffiixx//sseennddeerr__rreellaayy" whenever you change
+ the sender_relay table.
+
+PPoossttffiixx SSMMTTPP//LLMMTTPP cclliieenntt ppoolliiccyy -- SSAASSLL mmeecchhaanniissmm pprrooppeerrttiieess
+
+Just like the Postfix SMTP server, the SMTP client has a policy that determines
+which SASL mechanisms are acceptable, based on their properties. The next two
+sections give examples of how these policies are used.
+
+ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
+ |PPrrooppeerrttyy |DDeessccrriippttiioonn |
+ |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |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. |
+ |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+ |mutual_auth |Use only mechanisms that authenticate both the client and |
+ | |the server to each other. |
+ |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+
+UUnneennccrryypptteedd SSMMTTPP sseessssiioonn
+
+The default policy is stricter than that of the Postfix SMTP server - plaintext
+mechanisms are not allowed (nor is any anonymous mechanism):
+
+ /etc/postfix/main.cf:
+ smtp_sasl_security_options = noplaintext, noanonymous
+
+This default policy, which allows no plaintext passwords, leads to
+authentication failures if the remote server only offers plaintext
+authentication mechanisms (the SMTP server announces "AUTH PLAIN LOGIN"). In
+such cases the SMTP client will log the following error message:
+
+ SASL authentication failure: No worthy mechs found
+
+ NNoottee
+
+ This same error message will also be logged when the libplain.so or
+ liblogin.so modules are not installed in the /usr/lib/sasl2 directory.
+
+The insecure approach is to lower the security standards and permit plaintext
+authentication mechanisms:
+
+ /etc/postfix/main.cf:
+ smtp_sasl_security_options = noanonymous
+
+The more secure approach is to protect the plaintext username and password with
+TLS session encryption. To find out if the remote SMTP server supports TLS,
+connect to the server and see if it announces STARTTLS support as shown in the
+example. Information sent by the client (that is, you) is shown in bboolldd font.
+
+ % tteellnneett sseerrvveerr..eexxaammppllee..ccoomm 2255
+ ...
+ 220 server.example.com ESMTP Postfix
+ EEHHLLOO cclliieenntt..eexxaammppllee..ccoomm
+ 250-server.example.com
+ 250-PIPELINING
+ 250-SIZE 10240000
+ 250-STARTTLS
+ ...
+
+Instead of port 25 (smtp), specify port 587 (submission) where appropriate.
+
+EEnnccrryypptteedd SSMMTTPP sseessssiioonn ((TTLLSS))
+
+To turn on TLS in the Postfix SMTP client, see TLS_README for configuration
+details.
+
+The smtp_sasl_tls_security_options 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:
+ smtp_sasl_tls_security_options = $smtp_sasl_security_options
+
+A more sophisticated policy allows plaintext mechanisms, but only over a TLS-
+encrypted connection:
+
+ /etc/postfix/main.cf:
+ smtp_sasl_security_options = noanonymous, noplaintext
+ smtp_sasl_tls_security_options = noanonymous
+
+PPoossttffiixx SSMMTTPP//LLMMTTPP cclliieenntt ppoolliiccyy -- SSAASSLL mmeecchhaanniissmm nnaammeess
+
+Given the SASL security options of the previous section, the Cyrus SASL library
+will choose the most secure authentication mechanism that both the SMTP client
+and server implement. Unfortunately, that authentication mechanism may fail
+because the client or server is not configured to use that mechanism.
+
+To prevent this, the Postfix SMTP client can filter the names of the
+authentication mechanisms from the remote SMTP server. Used correctly, the
+filter hides unwanted mechanisms from the Cyrus SASL library, forcing the
+library to choose from the mechanisms the Postfix SMTP client filter passes
+through.
+
+The following example filters out everything but the mechanisms PLAIN and
+LOGIN:
+
+ /etc/postfix/main.cf:
+ smtp_sasl_mechanism_filter = plain, login
+
+ NNoottee
+
+ If the remote server does not offer any of the mechanisms on the filter
+ list, authentication will fail.
+
+We close this section with an example that passes every mechanism except for
+GSSAPI and LOGIN:
+
+ /etc/postfix/main.cf:
+ smtp_sasl_mechanism_filter = !gssapi, !login, static:all
+
+BBuuiillddiinngg PPoossttffiixx wwiitthh SSAASSLL ssuuppppoorrtt
+
+As mentioned elsewhere, Postfix supports two SASL implementations: Cyrus SASL
+(SMTP client and server) and Dovecot SASL (SMTP server only). Both
+implementations can be built into Postfix simultaneously.
+
+ * Building Dovecot SASL support
+ * Building Cyrus SASL support
+
+BBuuiillddiinngg DDoovveeccoott SSAASSLL ssuuppppoorrtt
+
+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.
+
+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 the Postfix SMTP client 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:
+
+ % mmaakkee ttiiddyy # if you have left-over files from a previous build
+ % mmaakkee mmaakkeeffiilleess CCCCAARRGGSS==''--DDUUSSEE__SSAASSLL__AAUUTTHH \\
+ --DDDDEEFF__SSEERRVVEERR__SSAASSLL__TTYYPPEE==\\""ddoovveeccoott\\""''
+
+After this, proceed with "make" as described in the INSTALL document.
+
+NNoottee
+
+ * The -DDEF_SERVER_SASL_TYPE=\"dovecot\" 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 (but this may
+ cause surprises when you switch to a later Postfix version that is built
+ with the default SASL type of cyrus).
+
+ * If you also want support for LDAP or TLS (or for Cyrus SASL), you need to
+ merge their CCARGS and AUXLIBS options into the above command line; see the
+ LDAP_README and TLS_README for details.
+
+ % mmaakkee ttiiddyy # if you have left-over files from a previous build
+ % mmaakkee mmaakkeeffiilleess CCCCAARRGGSS==''--DDUUSSEE__SSAASSLL__AAUUTTHH \\
+ --DDDDEEFF__SSEERRVVEERR__SSAASSLL__TTYYPPEE==\\""ddoovveeccoott\\"" \\
+ ......CCCCAARRGGSS ooppttiioonnss ffoorr LLDDAAPP oorr TTLLSS eettcc........'' \\
+ AAUUXXLLIIBBSS==''......AAUUXXLLIIBBSS ooppttiioonnss ffoorr LLDDAAPP oorr TTLLSS eettcc........''
+
+BBuuiillddiinngg CCyyrruuss SSAASSLL ssuuppppoorrtt
+
+BBuuiillddiinngg tthhee CCyyrruuss SSAASSLL lliibbrraarryy
+
+Postfix works with cyrus-sasl-1.5.x or cyrus-sasl-2.1.x, which are available
+from https://github.com/cyrusimap/cyrus-sasl/releases.
+
+ IImmppoorrttaanntt
+
+ If you install the Cyrus SASL libraries as per the default, you will have
+ to create a 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 and/or
+NTLM authentication mechanism. To enable these authentication mechanisms, build
+the Cyrus SASL libraries with:
+
+ % ..//ccoonnffiigguurree ----eennaabbllee--llooggiinn ----eennaabbllee--nnttllmm
+
+BBuuiillddiinngg PPoossttffiixx wwiitthh CCyyrruuss SSAASSLL ssuuppppoorrtt
+
+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.
+
+On some systems this generates the necessary Makefile definitions:
+
+Cyrus SASL version 2.1.x
+
+ % mmaakkee ttiiddyy # if you have left-over files from a previous build
+ % mmaakkee mmaakkeeffiilleess CCCCAARRGGSS==""--DDUUSSEE__SSAASSLL__AAUUTTHH --DDUUSSEE__CCYYRRUUSS__SSAASSLL \\
+ --II//uussrr//llooccaall//iinncclluuddee//ssaassll"" AAUUXXLLIIBBSS==""--LL//uussrr//llooccaall//lliibb --llssaassll22""
+
+ If your Cyrus SASL shared library is in a directory that the RUN-TIME
+ linker does not know about, add a "-Wl,-R,/path/to/directory" option after
+ "-lsasl2".
+
+Cyrus SASL version 1.5.x
+
+ % mmaakkee ttiiddyy # if you have left-over files from a previous build
+ % mmaakkee mmaakkeeffiilleess CCCCAARRGGSS==""--DDUUSSEE__SSAASSLL__AAUUTTHH --DDUUSSEE__CCYYRRUUSS__SSAASSLL \\
+ --II//uussrr//llooccaall//iinncclluuddee"" AAUUXXLLIIBBSS==""--LL//uussrr//llooccaall//lliibb --llssaassll""
+
+On Solaris 2.x you need to specify run-time link information, otherwise the
+ld.so run-time linker will not find the SASL shared library:
+
+Cyrus SASL version 2.1.x
+
+ % mmaakkee ttiiddyy # remove left-over files from a previous build
+ % mmaakkee mmaakkeeffiilleess CCCCAARRGGSS==""--DDUUSSEE__SSAASSLL__AAUUTTHH --DDUUSSEE__CCYYRRUUSS__SSAASSLL \\
+ --II//uussrr//llooccaall//iinncclluuddee//ssaassll"" AAUUXXLLIIBBSS==""--LL//uussrr//llooccaall//lliibb \\
+ --RR//uussrr//llooccaall//lliibb --llssaassll22""
+
+Cyrus SASL version 1.5.x
+
+ % mmaakkee ttiiddyy # if you have left-over files from a previous build
+ % mmaakkee mmaakkeeffiilleess CCCCAARRGGSS==""--DDUUSSEE__SSAASSLL__AAUUTTHH --DDUUSSEE__CCYYRRUUSS__SSAASSLL \\
+ --II//uussrr//llooccaall//iinncclluuddee"" AAUUXXLLIIBBSS==""--LL//uussrr//llooccaall//lliibb \\
+ --RR//uussrr//llooccaall//lliibb --llssaassll""
+
+UUssiinngg CCyyrruuss SSAASSLL vveerrssiioonn 11..55..xx
+
+Postfix supports Cyrus SASL version 1.x, but you shouldn't use it unless you
+are forced to. The makers of Cyrus SASL write:
+
+ This library is being deprecated and applications should transition to
+ using the SASLv2 library (source: Project Cyrus: Downloads).
+
+If you still need to set it up, here's a quick rundown:
+
+Read the regular section on SMTP server configurations for the Cyrus SASL
+framework. The differences are:
+
+ * Cyrus SASL version 1.5.x searches for configuration (smtpd.conf) in /usr/
+ lib/sasl/ only. You must place the configuration in that directory. Some
+ systems may have modified Cyrus SASL and put the files into e.g. /var/lib/
+ sasl/.
+
+ * Use the saslpasswd command instead of saslpasswd2 to create users in
+ sasldb.
+
+ * Use the sasldblistusers command instead of sasldblistusers2 to find users
+ in sasldb.
+
+ * In the smtpd.conf file you can't use mech_list to limit the range of
+ mechanisms offered. Instead, remove their libraries from /usr/lib/sasl/
+ (and remember remove those files again when a system update re-installs new
+ versions).
+
+CCrreeddiittss
+
+ * Postfix SASL support was originally implemented by Till Franke of SuSE
+ Rhein/Main AG.
+ * Wietse trimmed down the code to only the bare necessities.
+ * Support for Cyrus SASL version 2 was contributed by Jason Hoos.
+ * Liviu Daia added smtpd_sasl_application_name, separated
+ reject_sender_login_mismatch into
+ reject_authenticated_sender_login_mismatch and
+ reject_unauthenticated_sender_login_mismatch, and revised the docs.
+ * Wietse made another iteration through the code to add plug-in support for
+ multiple SASL implementations, and for reasons that have been lost, also
+ changed smtpd_sasl_application_name into smtpd_sasl_path.
+ * The Dovecot SMTP server-only plug-in was originally implemented by Timo
+ Sirainen of Procontrol, Finland.
+ * Patrick Ben Koetter revised this document for Postfix 2.4 and made much
+ needed updates.
+ * Patrick Ben Koetter revised this document again for Postfix 2.7 and made
+ much needed updates.
+