10.9 Support SMTP AUTH

Support for the SMTP extension AUTH, as defined by RFC2554, was first included in sendmail beginning with V8.10. In this section we first show how to include AUTH support inside sendmail, then how to verify that it works, and finally, how to use it. The steps to take are:

Download, compile, install, and configure the Cyrus SASL library.
Build and install sendmail with SASL support included.
Configure your client machines to use SASL.

Before we begin, however, let's consider why you might want AUTH support, or why you might not need it.

SMTP AUTH is intended to prevent untrusted machines from using your mail-sending machines to send undesirable mail, such as spam. If yours is just a lone Linux box used to send and receive personal email, and you don't travel, SMTP AUTH will probably not be of use to you. For SMTP AUTH to have value, yours must be a network that supports laptops or other portable machines that can be removed and installed without system administration oversight, and where those permanent machines all need to trust each other. The larger your site, the more likely it is that you will need to use SMTP AUTH as one more layer of email protection. A mail gateway machine that is a frontend for many PC and laptop machines is one situation where such trust is desirable, and we will use it as an example throughout this section.

10.9.1 Get and Install the SASL Library

As of this writing, the Cyrus SASL library is available from ftp://ftp.andrew.cmu.edu/pub/cyrus-mail.

Always download and install the latest version. As of this writing, version 1.5.27 is the latest, the one officially supported by V8.12 sendmail, and thus is the one we document here.^[27] After you have downloaded and extracted the source, first examine the file INSTALL. It tells you how to build and install the library.

^[27] Version 2.1 is also available, but is not officially supported by V8.12. V8.12.5 and above include unofficial support for 2.1, and V8.13 will include official support for it.

The first step is to configure the package for your machine:

# ./configure --enable-login

Be patient. This step can be quite slow on some machines, but pay attention to any warnings. For example:

configure: warning: No DES library found for Kerberos V4 support

A warning such as this indicates that you will not be able to perform DES encryption unless you download and install the Kerberos package.^[28] The second step is to compile (build) the library. Just enter the following command:

^[28] We don't cover Kerberos in this book. You can find information about Kerberos at http://web.mit.edu/kerberos/www.

# make

If your compile fails, first look through the documentation that was supplied with the source. If you don't find your answer there, visit this web site for additional help: http://asg.web.cmu.edu/sasl/.

The last step is to install the package, like this:

# make install

By default, the package installs its plug-ins in /usr/local/lib/sasl, but the library looks for them in /usr/lib/sasl. Although the install process won't make a link for you, we recommend you create the required link with a command such as:

# cd /usr/lib
# ln -s ../local/lib/sasl

These directories need to be secure. That is, they need to live in paths, all components of which are writable only by root and owned by root. For example, the following command run on our system showed that permissions were correct:

% ls -ld / /usr /usr/lib /usr/lib/sasl /usr/local /usr/local/lib /usr/local/lib/sasl
drwxr-xr-x  18 root  wheel   512 Mar 15 20:08 /
drwxr-xr-x  22 root  wheel   512 Sep 29  2000 /usr/
drwxr-xr-x   4 root  wheel  7168 Jan  3 11:34 /usr/lib/
lrwxr-xr-x   1 root  wheel    19 Jan  3 11:34 /usr/lib/sasl@ -> /usr/local/lib/sasl
drwxr-xr-x  18 root  wheel   512 Oct 11  2000 /usr/local/
drwxr-xr-x   9 root  wheel  2560 Jan  3 11:29 /usr/local/lib/
drwxr-xr-x   2 root  wheel   512 Jan  3 11:29 /usr/local/lib/sasl/

If you change the location of these directories from the default, you will need to specify the new locations when you build sendmail, as shown later.

As a part of tuning SASL, you need to create a file called /usr/lib/sasl/Sendmail.conf. We don't describe that file here. Instead we advise you to check the README file in the Cyrus SSL source directory.

As a further part of tuning SASL for your site, you might optionally decide ahead of time to offer CRAM-MD5 and DIGEST-MD5 modes as part of the ESMTP AUTH extension. If so, you enable them by running the saslpasswd program, which is located in the util subdirectory of the SASL source tree (and is installed in the /usr/local/sbin directory):

# util/saslpasswd  user

Here, user is the login name of the user for whom you wish to set up an SASL authentication password. Again, see the documents in the SASL source tree's doc subdirectory, and the manual page for saslpasswd(8) for more information.

10.9.2 Add SASL Support to sendmail

To add SASL support to sendmail, just add the following line to your Build m4 file (Section 2.4):

APPENDDEF(`confENVDEF', `-DSASL')
APPENDDEF(`conf_sendmail_LIBS', `-lsasl')

The first line causes SASL support to be included in the sendmail program.^[29] The second line tells the compiler to use the SASL library. If you installed the SASL library in the standard location as described in the previous section, these two additional Build lines might be all you need.

^[29] If you have an SASL library version earlier than 1.5.10, you should upgrade to the latest version. If you cannot upgrade, or choose not to, you must define the value for SASL to be the version number of the SASL library you currently use. Your current version has the form a.b.c (as 1.5.9). You create a single number where b and c are each two digits, thus 1.5.9 becomes 10509. You then define SASL with that number:

Build sendmail as usual. If you get the following error (or something similar):

sendmail.h:127: sasl.h: No such file or directory

you will have to add another line to your Build m4 file. That additional line will look something like this:

APPENDDEF(`confINCDIRS', `-I/disk/3/packages/sasl/include')
                              
        the path to where the SASL include files are located

Another possible problem might be that the SASL library cannot be found. In that instance, an error message such as the following might appear:

ld: cannot open -lsasl: No such file or directory

To correct this problem, simply add the following line to your Build m4 file:^[30]

^[30] On your system, the -L might have to be -R instead, or you might have to use both.

APPENDDEF(`confLIBDIRS', `-L/disk/3/packages/sasl/lib')
                              
           the path to where the SASL library is located

But be careful about where you have located this library. The SASL library is a shared library and as such is subject to security restrictions. When sendmail runs, it ignores LD_LIBRARY_PATH and so cannot find shared libraries that are not in your operating system's default locations. Typically, that trusted location is /usr/lib, and sometimes /usr/local/lib. If sendmail appears to build correctly, but doesn't produce the AUTH keyword as shown next, the problem might be that your location for the SASL library is bad.

10.9.2.1 Test SASL support in sendmail

Before you install sendmail, test it to be sure the added SASL support has worked. You can do this by running sendmail from the directory in which it was built. Note that you must do this as root for SASL to work:

# obj.*/sendmail/sendmail -bs -Am

Here, we run the newly built sendmail relative to the source directory. The -bs tells sendmail to speak SMTP on its standard input. The -Am tells sendmail to use its server configuration file (not submit.cf), even though it is running in mail-submission mode. Such a test session might look like this:

220 your.host.domain ESMTP Sendmail 8.12.7/8.12.7; Mon, 14 Jan 2002 11:43:02 -0700 
(PST)
ehlo your.host.domain 
250-your.host.domain Hello root@localhost, pleased to meet you
250-ENHANCEDSTATUSCODES
250-PIPELINING
250-8BITMIME
250-SIZE
250-DSN
250-ETRN
250-AUTH DIGEST-MD5 CRAM-MD5               note this line
250-DELIVERBY
250 HELP
quit 
221 2.0.0 your.host.domain closing connection

Here, the AUTH SMTP keyword appears, indicating that this site supports SASL authentication and two modes of authentication as shown earlier.

If the AUTH keyword does not appear, you have a problem. First, be sure you ran the test as root. Otherwise it will fail. If you ran as root and the test still failed, examine your syslog file (Section 14.3). Look for a line that contains the word SASL. One such error might look, in part, like this:

SASL error: listmech=0, num=0

Here, zero authentication mechanisms were found (the num=0). One possible reason might be that you did not install the SASL library in a path that was acceptable for shared libraries. Another possible reason for this error might be that you have not set up any mechanisms yet. Consider running the saslpasswd(8) program as described in Section 10.9.1.

If no SASL lines appear in your syslog file, look for errors relating to permissions. One possible error might be that the /etc directory is unsafe.^[31] Another might be that the directory pointed to by the symbolic link /usr/lib/sasl is unsafe. Revise any offending permissions and rerun the test until it succeeds.

^[31] Every component of a safe directory path must be owned and writable only by root.

If no problems appear in your syslog file, and AUTH still fails to appear, consider increasing the LogLevel setting in sendmail to 13, while running the test again:

# obj.*/sendmail/sendmail -OLogLevel=13 -bs -Am

Then recheck your log file for additional error information.

10.9.3 SASL and Your mc File

V8.10 sendmail and above offer macros for your mc configuration file that help with your SASL settings. We cover them soon, but first we must describe two concepts central to SASL and its use: authorization and authentication.

Authorization refers to a user's permission to perform certain actions. One form of authorization, for example, might be to allow a user to relay mail through your mail hub machine. In general, authorization is associated with a user's identifier (userid).

Authentication refers to the validation of a user or machine's identity. One form of authentication, for example, might be the recognition that a laptop is a company-owned machine. Authentication is communicated inside credentials (more on this soon) and is associated with a client's identifier (authid).

The AuthMechanisms option (AuthMechanisms) is used to define a list of mechanisms that can be used to authenticate a connection. If, for example, you wish to limit your authentication mechanisms to just CRAM-MD5, you can define confAUTH_MECHANISMS in your mc file like this:

define(`confAUTH_MECHANISMS', `CRAM-MD5')

The class $={TrustAuthMech} contains a list of authentication mechanisms that allow relaying. It also contains a subset, or a matching set, of the list of all authentication mechanisms defined with the AuthMechanisms option, described earlier. For example:

TRUST_AUTH_MECH(`CRAM-MD5')

Here, sendmail will authenticate using that mechanism, and the authentication (if successful) will provide an authorization to relay.

For V8.10 and V8.11, the default authorization information for the local machine acting as a client is contained in the file /etc/mail/default-auth-info. Beginning with V8.12, that information is contained in the access database unless you tell sendmail otherwise by declaring the authinfo feature (FEATURE(authinfo)):

FEATURE(`authinfo')  V8.12 and above

The file or database, if present, must live in a safe directory and must be given secure permissions. It contains the information needed to authenticate a client (outbound) connection, and its contents are described in detail in DefaultAuthInfo. Note that the DefaultAuthInfo option is deprecated as of V8.12, and the information in that file is instead looked up by default in the access database.

If you wish to force all connections to be authenticated, you can do so by specifying the a key-letter to the DaemonPortOptions option (DaemonPortOptions). But note that you must not do this on a publicly accessible MTA that serves the Internet. You can do it on client machines on your internal network, where those client machines connect only to your Internet mail server:

define(`confDAEMON_OPTIONS',`a') V8.9 only
DAEMON_OPTIONS(`F=a')            V8.10 and above

10.9.3.1 Format of the default-auth-info file (V8.10 and V8.11)

For V8.10 and V8.11, the default-auth-info file is a plain-text file. Beginning with V8.12, that same information is in the access or authinfo database (see the next section).

The default-auth-info file contains a list of values, one value per line, in the following order:

First: The username that sendmail uses to check allowable permissions, such as authuser (should never be root).
Second: The username of the user allowed to set up the connection, such as authuser (should never be root).
Third: The clear-text password used to authorize the mail connection. This should be a password dedicated to this use, not a plain-text copy of any user's (especially root's) password.
Fourth: The administrative zone for authentication. In general, this should be your DNS domain. If no realm is specified (this item is missing), sendmail will substitute the value of the $j macro ($j).
Fifth: With V8.11 only, the preferred mechanism for connection authentication. This should match one of the mechanisms listed in the AuthMechanisms option (AuthMechanisms).

For example, one such default-auth-info file's contents might look like this:

user
user
foobar
our.official.domain
CRAM-MD5               V8.11 only

This file must live in a directory, all components of which are writable only by root. The file itself must be readable or writable only by root, and optionally readable by the user defined by the TrustedUser option (TrustedUser).

The location or name of this file can be changed using the confDEF_AUTH_INFO mc macro, which declares the DefaultAuthInfo option (DefaultAuthInfo):

define(`confDEF_AUTH_INFO', `/etc/security/default-auth-info')

Here, the location, but not the name, has been changed into what the administrator has set up as a more secure directory.

10.9.3.2 Authinfo and the access database (V8.12 and above)

Under V8.12, default client authentication information was moved out of the default-auth-info text file and into the access database. If you prefer a more secure database than the access database, you can declare an alternative with the authinfo feature (FEATURE(authinfo)). For example:

FEATURE(`authinfo')

Here, instead of looking up client authentication information in the access database, sendmail will instead look in the /etc/mail/authinfo database.

Whether you store default client authentication information in the access database or in the authinfo database, the syntax of entries is the same.

The database entries are created from a text file that has keys down the left column and matching values down the right. The two columns are separated by one or more tab or space characters. One line in such a source text file might look like this:

AuthInfo:address      "U:user"  "P=password" V8.12 and above

The left column of the database is composed of two parts. The first part is mandatory, the literal expression AuthInfo:. The second, configurable part is an IPv4 address, an IPv6 address, or a canonical host or domain name. For example:

AuthInfo:123.45.67.89                   an IPv4 address
Authinfo:IPv6:2002:c0a8:51d2::23f4      an IPv6 address
AuthInfo:host.domain.com                a hostname
AuthInfo:domain.com                     a domain name

When sendmail connects to another host, and that other host offers to authenticate, that connected-to host's IP address, hostname, and domain are looked up in the database.

If the IP address, host, or domain is not found, the connection is allowed, but sendmail will not attempt to authenticate it. Otherwise, the information in the matching right column is returned for sendmail to use.

The right column is composed of letter and value pairs, each pair quoted and separated from the others by space characters:

AuthInfo:address      "U:user"  "P=password"

Letters are separated from their value with a colon or an equal sign. A colon means that the value is literal text. An equal sign means that the value is Base64-encoded.

These letters and their meanings are shown in Table 10-2.

Table 10-2. Right column key letters for the default authinfo file
Letter	Description
`U`	The user (authorization) identifier
`I`	The authentication identifier
`P`	The password
`R`	The realm
`M`	The list of mechanisms (separated by spaces)

Either the U or the I, or both, must exist or authentication will fail. The P must always be present. The R and M are optional. All the letters are case-insensitivethat is, U and u are the same.

The U lists the name of the user that sendmail will use to check allowable permissions. Generally, this could be U:authuser (but should never be root).

The I lists the name of the user allowed to set up the connection. Generally this could be I:authuser (but should never be root).

The P value is the password. If the P is followed by a colon (as P:) the password is in plain text. If the P is followed by an equal sign (P=) the password is Base64-encoded. Generally, this should never be root's plain-text password.

The R lists the administrative realm for authentication. In general, this should be your DNS domain. If no realm is specified (this item is missing), sendmail will substitute the value of the $j macro ($j).

The M lists the preferred mechanism for connection authentication. Multiple mechanisms can be listed, one separated from another with a space:

"M:DIGEST-MD5 CRAM-MD5"

If the M item is missing, sendmail uses the list of mechanisms listed in the AuthMechanisms option (AuthMechanisms).

Missing required letters, unsupported letters, and letters that are missing values have warnings logged at a LogLevel of 9, or above, like this:

AUTH=client, relay=server_name [server_addr], authinfo failed

Here, the server_name is the value of the {server_name} sendmail macro (${server_name}). The server_addr is the value of the {server_addr} sendmail macro ${server_addr}). Both identify the connected-to host for which the connection failed.

All of this is implemented when you use the authinfo rule set. As of V8.12, there is no way to add your own rules to this rule set.

10.9.4 SASL and Rule Sets

The SMTP AUTH extension, enabled by SASL, allows client machines to relay mail through the authentication checking server. This mechanism is especially useful for roaming users whose laptops seldom have a constant IP number or hostname assigned.^[32] A special rule set called trust_auth, found inside the sendmail configuration file, does the actual checking. This rule set decides whether the client's authentication identifier (authid) is trusted to act as (proxy for) the requested authorization identity (userid). It allows authid to act for userid if both are recognized, and disallows that action if the authentication fails.

^[32] This mechanism requires that the laptop be running a mail reading/sending program that can use SMTP AUTH. Recent versions of Netscape and Microsoft's Explorer have this support, as do many other such programs. On laptops that run Unix (such as Linux or FreeBSD), you can, of course, run sendmail.

Another rule set, called Local_trust_auth, is available if you wish to supplement the basic test provided by trust_auth. The Local_trust_auth rule set can return the #error delivery agent to disallow proxying, or it can return OK to allow proxying.

Within the Local_trust_auth rule set you can use three new sendmail macros (in addition to the other normal sendmail macros). They are:

{auth_authen}: The client's authentication credentials as determined by the authentication process (see ${auth_authen})
{auth_author}: The authorization identity as set by issuance of the SMTP AUTH= parameter (see ${auth_author})
{auth_type}: The mechanism used for authentication (see ${auth_type})

10.9.5 Additional SASL Help

Setting up SASL can be simpler than we have shown here, or more difficult. The ultimate level of complexity depends on the degree of sophistication you wish to employ using this method of authentication. Sources for additional information that might be of help are:

cf/README: The file cf/README in the source distribution contains a section called SMTP AUTHENTICATION that describes how to use authentication in rule sets.
http://www.sendmail.org/tips/: This web site deals with items ranging from what we have discussed here, to compliant MUAs, problems with realms, and how to use SASL AUTH in support of roaming users.
http://asg.web.cmu.edu/sasl/: This web site, in addition to distributing the source for SASL, contains links to a number of documents that will help you install and configure the SASL library.