diff options
Diffstat (limited to 'README_FILES/SASL_README')
| -rw-r--r-- | README_FILES/SASL_README | 1418 |
1 files changed, 1418 insertions, 0 deletions
diff --git a/README_FILES/SASL_README b/README_FILES/SASL_README new file mode 100644 index 0000000..0c42480 --- /dev/null +++ b/README_FILES/SASL_README @@ -0,0 +1,1418 @@ +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:// for to connect over a UNIX-domain socket, ldap: + // for an unencrypted TCP connection or ldaps:// for an encrypted TCP + connection. + + ldapdb_id + The login name to authenticate the ldapdb plugin to the LDAP server + (proxy authorization). + + ldapdb_pw + The password (in plaintext) to authenticate the ldapdb plugin to the + LDAP server (proxy authorization). + + ldapdb_mech + The mechanism to authenticate the ldapdb plugin to the 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. + + * The Postfix SMTP client does not support the obsolete "wrappermode" + protocol, which uses TCP port 465 on the SMTP server. See TLS_README for a + solution that uses the stunnel command. + + * 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 dbm instead of hash if your system uses dbm files instead of db + files. To find out what lookup tables Postfix supports, use the command + "postconf -m". + + * Execute the command "postmap /etc/postfix/sasl_passwd" whenever you change + the sasl_passwd table. + + * Execute the command "postmap /etc/postfix/sender_relay" 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 sasl). + + * 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 ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/. + + 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"" + +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. + |