Postfix SMTP Authentication Devin L. Ganger Last updated: Wednesday, 16 Jan 2002 Refers to: Postfix 1.11.x release versions 0. Updates =========== 07 Jan 2003: Added 2.0 incompatibility warning. 28 Nov 2002: Fixed a typo (/usr/lib/sasl). 16 Jan 2002: Added the Updates section. Fixed two typos (method_pwcheck and -d option of saslpasswd). 1. Introduction ================ NOTE: This document is only applicable to the 1.11.x release versions of Postfix. It does not apply to the 1.11.x snapshot line, nor to Postfix 2.0, as those incorporate the SASLv2 libraries. Although SMTP is in daily use upon millions of hosts around the world, one of its main flaws as it was originally defined [1] was the lack of any sort of authentication mechanism. At the time it was written, there was a much higher level of general trust amongst the members of the Internet community. It should be noted for fairness that this inherent attitude of trust is endemic in all levels of Internet protocols, not just SMTP. As the entry barriers dropped and a growing number of people came on-line, the flaws with this trust model became more obvious as the trust itself became more abused. This flaw, coupled with both the default policies of many SMTP implementations and the ease of spoofing the IP protocols, has resulted in widespread abuses of the SMTP infrastructure. This lack of authentication capability is a two-way problem; not only is the SMTP server unable to trust that the client is who it claims to be, the SMTP client is unable to trust that a given server is legitimate. The Postfix mail system's wide variety of configuration options help administrators combat abuse by allowing precise restriction of the server's resources and how they are made available for the use of others. These mechanisms, however, rely upon one of two weak authentication methods: IP address and DNS information. There are other methods such as POP-before-SMTP, but these require extra services to run and typically involve kludgey integration with Postfix and other mail agents. 2. SMTP Authentication ======================= The Simple Authentication Security Layer (SASL) [3] -- combined with the SMTP AUTH extension [4] -- provides a modular framework to mail servers and client. AUTH support in SMTP is built upon SASL, which provides an open layer of mechanisms and protocols to be used in establishing authenticated sessions. SASL implements the actual protocols (PLAIN and CRAM-MD5 to name some examples) as well as providing a consistent API to a variety of authentication mechanisms (such as Kerberos, a special database, or the system password file). This allows authentication to be implemented using a variety of methods, without support for them having to be explicitly code into each mail application. Likewise, the local policy decisions on what access or service level is granted by the mail server after a successful authentication is left to the configuration of the mail server. SMTP AUTH is not a cure-all for security issues. It does not provide any sort of way to encrypt the SMTP session; in fact, some of the security protocols supported by SASL send the authentication credentials in the clear rendering them vulnerable to sniffing. It is up to each administrator to allow or restrict the various protocols as appropriate for their security policy. Authentication is most useful for determining which level of service to provide to a session, such as allowing authenticated clients to relay mail while disallowing it generally. However, it may be used in conjunction with other security techniques such as session encryption via SSL/TLS. SMTP AUTH support for Postfix was first introduced by Till Franke in August 1999 as a patch against snapshot-19990627. It was officially rolled in to the Postfix source in snapshot-20000507. The current support is based on the Cyrus SASL library [5] and has been tested against cyrus-sasl-1.5.5 and up. Here's a sample dialogue between two Postfix servers using SMTP AUTH, saslserve.example.com and saslclient.example.com: 01: S: 220 saslserve.example.com ESMTP 02: C: EHLO saslclient.example.com 03: S: 250-saslserve.example.com 04: S: 250-PIPELINING 05: S: 250-SIZE 10240000 06: S: 250-ETRN 07: S: 250-AUTH LOGIN DIGEST-MD5 CRAM-MD5 PLAIN 08: S: 250 8BITMIME 09: C: AUTH LOGIN 10: S: 334 VXNlcm5hbWU6 11: C: Ym9maA== 12: S: 334 UGFzc3dvcmQ6 13: C: Ym9maA== 14: S: 235 Authentication successful 15: C: MAIL FROM: SIZE=697 16: S: 250 Ok 17: C: RCPT TO: 18: S: 250 Ok 19: C: DATA 20: S: 354 End data with . 21: S: 250 Ok: queued as 1CF2E1D962 22: C: QUIT 23: S: 221 Bye The use of EHLO in line 2 allows saslserve to respond with a list of SMTP extensions that it supports, including AUTH (line 7). Notice that AUTH supports four authentication protocols: LOGIN, DIGEST-MD5, CRAM-MD5, and PLAIN. In line 9, saslclient responds with AUTH LOGIN, indicating that it wishes to have an authenticated login using the LOGIN protocol. Lines 10 through 13 are the ensuing dialogue, concluding on line 14 with saslserve announcing successful authentication. Lines 15 through 23 are the rest of a normal SMTP session. You may find further examples of AUTH-enabled sessions in RFC 2554. 3. Enabling AUTH support in Postfix ==================================== Several operating systems and distributions provide the Cyrus SASL library in binary package format; check with your vendor for details. Be certain that your version of Postfix has SASL support. If it is older than snapshot-19990627, you will have to upgrade. For all versions older than snapshot-19990627 and before snapshot-20000507, you will have to download Till Franke's patch. It is highly recommended that you upgrade to a version no lower than release-20010228 if you have to upgrade. Also, you may wish to upgrade Postfix without enabling SASL support first, in order to minimize the number of complications that you have to deal with. Only proceed with enabling SASL support when you are certain that the everything else is working correctly. Be certain to review the options that were used to compile the library and Postfix; if they are not compatible, you will have to recompile at least one component. Compiling the Cyrus SASL libraries ---------------------------------- The first thing you need is a version of the Cyrus SASL library. Versions 1.5.5 or greater are reported to work with Postfix; the most recent non-beta release of the library as of this writing is 1.5.24, the latest beta is 1.5.27. You may find the source distributions via FTP at: ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/ If you are installing the SASL libraries from source, follow the instructions in the INSTALL file in the root of the source directory. The basic installation sequence is: cd cyrus-sasl- ./configure make make install ln -s /usr/local/lib/sasl /usr/lib/sasl By default, this will install the SASL libraries into the /usr/local/lib directory and headers into the /usr/local/include directory. Additional libraries for the authentication mechanisms into the /usr/local/lib/sasl directory. If you have changed the location of this last directory, be sure to modify the above symbolic link appropriately. If you are planning on offering authenticated SMTP to incoming sessions, create the /usr/local/lib/sasl/smtpd.conf file and make it readable by the Postfix user. See section 4 for details of what to place in this file. Various of the following options may not apply to your version of the SASL library; be sure to read the documentation for details. Be sure only to enable the authentication protocols and mechanisms that you need. This may mean modifying the defaults that configure will use (defaults for 1.5.24 are listed below). The following options to configure should be specified under the following circumstances: --enable-login You wish to support the Outlook Express 5.x client, which uses the non-standard, undocumented LOGIN protocol. Passwords are passed over the wire in the clear. This is disabled by default. --disable-krb4 Do not support the Kerberos version 4 protocol. Unless you know that it will be used, turn it off, as it is enabled by default. --disable-gssapi Do not support the Kerberos version 5 (GSSAPI) protocol. Enabled by default. --disable-anon Do not use the ANONYMOUS protocol (same as using no authentication). Enabled by default. --disable-plain Do not use the PLAIN protocol, which sends the password in plaintext. This is enabled by default and should only be used for testing unless you are encrypting the session via TLS, IPsec, or other mechanism. --enable-pwcheck Enable support for the pwcheck daemon. See section 4 or the SASL documentation for more details. You must specify a shared directory for the daemon and SASL to use. Disabled by default. (--enable-pwcheck=/shared/dir) If you use the above options with 1.5.24, you will only be left with the DIGEST-MD5 and CRAM-MD5 methods. If you have DES and RC4 libraries in standard locations, SASL will automatically add support for those encryptions to the DIGEST-MD5 method. If your system uses PAM, SASL will enable that as an authentication mechanism (default on Solaris and Linux). Compiling Postfix ----------------- If you installed SASL somewhere other than in /usr/local, make the necessary changes below. Follow the basic Postfix installation instructions. However, you must specify "-DUSE_SASL_AUTH" in CCARGS and "-lsasl" before running make. If the directories the SASL libraries and headers live in are not already specified, you should also add "-I/usr/local/include" and "-L/usr/local/lib" to CCARGS and AUXLIBS respectively. On Solaris 2.x, the dynamic linker will not find the SASL shared library unless you give it the appropriate run-time information. Add "-R/usr/local/lib" to AUXLIBS. Once Postfix compiles properly, install it and verify that all your normal functionality is still working. 4. Configuring AUTH in the SMTP server (smtpd) =============================================== The options in this section only affect the smtpd process (in other words, incoming authentication sessions). If you do not wish to provide authentication to incoming sessions, you may ignore this section; you will still be able to seperately configure outbound authentication. Additional Cyrus SASL configuration ----------------------------------- In /usr/local/lib/sasl/smtpd.conf, you need to add one of the following lines to tell the SASL library where to pull authentication information: pwcheck_method: pam SASL will integrate with your system's PAM libraries, if support is compiled in, and authenticate versus the database specified by pam. This is the only way to use services such as LDAP and RADIUS, in theory. This may be used with PLAIN, LOGIN, and other plaintext authentication protocols. pwcheck_method: shadow SASL looks for the username and password using /etc/shadow. This means that the Postfix user must have read access to /etc/shadow. It is recommended that you create a special group to have the group ownership of the shadow file and give the Postfix user membership in that group instead of in the regular group shadow is owned by. pwcheck_method: sasldb This method uses the /etc/sasldb database to check passwords and secrets. You must use this method to allow DIGEST-MD5 or CRAM-MD5 ( or SCRAM-MD5 if you enabled it) authentication. Add users to this file using the saslpasswd utility. If you have SASL 1.5.12 or later, you must add at least one set of credentials to the file to properly initialize it before it will be used. The Postfix user needs read access to this file, and may need write access as well with pre-compiled SASL libraries. pwcheck_method: pwcheck This is an alternative to giving the Postfix user read access to the /etc/shadow file. In theory, the pwcheck helper daemon runs as root and interfaces with the SASL library. This is not yet adequately documented by Cyrus. Additional notes on /etc/sasldb ------------------------------- To enter credential sets into the sasldb file, use the saslpasswd utility (located in /usr/local/sbin). It has the following command line options (see the man pages for more details): -c create username/password if it does not already exist -d delete username/password -u specify the authentication realm (must match the value of the smtpd_sasl_local_domain parameter in main.cf) Use the sasldblistusers command to list the credentials contained within /etc/sasldb. Permissions on /etc/sasldb should not allow regular users read or write access. Configuring Postfix ------------------- The following are the new parameters in main.cf that affect SMTP authentication in the server: broken_sasl_auth_clients Set this equal to yes to enable support for older clients that expect AUTH= instead of AUTH. This will result in Postfix giving two AUTH banners, i.e.: 250-AUTH=LOGIN PLAIN 250-AUTH LOGIN PLAIN This is required to allow Outlook Express 4.x to authenticate. smtpd_sasl_auth_enable Set this equal to yes to enable the advertisement of AUTH in the ESMTP capabilities. smtpd_sasl_local_domain Set this equal to the value of the authentication realm that the Postfix smtpd process should attempt to authenticate sessions against. At this point, it has no effect if you are not using sasldb. Traditionally, this is set equal to $myhostname. There is no provision for the client to specify the realm, and at this time, Postfix has no support for multiple authentication domains (which could be useful for hosting multiple virtual domains). smtpd_sasl_security_options If set to noplaintext, Postfix will not advertise methods that use plaintext passwords (PLAIN and LOGIN). If set to noanonymous, Postfix will not advertise methods that allow anonymous authentication (ANON). If set to nodictionary, Postfix will not advertise methods that are vulnerable to passive (dictionary) attack. If set to noactive, Postfix will not advertise methods that are vulnerable to active (non-dictionary) attack. The following is a new restriction that may be used in main.cf to define behavior allowed to authenticated clients: permit_sasl_authenticated When used in smtpd_recipient_restrictions or smtpd_client_restrictions, this grants permission to authenticated clients. When used in smtpd_client restrictions, smtpd_delay_reject must be set to yes. This will disallow any non-authenticated connections. For examples of the main.cf parameters, see the sample-auth.cf file in your /etc/postfix directory. For authenticated sessions, Postfix will log the username provided by the remote host, the requested authentication method, and the sender address. It does not log any further information (unless the debug options in main.cf are specified and match the remote host) and does not alter the headers of the message in any way to indicate that AUTH was used. Handling broken clients ----------------------- Microsoft Outlook Express requires special handling; unfortunately, each major release requires a different workaround. For 4.x, set "broken_sasl_auth_clients = yes" in the main.cf file. For 5.x, make sure that SASL has been compiled with --enable-login and that you have not disabled plaintext methods (for more information, see smtpd_sasl_security_options). 5. Configuring AUTH in the SMTP client (smtp) ============================================== The options in this section only affect the smtp process (in other words, outgoing authentication sessions). If you do not wish to use authentication in outgoing sessions, you may ignore this section; you will still be able to separately configure outbound authentication. No additional configuration of the SASL library is required. The following are the new parameters in main.cf that affect SMTP authentication in the client: smtp_sasl_auth_enable Set this to yes to allow Postfix to attempt to authenticate on outbound connections. smtp_sasl_password_maps Set this to the map that stores the outgoing credential information (example: hash:/etc/postfix/sasl_passwd). This is not the same database as /etc/sasldb; you cannot use that to supply outgoing credentials.. smtp_sasl_security_options If set to noplaintext, Postfix will not use methods that use plaintext passwords (PLAIN and LOGIN). If set to noanonymous, Postfix will not use methods that allow anonymous authentication (ANON). If set to nodictionary, Postfix will not use methods that are vulnerable to passive (dictionary) attack. If set to noactive, Postfix will not use methods that are vulnerable to active (non-dictionary) attack. If Postfix cannot use authentication with this destination without violating this parameter, even if credentials are defined, then it will not. You must create a new map to store the credentials that Postfix will use when it connects with remote systems. Create a textfile (/etc/postfix/sasl_passwd, formatted in the following fashion, one line for each remote system: destination username:password If no password is required, you may use: destination username The destination may be either a FQDN of a remote host or a domain name serviced by multiple hosts. Postfix will first attempt to find the server hostname in this map; if it does not, then it will attempt to find the destination host name. If the destination is serviced by a server farm that all share the same authentication database, you should set this to be the domain name instead of adding a line for each server. The Postfix SMTP client will detect and properly authenticate against clients that use the older, non-standard AUTH= banner. One quirk of the using AUTH with the SMTP client is that the host information matched in the client password map must exist in DNS, even if you are using a different naming service such as NIS or host files. Remember that SMTP AUTH clients use the first mutually-supported method in the AUTH banner. 6. Advanced topics =================== Using chroot jails with AUTH ---------------------------- In theory, Postfix can be run chrooted and use AUTH. However, the current implementation requires many configuration files and libraries to be copied into the jail in order for this to work; it may be impractical to do so. No one has yet reported back details on how they have done this. The SMTP client password map (/etc/postfix/sasl_passwd) is opened by Postfix before entering the jail Using AUTH over secure connections ---------------------------------- The SMTP AUTH extension may be used concurrently with TLS [6] (formerly SSL) encryption for the SMTP session. Although no support for this is provided in stock Postfix, patches are available against postfix-release-20010228 from the following site: http://www.aet.tu-cottbus.de/personen/jaenicke/pfixtls/ Detailed discussion of this patch is beyond the scope of this document. 7. References ============== [1] Postel, J., "Simple Mail Transfer Protocol", RFC 821, August 1982. [2] Kensin, J., Freed, N, Rose, M, Stefferud, E. and D. Crocker, "SMTP Service Extensions", STD 10, RFC 1869, November 1995. [3] Myers, J., "Simple Authentication and Security Layer (SASL)", RFC 2222, October 1997. [4] Myers, J., "SMTP Authentication", RFC 2554, Marc 1999. [5] The Cyrus Project SASL Library, http://asg2.web.cmu.edu/sasl/ [6] Hoffman, P., "SMTP Service Extension for Secure SMTP over TLS", RFC 2487, January 1999