diff options
Diffstat (limited to 'proto/SASL_README.html')
| -rw-r--r-- | proto/SASL_README.html | 2278 |
1 files changed, 2278 insertions, 0 deletions
diff --git a/proto/SASL_README.html b/proto/SASL_README.html new file mode 100644 index 0000000..14d959b --- /dev/null +++ b/proto/SASL_README.html @@ -0,0 +1,2278 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> + +<head> + +<title>Postfix SASL Howto</title> + +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link rel='stylesheet' type='text/css' href='postfix-doc.css'> + +</head> + +<body> + +<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix SASL Howto</h1> + +<hr> + +<h2><a name="intro">How Postfix uses SASL authentication</a></h2> + +<p> 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. </p> + +<p> 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. </p> + +<p> 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. </p> + +<p> 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. </p> + +<p> You can read more about the following topics: </p> + +<ul> + +<li><a href="#server_sasl">Configuring SASL authentication in the +Postfix SMTP server</a></li> + +<li><a href="#client_sasl">Configuring SASL authentication in the Postfix SMTP/LMTP client</a></li> + +<li><a href="#postfix_build">Building Postfix with SASL support</a></li> + +<li><a href="#cyrus_legacy">Using Cyrus SASL version 1.5.x</a></li> + +<li><a href="#credits">Credits</a></li> + +</ul> + +<h2><a name="server_sasl">Configuring SASL authentication in the +Postfix SMTP server</a></h2> + +<p> As mentioned earlier, SASL is implemented separately from +Postfix. For this reason, configuring SASL authentication in the +Postfix SMTP server involves two different steps: </p> + +<ul> + +<li> <p> 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. </p> </li> + +<li> <p> 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. </p> </li> + +</ul> + +<p> Successful authentication in the Postfix SMTP server requires +a functional SASL framework. Configuring SASL should therefore +always be the first step, before configuring Postfix. </p> + +<p> You can read more about the following topics: </p> + +<ul> + +<li><a href="#server_which">Which SASL Implementations are +supported?</a></li> + +<li><a href="#server_dovecot">Configuring Dovecot SASL</a> + +<ul> + +<li><a href="#server_dovecot_comm">Postfix to Dovecot SASL +communication</a></li> + +</ul> </li> + +<li><a href="#server_cyrus">Configuring Cyrus SASL</a> + +<ul> + +<li><a href="#server_cyrus_name">Cyrus SASL configuration file +name</a></li> + +<li><a href="#server_cyrus_location">Cyrus SASL configuration +file location</a></li> + +<li><a href="#server_cyrus_comm">Postfix to Cyrus SASL +communication</a></li> + +</ul> </li> + +<li><a href="#server_sasl_enable">Enabling SASL authentication and +authorization in the Postfix SMTP server</a> + +<ul> + +<li><a href="#server_sasl_authc">Enabling SASL authentication in +the Postfix SMTP server</a></li> + +<li><a href="#smtpd_sasl_security_options">Postfix SMTP Server +policy - SASL mechanism properties</a></li> + +<li><a href="#server_sasl_authz">Enabling SASL authorization in the +Postfix SMTP server</a></li> + +<li><a href="#server_sasl_other">Additional SMTP Server SASL +options</a></li> + +</ul></li> + +<li><a href="#server_test">Testing SASL authentication in the Postfix +SMTP server</a></li> + +</ul> + + +<h3><a name="server_which">Which SASL Implementations are +supported?</a></h3> + +<p> Currently the Postfix SMTP server supports the Cyrus SASL and +Dovecot SASL implementations. </p> + +<blockquote> + +<strong>Note</strong> + +<p> 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. </p> + +</blockquote> + +<p> To find out what SASL implementations are compiled into Postfix, +use the following commands: </p> + +<blockquote> +<pre> +% <strong><code>postconf -a</code></strong> (SASL support in the SMTP server) +% <strong><code>postconf -A</code></strong> (SASL support in the SMTP+LMTP client) +</pre> +</blockquote> + +<p> These commands are available only with Postfix version 2.3 and +later. </p> + +<h3><a name="server_dovecot">Configuring Dovecot SASL</a></h3> + +<p> 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 +<a href="http://wiki.dovecot.org">Dovecot documentation</a> for how +to configure and operate the Dovecot authentication server. </p> + +<h4><a name="server_dovecot_comm">Postfix to Dovecot SASL communication</a></h4> + +<p> 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. </p> + +<p> The following fragment for Dovecot version 2 assumes that the +Postfix queue is under <code>/var/spool/postfix/</code>. </p> + +<blockquote> +<pre> + 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 +</pre> +</blockquote> + +<p> Line 4 places the Dovecot SASL socket in +<code>/var/spool/postfix/private/auth</code>, lines 5-8 limit +read+write permissions to user and group <code>postfix</code> only, +and line 14 provides <code>plain</code> and <code>login</code> as +mechanisms for the Postfix SMTP server. </p> + +<p> Proceed with the section "<a href="#server_sasl_enable">Enabling +SASL authentication and authorization in the Postfix SMTP server</a>" +to turn on and use SASL in the Postfix SMTP server. </p> + +<h3><a name="server_cyrus">Configuring Cyrus SASL</a></h3> + +<p> 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. </p> + +<p> 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. </p> + +<h4><a name="server_cyrus_name">Cyrus SASL configuration file name</a></h4> + +<p> The name of the configuration file (default: <code>smtpd.conf</code>) +is configurable. It is a concatenation from a value that the Postfix +SMTP server sends to the Cyrus SASL library, and the suffix +<code>.conf</code>, added by Cyrus SASL. </p> + +<p> The value sent by Postfix is the name of the server component +that will use Cyrus SASL. It defaults to <code>smtpd</code> and +is configured with one of the following variables: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + # Postfix 2.3 and later + smtpd_sasl_path = smtpd + + # Postfix < 2.3 + smtpd_sasl_application_name = smtpd +</pre> +</blockquote> + +<h4><a name="server_cyrus_location">Cyrus SASL configuration file +location</a></h4> + +<p> The location where Cyrus SASL searches for the named file depends +on the Cyrus SASL version and the OS/distribution used. </p> + +<p> You can read more about the following topics: </p> + +<ul> + +<li> <p> Cyrus SASL version 2.x searches for the configuration file +in <code>/usr/lib/sasl2/</code>. </p> </li> + +<li> <p> Cyrus SASL version 2.1.22 and newer additionally search +in <code>/etc/sasl2/</code>. </p> </li> + +<li> <p> With Postfix 2.5 and later you can explicitly configure the +search path via the <code>cyrus_sasl_config_path</code> configuration +parameter. Specify zero or more colon-separated directories. If +set empty (the default value) the search path is the one compiled +into the Cyrus SASL library. </p> </li> + +<li> <p> Some Postfix distributions employ a non-empty default value +for <code>cyrus_sasl_config_path</code> to look for the Cyrus SASL +configuration file in <code>/etc/postfix/sasl/</code>, +<code>/var/lib/sasl2/</code> etc. See the output of <code>postconf +cyrus_sasl_config_path</code> and/or the distribution-specific +documentation to determine the expected location. </p> </li> + +<li> <p> Some Debian-based Postfix distributions patch Postfix to +hardcode a non-default search path, making it impossible to set an +alternate search path via the "cyrus_sasl_config_path" parameter. This +is likely to be the case when the distribution documents a +Postfix-specific path (e.g. <code>/etc/postfix/sasl/</code>) that is +different from the default value of "cyrus_sasl_config_path" (which +then is likely to be empty). </p> </li> + +</ul> + +<blockquote> + +<strong>Note</strong> + +<p> Cyrus SASL searches <code>/usr/lib/sasl2/</code> first. If it +finds the specified configuration file there, it will not examine +other locations. </p> + +</blockquote> + +<h4><a name="server_cyrus_comm">Postfix to Cyrus SASL communication</a></h4> + +<p> As the Postfix SMTP server is linked with the Cyrus SASL library +<code>libsasl</code>, communication between Postfix and Cyrus SASL +takes place by calling functions in the SASL library. </p> + +<p> 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. </p> + +<p> The following table shows typical combinations discussed in +this document: </p> + +<blockquote> + +<table border="1"> + +<tr> + +<th align="center">authentication backend</th> + +<th align="center">password verification service / plugin</th> + +</tr> + +<tr> + +<td>/etc/shadow</td> + +<td><a href="#saslauthd">saslauthd</a></td> + +</tr> + +<tr> + +<td>PAM</td> + +<td><a href="#saslauthd">saslauthd</a></td> + +</tr> + +<tr> + +<td>IMAP server</td> + +<td><a href="#saslauthd">saslauthd</a></td> + +</tr> + +<tr> + +<td>sasldb</td> + +<td><a href="#auxprop_sasldb">sasldb</a></td> + +</tr> + +<tr> + +<td>MySQL, PostgreSQL, SQLite</td> + +<td><a href="#auxprop_sql">sql</a></td> + +</tr> + +<tr> + +<td>LDAP</td> + +<td><a href="#auxprop_ldapdb">ldapdb</a></td> + +</tr> + +</table> + +</blockquote> + +<blockquote> + +<strong>Note</strong> + +<p> Read the Cyrus SASL documentation for other backends it can +use. </p> + +</blockquote> + +<h4><a name="saslauthd">saslauthd - Cyrus SASL password verification service</a></h4> + +<p> Communication between the Postfix SMTP server (read: Cyrus SASL's +<code>libsasl</code>) and the <code>saslauthd</code> server takes +place over a UNIX-domain socket. </p> + +<p> <code>saslauthd</code> usually establishes the UNIX domain +socket in <code>/var/run/saslauthd/</code> and waits for authentication +requests. The Postfix SMTP server must have read+execute permission +to this directory or authentication attempts will fail. </p> + +<blockquote> + +<strong>Important</strong> + +<p> Some distributions require the user <code>postfix</code> to be +member of a special group e.g. <code>sasl</code>, otherwise it +will not be able to access the <code>saslauthd</code> socket +directory. </p> + +</blockquote> + +<p> The following example configures the Cyrus SASL library to +contact <code>saslauthd</code> as its password verification service: +</p> + +<blockquote> +<pre> +/etc/sasl2/smtpd.conf: + pwcheck_method: saslauthd + mech_list: PLAIN LOGIN +</pre> +</blockquote> + +<blockquote> + +<strong>Important</strong> + +<p> Do not specify any other mechanisms in <code>mech_list</code> +than <code>PLAIN</code> or <code>LOGIN</code> when using +<code>saslauthd</code>! It can only handle these two mechanisms, +and authentication will fail if clients are allowed to choose other +mechanisms. </p> + +</blockquote> + +<blockquote> + +<strong>Important</strong> + +<p> Plaintext mechanisms (<code>PLAIN</code>, <code>LOGIN</code>) +send credentials unencrypted. This information should be protected +by an additional security layer such as a TLS-encrypted SMTP session +(see: TLS_README). </p> + +</blockquote> + +<p> Additionally the <code>saslauthd</code> server itself must be +configured. It must be told which authentication backend to turn +to for password verification. The backend is selected with a +<code>saslauthd</code> command-line option and will be shown in the +following examples. </p> + +<blockquote> + +<strong>Note</strong> + +<p> Some distributions use a configuration file to provide saslauthd +command line options to set e.g. the authentication backend. Typical +locations are <code>/etc/sysconfig/saslauthd</code> or +<code>/etc/default/saslauthd</code>. </p> + +</blockquote> + +<h4><a name="saslauthd_shadow">Using saslauthd with /etc/shadow</a></h4> + +<p> Access to the <code>/etc/shadow</code> system password file +requires <code>root</code> privileges. The Postfix SMTP server +(and in consequence <code>libsasl</code> linked to the server) runs +with the least privilege possible. Direct access to +<code>/etc/shadow</code> would not be possible without breaking the +Postfix security architecture. </p> + +<p> The <code>saslauthd</code> socket builds a safe bridge. Postfix, +running as limited user <code>postfix</code>, can access the +UNIX-domain socket that <code>saslauthd</code> receives commands +on; <code>saslauthd</code>, running as privileged user <code>root</code>, +has the privileges required to access the shadow file. </p> + +<p> The <code>saslauthd</code> server verifies passwords against the +authentication backend <code>/etc/shadow</code> if started like this: </p> + +<blockquote> +<pre> +% <strong><code>saslauthd -a shadow</code></strong> +</pre> +</blockquote> + +<p> See section "<a href="#testing_saslauthd">Testing saslauthd +authentication</a>" for test instructions. </p> + +<h4><a name="saslauthd_pam">Using saslauthd with PAM</a></h4> + +<p> Cyrus SASL can use the PAM framework to authenticate credentials. +<code>saslauthd</code> uses the PAM framework when started like +this: </p> + +<blockquote> +<pre> +% <strong><code>saslauthd -a pam</code></strong> +</pre> +</blockquote> + +<blockquote> + +<strong>Note</strong> + +<p> PAM configuration for the Postfix SMTP server is usually given +in <code>/etc/pam.d/smtp</code> and is beyond the scope of this +document. </p> + +</blockquote> + +<p> See section "<a href="#testing_saslauthd">Testing saslauthd +authentication</a>" for test instructions. </p> + +<h4><a name="saslauthd_imap">Using saslauthd with an IMAP server</a></h4> + +<p> <code>saslauthd</code> can verify the SMTP client credentials +by using them to log into an IMAP server. If the login succeeds, +SASL authentication also succeeds. <code>saslauthd</code> contacts +an IMAP server when started like this: </p> + +<blockquote> +<pre> +% <strong><code>saslauthd -a rimap -O imap.example.com</code></strong> +</pre> +</blockquote> + +<blockquote> + +<strong>Note</strong> + +<p> The option "<code>-O imap.example.com</code>" specifies the +IMAP server <code>saslauthd</code> should contact when it verifies +credentials. </p> + +</blockquote> + +<blockquote> + +<strong>Important</strong> + +<p> <code>saslauthd</code> 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. </p> + +</blockquote> + +<p> See section "<a href="#testing_saslauthd">Testing saslauthd +authentication</a>" for test instructions. </p> + +<h4><a name="testing_saslauthd">Testing saslauthd authentication</a></h4> + +<p> Cyrus SASL provides the <code>testsaslauthd</code> utility to +test <code>saslauthd</code> authentication. The username and password +are given as command line arguments. The example shows the response +when authentication is successful: </p> + +<blockquote> +<pre> +% <strong><code>testsaslauthd -u <em>username</em> -p <em>password</em></code></strong> +0: OK "Success." +</pre> +</blockquote> + +<blockquote> + +<strong>Note</strong> + +<p> Sometimes the <code>testsaslauthd</code> program is not distributed +with a the Cyrus SASL main package. In that case, it may be +distributed with <code>-devel</code>, <code>-dev</code> or +<code>-debug</code> packages. </p> + +</blockquote> + +<p> Specify an additional "<code>-s smtp</code>" if <code>saslauthd</code> +was configured to contact the PAM authentication framework, and +specify an additional "<code>-f <em>/path/to/socketdir/mux</em></code>" +if <code>saslauthd</code> establishes the UNIX-domain socket in a +non-default location. </p> + +<p> If authentication succeeds, proceed with the section "<a +href="#server_sasl_enable">Enabling SASL authentication and authorization +in the Postfix SMTP server</a>". </p> + +<h4><a name="auxprop">Cyrus SASL Plugins - auxiliary property +plugins</a></h4> + +<p> Cyrus SASL uses a plugin infrastructure (called <code>auxprop</code>) +to expand <code>libsasl</code>'s capabilities. Currently Cyrus +SASL sources provide three authentication plugins. </p> + +<blockquote> + +<table border="1"> + +<tr> <th>Plugin </th> <th>Description </th> </tr> + +<tr> <td><a href="#auxprop_sasldb">sasldb</a></td> <td> Accounts +are stored stored in a Cyrus SASL Berkeley DB database </td> </tr> + +<tr> <td><a href="#auxprop_sql">sql</a></td> <td> Accounts are +stored in a SQL database </td> </tr> + +<tr> <td><a href="#auxprop_ldapdb">ldapdb</a></td> <td> Accounts +are stored stored in an LDAP database </td> </tr> + +</table> + +</blockquote> + +<blockquote> + +<strong>Important</strong> + +<p> 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. </p> + +</blockquote> + +<h4><a name="auxprop_sasldb">The sasldb plugin</a></h4> + +<p> 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 <code>/etc/sasldb2</code>. </p> + +<blockquote> + +<strong>Note</strong> + +<p> The <code>sasldb2</code> file contains passwords in +plaintext, and should have read+write access only to user +<code>postfix</code> or a group that <code>postfix</code> is member +of. </p> + +</blockquote> + +<p> The <code>saslpasswd2</code> command-line utility creates +and maintains the database: </p> + +<blockquote> +<pre> +% <strong>saslpasswd2 -c -u <em>example.com</em> <em>username</em></strong> +Password: +Again (for verification): +</pre> +</blockquote> + +<p> This command creates an account +<code><em>username@example.com</em></code>. </p> + +<blockquote> + +<strong>Important</strong> + +<p> users must specify <code><em>username@example.com</em></code> +as login name, not <code><em>username</em></code>. </p> + +</blockquote> + +<p> Run the following command to reuse the Postfix <code>mydomain</code> +parameter value as the login domain: </p> + +<blockquote> +<pre> +% <strong>saslpasswd2 -c -u `postconf -h mydomain` <em>username</em></strong> +Password: +Again (for verification): +</pre> +</blockquote> + +<blockquote> + +<strong>Note</strong> + +<p> Run <code>saslpasswd2</code> without any options for further +help on how to use the command. </p> + +</blockquote> + +<p> The <code>sasldblistusers2</code> command lists all existing +users in the sasldb database: </p> + +<blockquote> +<pre> +% <strong>sasldblistusers2</strong> +username1@example.com: password1 +username2@example.com: password2 +</pre> +</blockquote> + +<p> Configure libsasl to use sasldb with the following instructions: </p> + +<blockquote> +<pre> +/etc/sasl2/smtpd.conf: + pwcheck_method: auxprop + auxprop_plugin: sasldb + mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5 NTLM +</pre> +</blockquote> + +<blockquote> + +<strong>Note</strong> + +<p> In the above example adjust <code>mech_list</code> to the +mechanisms that are applicable for your environment. </p> + +</blockquote> + +<h4><a name="auxprop_sql">The sql plugin</a></h4> + +<p> 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. </p> + +<blockquote> + +<strong>Tip</strong> + +<p> If you must store encrypted passwords, you cannot use the sql +auxprop plugin. Instead, see section "<a href="#saslauthd_pam">Using +saslauthd with PAM</a>", and configure PAM to look up the encrypted +passwords with, for example, the <code>pam_mysql</code> 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. </p> + +</blockquote> + +<p> The following example configures libsasl to use the sql plugin +and connects it to a PostgreSQL server: </p> + +<blockquote> +<pre> +/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' +</pre> +</blockquote> + +<blockquote> + +<strong>Note</strong> + +<p> Set appropriate permissions if <code>smtpd.conf</code> contains +a password. The file should be readable by the <code>postfix</code> +user. </p> + +</blockquote> + +<blockquote> + +<strong>Note</strong> + +<p> In the above example, adjust <code>mech_list</code> to the +mechanisms that are applicable for your environment. </p> + +</blockquote> + +<p> The sql plugin has the following configuration options: </p> + +<blockquote> + +<dl> + +<dt>sql_engine</dt> + +<dd> + +<p> Specify <code>mysql</code> to connect to a MySQL server, +<code>pgsql</code> for a PostgreSQL server or <code>sqlite</code> +for an SQLite database </p> + +</dd> + +<dt>sql_hostnames</dt> + +<dd> + +<p> Specify one or more servers (hostname or hostname:port) separated +by commas. </p> + +<blockquote> + +<strong>Note</strong> + +<p> With MySQL servers, specify <code>localhost</code> to connect +over a UNIX-domain socket, and specify <code>127.0.0.1</code> to +connect over a TCP socket. </p> + +</blockquote> + +</dd> + +<dt>sql_user</dt> + +<dd> + +<p> The login name to gain access to the database. </p> + +</dd> + +<dt>sql_passwd</dt> + +<dd> + +<p> The password to gain access to the database. </p> + +</dd> + +<dt>sql_database</dt> + +<dd> + +<p> The name of the database to connect to. </p> + +</dd> + +<dt>sql_select</dt> + +<dd> + +<p> The SELECT statement that should retrieve the plaintext password +from a database table. </p> + +<blockquote> + +<strong>Important</strong> + +<p> Do not enclose the statement in quotes! Use single quotes to +escape macros! </p> + +</blockquote> + +</dd> + +</dl> + +</blockquote> + +<p> The sql plugin provides macros to build <code>sql_select</code> +statements. They will be replaced with arguments sent from the client. The +following macros are available: </p> + +<blockquote> + +<dl> + +<dt>%u</dt> + +<dd> + +<p> The name of the user whose properties are being selected. </p> + +</dd> + +<dt>%p</dt> + +<dd> + +<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). </p> + +</dd> + +<dt>%r</dt> + +<dd> + +<p> 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. </p> + +</dd> + +</dl> + +</blockquote> + +<h4><a name="auxprop_ldapdb">The ldapdb plugin</a></h4> + +<p> The ldapdb auxprop plugin provides access to credentials stored +in an LDAP server. This plugin requires that SASL client passwords are +stored as plaintext. </p> + +<blockquote> + +<strong>Tip</strong> + +<p> If you must store encrypted passwords, you cannot use the ldapdb +auxprop plugin. Instead, you can use "<code>saslauthd -a ldap</code>" +to query the LDAP database directly, with appropriate configuration +in <code>saslauthd.conf</code>, <a +href="http://git.cyrusimap.org/cyrus-sasl/tree/saslauthd/LDAP_SASLAUTHD">as +described here</a>. 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. </p> + +</blockquote> + +<p> 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. </p> + +<p> 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. </p> + +<p> This example configures libsasl to use the ldapdb plugin and +the plugin to connect to an LDAP server: </p> + +<blockquote> +<pre> +/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 +</pre> +</blockquote> + +<blockquote> + +<strong>Important</strong> + +<p> Set appropriate permissions if <code>smtpd.conf</code> contains a +password. The file should be readable by the <code>postfix</code> +user. </p> + +</blockquote> + +<blockquote> + +<strong>Note</strong> + +<p> The shared-secret mechanisms (CRAM-MD5, etc.) require that the +SASL client passwords are stored as plaintext. </p> + +</blockquote> + +<p> The following is a summary of applicable <code>smtpd.conf</code> +file entries: </p> + +<blockquote> + +<dl> + +<dt>auxprop_plugin</dt> + +<dd> <p> Specify <code>ldapdb</code> to enable the plugin. </p> </dd> + +<dt>ldapdb_uri</dt> + +<dd> <p> Specify either <code>ldapi://</code> to connect over +a UNIX-domain socket, <code>ldap://</code> for an unencrypted TCP +connection, or <code>ldaps://</code> for an encrypted TCP connection. +</p> </dd> + +<dt>ldapdb_id</dt> + +<dd> <p> The login name to authenticate the ldapdb plugin to the +LDAP server (proxy authorization). </p> </dd> + +<dt>ldapdb_pw</dt> + +<dd> <p> The password (in plaintext) to authenticate the ldapdb +plugin to the LDAP server (proxy authorization). </p> </dd> + +<dt>ldapdb_mech</dt> + +<dd> <p> The mechanism to authenticate the ldapdb plugin to the +LDAP server. </p> + +<blockquote> + +<strong>Note</strong> + +<p> Specify a mechanism here that is supported by the LDAP server. +</p> + +</blockquote> + +</dd> + +<dt>ldapdb_rc (optional)</dt> + +<dd> <p> 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. </p> + +<blockquote> + +<strong>Note</strong> + +<p> 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. </p> + +</blockquote> + +</dd> + +<dt>ldapdb_starttls (optional)</dt> + +<dd> <p> The TLS policy for connecting to the LDAP server. Specify +either <code>try</code> or <code>demand</code>. If the option is +<code>try</code> 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 <code>demand</code> and +a TLS-encrypted connection cannot be established, the connection +fails immediately. </p> </dd> + +</dl> + +</blockquote> + +<p> 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. </p> + +<p> The following configuration gives an example of authorization configuration +in the OpenLDAP slapd server: </p> + +<blockquote> +<pre> +/etc/openldap/slapd.conf: + authz-regexp + uid=(.*),cn=.*,cn=auth + ldap:///dc=example,dc=com??sub?cn=$1 + authz-policy to +</pre> +</blockquote> + +<p> Here, the <code>authz-regexp</code> option serves for authentication +of the ldapdb user. It maps its login name to a DN in the LDAP +directory tree where <code>slapd</code> can look up the SASL account +information. The <code>authz-policy</code> options defines the +authentication policy. In this case it grants authentication +privileges "<code>to</code>" the ldapdb plugin. </p> + +<p> The last configuration step is to tell the OpenLDAP <code>slapd</code> +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: <code>authzTo</code> because the authz-policy +is "<code>to</code>") and configures the scope where the login name +"proxyuser" may search: </p> + +<blockquote> +<pre> +dn: cn=proxyuser,dc=example,dc=com +changetype: modify +add: authzTo +authzTo: dn.regex:uniqueIdentifier=(.*),ou=people,dc=example,dc=com +</pre> +</blockquote> + +<p> Use the <code>ldapmodify</code> or <code>ldapadd</code> command +to add the above attribute. </p> + +<blockquote> + +<strong>Note</strong> + +<p> Read the chapter "Using SASL" in the <a +href="http://www.openldap.org/doc/admin">OpenLDAP Admin Guide</a> +for more detailed instructions to set up SASL authentication in +OpenLDAP. </p> + +</blockquote> + +<h3><a name="server_sasl_enable">Enabling SASL authentication and +authorization in the Postfix SMTP server</a></h3> + +<p> By default the Postfix SMTP server uses the Cyrus SASL +implementation. If the Dovecot SASL implementation should be used, +specify an <code>smtpd_sasl_type</code> value of <code>dovecot</code> +instead of <code>cyrus</code>: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + smtpd_sasl_type = dovecot +</pre> +</blockquote> + +<p> Additionally specify how Postfix SMTP server can find the Dovecot +authentication server. This depends on the settings that you have +selected in the section "<a href="#server_dovecot_comm">Postfix to +Dovecot SASL communication</a>". </p> + +<ul> + +<li> <p> If you configured Dovecot for UNIX-domain socket communication, +configure Postfix as follows: </p> + +<pre> +/etc/postfix/main.cf: + smtpd_sasl_path = private/auth +</pre> + +<strong>Note</strong> + +<p> 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. </p> + +<li> <p> 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. </p> + +<pre> +/etc/postfix/main.cf: + smtpd_sasl_path = inet:127.0.0.1:12345 +</pre> + +<strong>Note</strong> + +<p> If you specify a remote IP address, information +will be sent as plaintext over the network. </p> + +</ul> + +<h4><a name="server_sasl_authc">Enabling SASL authentication +in the Postfix SMTP server</a></h4> + +<p> Regardless of the SASL implementation type, enabling SMTP +authentication in the Postfix SMTP server always requires setting +the <code>smtpd_sasl_auth_enable</code> option: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + smtpd_sasl_auth_enable = yes +</pre> +</blockquote> + +<p> 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: </p> + +<blockquote> +<pre> +% <strong>telnet server.example.com 25</strong> +... +220 server.example.com ESMTP Postfix +<strong>EHLO client.example.com</strong> +250-server.example.com +250-PIPELINING +250-SIZE 10240000 +250-AUTH DIGEST-MD5 PLAIN CRAM-MD5 +... +</pre> +</blockquote> + +<p> However not all clients recognize the AUTH capability as defined +by the SASL authentication RFC. Some historical implementations expect the +server to send an "<code>=</code>" as separator between the AUTH +verb and the list of mechanisms that follows it. </p> + +<p> The <code>broken_sasl_auth_clients</code> configuration option +lets Postfix repeat the AUTH statement in a form that these broken +clients understand: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + broken_sasl_auth_clients = yes +</pre> +</blockquote> + +<blockquote> + +<strong>Note</strong> + +<p> 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. </p> + +</blockquote> + +<p> After "postfix reload", the Postfix SMTP server will propagate +the AUTH capability twice - once for compliant and once for broken +clients: </p> + +<blockquote> +<pre> +% <strong>telnet server.example.com 25</strong> +... +220 server.example.com ESMTP Postfix +<strong>EHLO client.example.com</strong> +250-server.example.com +250-PIPELINING +250-SIZE 10240000 +250-AUTH DIGEST-MD5 PLAIN CRAM-MD5 +250-AUTH=DIGEST-MD5 PLAIN CRAM-MD5 +... +</pre> +</blockquote> + +<h4><a name="smtpd_sasl_security_options">Postfix SMTP Server policy +- SASL mechanism properties</a></h4> + +<p> 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. </p> + +<blockquote> + +<table border="1"> + +<tr> <th>Property</th> <th>Description</th> </tr> + +<tr> <td>noanonymous</td> <td> Don't use mechanisms that permit +anonymous authentication. </td> </tr> + +<tr> <td>noplaintext</td> <td> Don't use mechanisms that transmit +unencrypted username and password information. </td> </tr> + +<tr> <td>nodictionary</td> <td> Don't use mechanisms that are +vulnerable to dictionary attacks. </td> </tr> + +<tr> <td>forward_secrecy</td> <td> Require forward secrecy between +sessions (breaking one session does not break earlier sessions). +</td> </tr> + +<tr> <td>mutual_auth</td> <td> Use only mechanisms that authenticate +both the client and the server to each other. </td> </tr> + +</table> + +</blockquote> + +<h4><a name="id396877">Unencrypted SMTP session</a></h4> + +<p> The default policy is to allow any mechanism in the Postfix SMTP server +except for those based on anonymous authentication: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + # Specify a list of properties separated by comma or whitespace + smtpd_sasl_security_options = noanonymous +</pre> +</blockquote> + +<blockquote> + +<strong>Important</strong> + +<p> Always set at least the <code>noanonymous</code> option. +Otherwise, the Postfix SMTP server can give strangers the same +authorization as a properly-authenticated client. </p> + +</blockquote> + +<h4><a name="id396969">Encrypted SMTP session (TLS)</a></h4> + +<p> 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: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + smtpd_sasl_tls_security_options = $smtpd_sasl_security_options +</pre> +</blockquote> + +<p> A more sophisticated policy allows plaintext mechanisms, but +only over a TLS-encrypted connection: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + smtpd_sasl_security_options = noanonymous, noplaintext + smtpd_sasl_tls_security_options = noanonymous +</pre> +</blockquote> + +<p> To offer SASL authentication only after a TLS-encrypted session has been +established specify this: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + smtpd_tls_auth_only = yes +</pre> +</blockquote> + +<h4><a name="server_sasl_authz">Enabling SASL authorization in the Postfix +SMTP server</a></h4> + +<p> 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: </p> + +<ul> + +<li> <p> Send a message to a remote recipient. </p> </li> + +<li> <p> Use a specific envelope sender in the MAIL FROM command. </p> </li> + +</ul> + +<p> These permissions are not enabled by default. </p> + +<h4><a name="server_sasl_authz_relay">Mail relay authorization</a></h4> + +<p> With <code>permit_sasl_authenticated</code> the Postfix SMTP +server can allow +SASL-authenticated SMTP clients to send mail to remote destinations. +Examples: +</p> + +<blockquote> +<pre> +# 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 + <strong>permit_sasl_authenticated</strong> + reject_unauth_destination +</pre> + +<pre> +# 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 + <strong>permit_sasl_authenticated</strong> + reject_unauth_destination + ...other rules... +</pre> +</blockquote> + +<h4><a name="server_sasl_authz_envelope">Envelope sender address +authorization</a></h4> + +<p> 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. </p> + +<p> 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: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + <strong>smtpd_sender_login_maps = hash:/etc/postfix/controlled_envelope_senders</strong> + + smtpd_recipient_restrictions = + ... + <strong>reject_sender_login_mismatch</strong> + permit_sasl_authenticated + ... +</pre> +</blockquote> + +<p> The <code>controlled_envelope_senders</code> table specifies +the binding between a sender envelope address and the SASL login +names that own that address: </p> + +<blockquote> +<pre> +/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 +</pre> +</blockquote> + +<p> With this, the <code>reject_sender_login_mismatch</code> +restriction above will reject the sender address in the MAIL FROM +command if <code>smtpd_sender_login_maps</code> does not specify +the SMTP client's login name as an owner of that address. </p> + +<p> See also <code>reject_authenticated_sender_login_mismatch</code>, +<code>reject_known_sender_login_mismatch</code>, and +<code>reject_unauthenticated_sender_login_mismatch</code> for additional +control over the SASL login name and the envelope sender. </p> + +<h4><a name="server_sasl_other">Additional SMTP Server SASL options</a></h4> + +<p> 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. </p> + +<h4><a name="sasl_access">Per-account access control</a></h4> + +<p> 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. +</p> + +<blockquote> +<pre> +/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 +</pre> +</blockquote> + +<h4><a name="id397172">Default authentication domain</a></h4> + +<p> Postfix can append a domain name (or any other string) to a +SASL login name that does not have a domain part, e.g. "<code>john</code>" +instead of "<code>john@example.com</code>": </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + smtpd_sasl_local_domain = example.com +</pre> +</blockquote> + +<p> 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. </p> + +<h4><a name="id397205">Hiding SASL authentication from clients or +networks</a></h4> + +<p> 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. </p> + +<p> Postfix can hide the AUTH capability from these clients/networks: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + smtpd_sasl_exceptions_networks = !192.0.2.171/32, 192.0.2.0/24 +</pre> +</blockquote> + +<h4><a name="id397226">Adding the SASL login name to mail headers</a></h4> + +<p> To report SASL login names in Received: message headers (Postfix +version 2.3 and later): </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + smtpd_sasl_authenticated_header = yes +</pre> +</blockquote> + +<blockquote> + +<strong>Note</strong> + +<p> The SASL login names will be shared with the entire world. </p> + +</blockquote> + +<h3><a name="server_test">Testing SASL authentication in the Postfix SMTP Server</a></h3> + +<p> To test the server side, connect (for example, with +<code>telnet</code>) 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 <strong>bold</strong> font. +</p> + +<blockquote> +<pre> +% <strong>telnet server.example.com 25</strong> +... +220 server.example.com ESMTP Postfix +<strong>EHLO client.example.com</strong> +250-server.example.com +250-PIPELINING +250-SIZE 10240000 +250-ETRN +250-AUTH DIGEST-MD5 PLAIN CRAM-MD5 +250 8BITMIME +<strong>AUTH PLAIN AHRlc3QAdGVzdHBhc3M=</strong> +235 Authentication successful +</pre> +</blockquote> + +<p> To test this over a connection that is encrypted with TLS, use +<code>openssl s_client</code> instead of <code>telnet</code>: + +<blockquote> +<pre> +% <strong>openssl s_client -connect server.example.com:25 -starttls smtp</strong> +... +220 server.example.com ESMTP Postfix +<strong>EHLO client.example.com</strong> +...see above example for more... +</pre> +</blockquote> + +<p> Instead of <code>AHRlc3QAdGVzdHBhc3M=</code>, specify the +base64-encoded form of <code>\0username\0password</code> (the \0 +is a null byte). The example above is for a user named `<code>test</code>' +with password `<code>testpass</code>'. </p> +<blockquote> + +<strong>Caution</strong> + +<p> 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. </p> + +</blockquote> + +<p> You can use one of the following commands to generate base64 +encoded authentication information: </p> + +<ul> + +<li> <p> Using a recent version of the <b>bash</b> shell: </p> + +<blockquote> +<pre> +% <strong>echo -ne '\000username\000password' | openssl base64</strong> +</pre> +</blockquote> + +<p> Some other shells support similar syntax. </p> + +<li> <p> Using the <b>printf</b> command: </p> + +<blockquote> +<pre> +% <strong>printf '\0%s\0%s' '<em>username</em>' '<em>password</em>' | openssl base64</strong> +% <strong>printf '\0%s\0%s' '<em>username</em>' '<em>password</em>' | mmencode</strong> +</pre> +</blockquote> + +<p> The <strong>mmencode</strong> command is part of the metamail +software. </p> + +<li> <p> Using Perl <b>MIME::Base64</b> (from http://www.cpan.org/): </p> + +<blockquote> +<pre> +% <strong>perl -MMIME::Base64 -e \ + 'print encode_base64("\0<em>username</em>\0<em>password</em>");'</strong> +</pre> +</blockquote> + +<p> If the username or password contain "@", you must specify "\@". </p> + +<li> <p> Using the <b>gen-auth</b> script: </p> + +<blockquote> +<pre> +% <strong>gen-auth plain</strong> +username: <strong><em>username</em></strong> +password: +</pre> +</blockquote> + +<p> The <strong>gen-auth</strong> Perl script was written by John +Jetmore and can be found at http://jetmore.org/john/code/gen-auth. </p> + +</ul> + +<h2><a name="client_sasl">Configuring SASL authentication in the Postfix SMTP/LMTP client</a></h2> + +<p> 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. +</p> + +<blockquote> + +<strong>Note</strong> + +<p> The examples in this section discuss only the SMTP client. +Replace <code>smtp_</code> with <code>lmtp_</code> to get the +corresponding LMTP client configuration. </p> + +</blockquote> + +<p> You can read more about the following topics: </p> + +<ul> + +<li><a href="#client_sasl_enable">Enabling SASL authentication in +the Postfix SMTP/LMTP client</a></li> + +<li><a href="#client_sasl_sender">Configuring sender-dependent SASL +authentication</a></li> + +<li><a href="#client_sasl_policy">Postfix SMTP/LMTP client policy +- SASL mechanism <em>properties</em></a></li> + +<li><a href="#client_sasl_filter">Postfix SMTP/LMTP client policy +- SASL mechanism <em>names</em></a></li> + +</ul> + +<h3><a name="client_sasl_enable">Enabling SASL authentication in the +Postfix SMTP/LMTP client</a></h3> + +<p> This section shows a typical scenario where the Postfix SMTP +client sends all messages via a mail gateway server that requires +SASL authentication. </p> + +<blockquote> + +<strong> Trouble solving tips: </strong> + +<ul> + +<li> <p> If your SASL logins fail with "SASL authentication failure: +No worthy mechs found" in the mail logfile, then see the section +"<a href="SASL_README.html#client_sasl_policy">Postfix SMTP/LMTP +client policy - SASL mechanism <em>properties</em></a>". + +<li> <p> For a solution to a more obscure class of SASL authentication +failures, see "<a href="SASL_README.html#client_sasl_filter">Postfix +SMTP/LMTP client policy - SASL mechanism <em>names</em></a>". + +</ul> + +</blockquote> + +<p> 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. </p> + +<blockquote> +<pre> +/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 +</pre> +</blockquote> + +<ul> + +<li> <p> The <code>smtp_sasl_auth_enable</code> setting enables +client-side authentication. We will configure the client's username +and password information in the second part of the example. </p> +</li> + +<li> <p> The <code>smtp_tls_security_level</code> setting ensures +that the connection to the remote smtp server will be encrypted, and +<code>smtp_sasl_tls_security_options</code> removes the prohibition on +plaintext passwords. </p> + +<li> <p> The <code>relayhost</code> 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. </p> </li> + +<li> <p> In the <code>relayhost</code> setting, the "<code>[</code>" +and "<code>]</code>" prevent the Postfix SMTP client from looking +up MX (mail exchanger) records for the enclosed name. </p> </li> + +<li> <p> The <code>relayhost</code> destination may also specify a +non-default TCP port. For example, the alternative form +<code>[mail.isp.example]:submission</code> tells Postfix to connect +to TCP network port 587, which is reserved for email client +applications. </p> </li> + +<li> <p> The Postfix SMTP client is compatible with SMTP servers +that use the non-standard "<code>AUTH=<em>method.</em>...</code>" +syntax in response to the EHLO command; this requires no additional +Postfix client configuration. </p> </li> + +<li> <p> 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). </p> </li> + +<li> <p> With the <code>smtp_sasl_password_maps</code> 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. </p> + +</ul> + +<blockquote> +<pre> +/etc/postfix/sasl_passwd: + # destination credentials + [mail.isp.example] username:password + # Alternative form: + # [mail.isp.example]:submission username:password +</pre> +</blockquote> + +<blockquote> + +<strong>Important</strong> + +<p> Keep the SASL client password file in <code>/etc/postfix</code>, +and make the file read+write only for <code>root</code> 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 <code>root</code> before it drops privileges, +and before entering an optional chroot jail. </p> + +</blockquote> + +<ul> + +<li> <p> Use the <code>postmap</code> command whenever you +change the <code>/etc/postfix/sasl_passwd</code> file. </p> </li> + +<li> <p> If you specify the "<code>[</code>" and "<code>]</code>" +in the <code>relayhost</code> destination, then you must use the +same form in the <code>smtp_sasl_password_maps</code> file. </p> +</li> + +<li> <p> If you specify a non-default TCP Port (such as +"<code>:submission</code>" or "<code>:587</code>") in the +<code>relayhost</code> destination, then you must use the same form +in the <code>smtp_sasl_password_maps</code> file. </p> </li> + +</ul> + +<h3><a name="client_sasl_sender">Configuring Sender-Dependent SASL +authentication</a></h3> + +<p> 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. +</p> + +<p> 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 <code>relayhost</code> setting only as a final +resort. </p> + +<blockquote> +<pre> +/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 +</pre> +</blockquote> + +<blockquote> +<pre> +/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 +</pre> +</blockquote> + +<blockquote> +<pre> +/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] +</pre> +</blockquote> + +<ul> + +<li> <p> 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. </p> + +<li> <p> Specify <b>dbm</b> instead of <b>hash</b> if your system uses +<b>dbm</b> files instead of <b>db</b> files. To find out what lookup +tables Postfix supports, use the command "<b>postconf -m</b>". </p> + +<li> <p> Execute the command "<b>postmap /etc/postfix/sasl_passwd</b>" +whenever you change the sasl_passwd table. </p> + +<li> <p> Execute the command "<b>postmap /etc/postfix/sender_relay</b>" +whenever you change the sender_relay table. </p> + +</ul> + +<h3><a name="client_sasl_policy">Postfix SMTP/LMTP client policy - +SASL mechanism <em>properties</em></a></h3> + +<p> 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. </p> + +<blockquote> + +<table border="1"> + +<tr> <th>Property</th> <th>Description</th> </tr> + +<tr> <td>noanonymous</td> <td> Don't use mechanisms that permit +anonymous authentication. </td> </tr> + +<tr> <td>noplaintext</td> <td> Don't use mechanisms that transmit +unencrypted username and password information. </td> </tr> + +<tr> <td>nodictionary</td> <td> Don't use mechanisms that are +vulnerable to dictionary attacks. </td> </tr> + +<tr> <td>mutual_auth</td> <td> Use only mechanisms that authenticate +both the client and the server to each other. </td> </tr> + +</table> + +</blockquote> + +<h4>Unencrypted SMTP session</h4> + +<p> The default policy is stricter than that of the Postfix SMTP +server - plaintext mechanisms are not allowed (nor is any anonymous +mechanism): </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + smtp_sasl_security_options = noplaintext, noanonymous +</pre> +</blockquote> + +<p> 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 "<code>AUTH +PLAIN LOGIN</code>"). In such cases the SMTP client will log the +following error message: </p> + +<blockquote> +<pre> +SASL authentication failure: No worthy mechs found +</pre> +</blockquote> + +<blockquote> + +<strong>Note</strong> + +<p> This same error message will also be logged when the +<code>libplain.so</code> or <code>liblogin.so</code> modules are +not installed in the <code>/usr/lib/sasl2</code> directory. </p> + +</blockquote> + +<p> The insecure approach is to lower the security standards and +permit plaintext authentication mechanisms: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + smtp_sasl_security_options = noanonymous +</pre> +</blockquote> + +<p> 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 <strong>bold</strong> +font. </p> + +<blockquote> +<pre> +% <strong>telnet server.example.com 25</strong> +... +220 server.example.com ESMTP Postfix +<strong>EHLO client.example.com</strong> +250-server.example.com +250-PIPELINING +250-SIZE 10240000 +250-STARTTLS +... +</pre> +</blockquote> + +<p> Instead of port 25 (smtp), specify port 587 (submission) where +appropriate. </p> + +<h4>Encrypted SMTP session (TLS)</h4> + +<p> To turn on TLS in the Postfix SMTP client, see TLS_README for +configuration details. </p> + +<p> 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: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + smtp_sasl_tls_security_options = $smtp_sasl_security_options +</pre> +</blockquote> + +<p> A more sophisticated policy allows plaintext mechanisms, but +only over a TLS-encrypted connection: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + smtp_sasl_security_options = noanonymous, noplaintext + smtp_sasl_tls_security_options = noanonymous +</pre> +</blockquote> + +<h3><a name="client_sasl_filter">Postfix SMTP/LMTP client policy - +SASL mechanism <em>names</em></a></h3> + +<p> 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.</p> + +<p> 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. </p> + +<p> The following example filters out everything but the mechanisms +<code>PLAIN</code> and <code>LOGIN</code>: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + smtp_sasl_mechanism_filter = plain, login +</pre> +</blockquote> + +<blockquote> + +<strong>Note</strong> + +<p> If the remote server does not offer any of the mechanisms on +the filter list, authentication will fail. </p> + +</blockquote> + +<p> We close this section with an example that passes every mechanism +except for <code>GSSAPI</code> and <code>LOGIN</code>: </p> + +<blockquote> +<pre> +/etc/postfix/main.cf: + smtp_sasl_mechanism_filter = !gssapi, !login, static:all +</pre> +</blockquote> + +<h2><a name="postfix_build">Building Postfix with SASL support</a></h2> + +<p> 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. +</p> + +<ul> + +<li><a href="#build_dovecot">Building Dovecot SASL support</a></li> + +<li><a href="#sasl_support">Building Cyrus SASL support</a></li> + +</ul> + +<h3><a name="build_dovecot">Building Dovecot SASL support</a></h3> + +<p> 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. </p> + +<p> 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. </p> + +<p> 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. </p> + +<p> To generate the necessary Makefiles, execute the following in +the Postfix top-level directory: </p> + +<blockquote> +<pre> +% <strong>make tidy</strong> # if you have left-over files from a previous build +% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH \ + -DDEF_SERVER_SASL_TYPE=\\\"dovecot\\\""</strong> +</pre> +</blockquote> + +<p> After this, proceed with "<code>make</code>" as described in +the INSTALL document. </p> + +<strong>Note</strong> + +<ul> + +<li> + +<p> The <code>-DDEF_SERVER_SASL_TYPE=\\\"dovecot\\\"</code> 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 <code>cyrus</code>). </p> + +</li> + +<li> + +<p> If you also want support for LDAP or TLS (or for Cyrus SASL), +you need to merge their <code>CCARGS</code> and <code>AUXLIBS</code> +options into the above command line; see the LDAP_README and +TLS_README for details. </p> + +<blockquote> +<pre> +% <strong>make tidy</strong> # if you have left-over files from a previous build +% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH \ + -DDEF_SERVER_SASL_TYPE=\\\"dovecot\\\" \ + ...<i>CCARGS options for LDAP or TLS etc.</i>..." \ + AUXLIBS="...<i>AUXLIBS options for LDAP or TLS etc.</i>..."</strong> +</pre> +</blockquote> + +</li> + +</ul> + +<h3><a name="sasl_support">Building Cyrus SASL support</a></h3> + +<h4><a name="build_sasl">Building the Cyrus SASL library</a></h4> + +<p> 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. </p> + +<blockquote> + +<strong>Important</strong> + +<p> If you install the Cyrus SASL libraries as per the default, you will have +to create a symlink <code>/usr/lib/sasl</code> -> +<code>/usr/local/lib/sasl</code> for version 1.5.x or +<code>/usr/lib/sasl2</code> -> <code>/usr/local/lib/sasl2</code> +for version 2.1.x. </p> + +</blockquote> + +<p> 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: </p> + +<blockquote> +<pre> +% <strong>./configure --enable-login --enable-ntlm</strong> +</pre> +</blockquote> + +<h4><a name="build_postfix">Building Postfix with Cyrus SASL support</a></h4> + +<p> 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. </p> + +<p> The following assumes that the Cyrus SASL include files are in +<code>/usr/local/include</code>, and that the Cyrus SASL libraries are in +<code>/usr/local/lib</code>. </p> + +<p> On some systems this generates the necessary <code>Makefile</code> +definitions: </p> + +<dl> + +<dt>Cyrus SASL version 2.1.x</dt> + +<dd> + +<pre> +% <strong>make tidy</strong> # if you have left-over files from a previous build +% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \ + -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib -lsasl2"</strong> +</pre> + +<p> 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". </p> + +</dd> + +<dt>Cyrus SASL version 1.5.x</dt> + +<dd> + +<pre> +% <strong>make tidy</strong> # if you have left-over files from a previous build +% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \ + -I/usr/local/include" AUXLIBS="-L/usr/local/lib -lsasl"</strong> +</pre> + +</dd> + +</dl> + +<p> 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: </p> + +<dl> + +<dt>Cyrus SASL version 2.1.x</dt> + +<dd> + +<pre> +% <strong>make tidy</strong> # remove left-over files from a previous build +% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \ + -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib \ + -R/usr/local/lib -lsasl2"</strong> +</pre> + +</dd> + +<dt>Cyrus SASL version 1.5.x</dt> + +<dd> + +<pre> +% <strong>make tidy</strong> # if you have left-over files from a previous build +% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \ + -I/usr/local/include" AUXLIBS="-L/usr/local/lib \ + -R/usr/local/lib -lsasl"</strong> +</pre> + +</dd> + +</dl> + +<h2><a name="cyrus_legacy">Using Cyrus SASL version 1.5.x</a></h2> + +<p> Postfix supports Cyrus SASL version 1.x, but you shouldn't use +it unless you are forced to. The makers of Cyrus SASL write: </p> + +<blockquote> <i> This library is being deprecated and applications +should transition to using the SASLv2 library</i> (source: <a +href="http://www.cyrusimap.org/download.html">Project Cyrus: +Downloads</a>). </blockquote> + +<p> If you still need to set it up, here's a quick rundown: </p> + +<p> Read the regular section on SMTP server configurations for the +Cyrus SASL framework. The differences are: </p> + +<ul> + +<li> <p> Cyrus SASL version 1.5.x searches for configuration +(<code>smtpd.conf</code>) in <code>/usr/lib/sasl/</code> only. You +must place the configuration in that directory. Some systems may +have modified Cyrus SASL and put the files into e.g. +<code>/var/lib/sasl/</code>. </p> </li> + +<li> <p> Use the <code>saslpasswd</code> command instead of +<code>saslpasswd2</code> to create users in <code>sasldb</code>. +</p> </li> + +<li> <p> Use the <code>sasldblistusers</code> command instead of +<code>sasldblistusers2</code> to find users in <code>sasldb</code>. +</p> </li> + +<li> <p> In the <code>smtpd.conf</code> file you can't use +<code>mech_list</code> to limit the range of mechanisms offered. +Instead, remove their libraries from <code>/usr/lib/sasl/</code> +(and remember remove those files again when a system update +re-installs new versions). </p> </li> + +</ul> + +<h2><a name="credits">Credits</a></h2> + +<ul> + +<li> Postfix SASL support was originally implemented by Till Franke +of SuSE Rhein/Main AG. </li> + +<li> Wietse trimmed down the code to only the bare necessities. + </li> + +<li> Support for Cyrus SASL version 2 was contributed by Jason Hoos. +</li> + +<li> 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. + </li> + +<li> 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. </li> + +<li> The Dovecot SMTP server-only plug-in was originally implemented +by Timo Sirainen of Procontrol, Finland. </li> + +<li> Patrick Ben Koetter revised this document for Postfix 2.4 and +made much needed updates. </li> + +<li> Patrick Ben Koetter revised this document again for Postfix +2.7 and made much needed updates. </li> + +</ul> + +</body> + +</html> + |