Recipe 7.2 Authenticating with AUTH

Problem

You have been asked to configure sendmail to use AUTH authentication when sending mail.

Solution

Make sure that the SASL libraries are installed and that sendmail is compiled with SASL support. See Recipe 1.5 and this chapter's Introduction if your system lacks either of these necessary components .

Add the host's authentication credentials to the access database using an AuthInfo : tag. Use the u : parameter to define the SASL authorization ID, the I : parameter to define the SASL authentication ID, the P : parameter to define the shared secret, the R : parameter to define the SASL realm, and the M : parameter to request an AUTH mechanism. Because the AuthInfo : entry contains a password written in clear text, it is important to make sure that the access database is only readable by root .

Create a sendmail configuration containing the access_db feature. Here is the required FEATURE macro:

 dnl Use the access database for AUTH credentials FEATURE(`access_db') 

Following the instructions in Recipe 1.8, rebuild the sendmail.cf file, copy the new sendmail.cf file to /etc/mail , and restart sendmail.

Discussion

To successfully authenticate, a host must be able to provide the receiving system with valid security credentials. These credentials are stored on the connecting host in the access database using the AuthInfo : tag. Here is an example of adding an AuthInfo : entry to the access database:

 #  cd /etc/mail  #  cat >> access   AuthInfo:chef.wrotethebook.com "U:crab" "I:crab" "P:It'sasecret!" "R:wrotethebook .com" "M:DIGEST-MD5  "  Ctrl-D  #  makemap hash access < access  #  chmod 600 access access.db  

The components of this access database entry are, as follows :

AuthInfo :

This is the access database tag. It identifies this entry as containing information used for authentication with the AUTH protocol.

chef.wrotethebook.com

The name of the remote system that will accept these credentials immediately follows the tag. The security credentials in this example are used by the local host to authenticate itself when it connects to chef.wrotethebook.com . The remote system can also be identified by IP address, although the hostname is more commonly used. If this field is empty (i.e., if no host is defined), the credentials are used for authentication when connecting to any system that advertises AUTH for which there is no specific AuthInfo : entry.

U:crab

The U : parameter defines the SASL authorization id, which is also called the user id. The authorization id is used to grant privileges on the remote system. If no value is provided for U :, sendmail uses the value assigned to I : as the default value for U :. See Introduction for more information about the SASL userid , which is also called the authorization id.

I:crab

The I : parameter defines the authentication id. This is the account name used during the authentication process. The authentication id is the name that is associated with the password in the sasldb file on the receiving system. If no value is provided for I :, sendmail uses the value assigned to U : as the default value for I :. Because U : and I : reference each other for default values, at least one of these values must be included in the AuthInfo : entry. See Introduction for more information about the SASL authid.

P:It'sasecret!

The P : parameter defines the password. In the example, the password is It'sasecret! . The password assigned to the P : parameter must match the password assigned to the authentication id in the sasldb file on the receiving host. This value is the shared-secret used for authentication.

R:wrotethebook.com

The R : parameter identifies the SASL realm. This value must match the SASL realm assigned to the authentication id in the sasldb file on the receiving host. Recipe Recipe 7.1 shows how the SASL realm is assigned to the authentication id on the receiving host using the -u argument of the saslpasswd command. If no value is provided for the R : parameter, sendmail uses the value returned by $j as the SASL realm. ( $j contains the fully qualified domain name of the local host.)

M:DIGEST-MD5

The M : parameter identifies the authentication technique that will be used. If no value is provided for M :, the AUTH protocol selects the "best" authentication technique that is available on both systems.

The authentication values defined by the AuthInfo : entry on the sending system must agree with those defined on the receiving system by saslpasswd . If any one of the values does not agree, authentication fails with the following error message:

 500 5.7.0 authentication failed 

Send mail to the remote host to test the AUTH credentials. Call sendmail with the -v option in order to watch the protocol interactions. Here is a sample test:

 $  sendmail -Am -v -t   To: [e-mail]   From: [e-mail]   Subject: Test   Please ignore  .  Ctrl-D  [e-mail]... Connecting to chef.wrotethebook.com. via esmtp... 220 chef.wrotethebook.com ESMTP Sendmail 8.12.9/8.12.9; Tue, 7 Jan 2003 13:25:58 - 0500 >>> EHLO crab.wrotethebook.com 250-chef.wrotethebook.com Hello IDENT:iE/rw7zeTz25z3Y8g3qLEbb5uGQ8RtyH@crab [192.168. 0.15], pleased to meet you 250-ENHANCEDSTATUSCODES 250-8BITMIME 250-SIZE 250-DSN 250-AUTH DIGEST-MD5 CRAM-MD5 250 HELP >>> AUTH DIGEST-MD5 = 334 bm9uY2U9ImFZcjB6VERCSWNBYUpFTVhNWGg2THQ5VllPW1kNS1zZXNz >>> dXNlcm5hbWU9ImNyYWlnIixyZWFsbT0id3JvdGV0aGVib29ryZmU3OTI3NzEzYTg5MGJjZQ== 334 cnNwYXV0aD0zYzMyMTc5YzhiMTQwYzQzNWJiNTgwOTZmOGZjYTQ4Mg== >>> 235 2.0.0 OK Authenticated >>> MAIL From:<[e-mail]> SIZE=97 AUTH=[e-mail] 250 2.1.0 <[e-mail]>... Sender ok >>> RCPT To:<[e-mail]> 250 2.1.5 <[e-mail]>... Recipient ok >>> DATA 354 Enter mail, end with "." on a line by itself >>> . 250 2.0.0 h07IPxt01997 Message accepted for delivery [e-mail]... Sent (h07IPxt01997 Message accepted for delivery) Closing connection to chef.wrotethebook.com. >>> QUIT 221 2.0.0 chef.wrotethebook.com closing connection 

In addition to the -v option, this test invokes sendmail with -t and -Am . -t tells sendmail to obtain the recipient address from any To:, CC:, and Bcc: lines in the message. (In the example, we specified the recipient with a To: line in the message.) The first five lines after the sendmail command is our test message, which is terminated by a Ctrl-D end-of-file mark. The -Am option tells sendmail to run as an MTA, using the sendmail.cf configuration. If this option is not specified, sendmail runs as a message submission program (MSP), uses the submit.cf configuration, and displays the interaction between the user's sendmail command and the local system. Because we want to watch the MTA interaction between our system and a remote system, we need to use the -Am option. ^[2]

^[2] Older versions of sendmail do not use submit.cf configuration and do not have, or need, the -Am commandline option.

Every line after the Ctrl-D is output from sendmail. Output lines that start with >>> are SMTP commands coming from the sending system. Lines that start with a numeric response code come from the receiving system.

The local system sends an EHLO command. In response, the remote system displays the list of extended commands that it supports. One of these tells the local host that the remote system supports AUTH and that it offers two authentication techniques, DIGEST-MD5 and CRAM-MD5. The local host sends an AUTH command requesting the DIGEST-MD5 technique to authenticate the connection. The endpoints exchange MD5 challenges and responses, and the remote system displays the message:

 235 2.0.0 OK Authenticated 

After that message, the mail delivery proceeds normally. The only effect that the recipient might notice is the addition of the word "authenticated" to the mail's Received : header, as shown below:

 Received: from crab.wrotethebook.com     (IDENT:iE/rw7zeTz25z3Y8g3qLEbb5uGQ8RtyH@crab [192.168.0.15])         (authenticated)         by chef.wrotethebook.com (8.12.9/8.12.9) with ESMTP id     h07IPxt01997         for <[e-mail]>; Tue, 7 Jan 2003 13:25:59 -0500 

The tests show that the AuthInfo : entry in the access database works and provides sendmail with the correct information to authenticate the local host to the remote host. However, versions of sendmail prior to sendmail 8.12 cannot store authentication information in the access database. On these older systems, AUTH security credentials are stored in a separate file. The file must be identified in the sendmail m4 configuration using the confDEF_AUTH_INFO define. For example, the following line added to the sendmail configuration tells sendmail that the SASL credentials are stored in a file named /etc/mail/default_auth_info :

 define(`confDEF_AUTH_INFO', `/etc/mail/default_auth_info') 

The confDEF_AUTH_INFO define is deprecated and should not be used with sendmail 8.12 or later versions of sendmail. In fact, it is ignored when added to a sendmail 8.12 configuration that also includes either the access_db feature or the authinfo feature. ^[3] Versions of sendmail before 8.12, however, do use the confDEF_AUTH_INFO file and do not support the AuthInfo : tag for the access database. If you have an older version of sendmail, upgrade to the latest version as described in Chapter 1. You should only use the deprecated file if you have an old version of sendmail that you cannot upgrade. A sample /etc/mail/default_auth_info file created for the confDEF_AUTH_INFO define shown above might contain:

^[3] It is possible to force sendmail 8.12 to use the file pointed to by confDEF_AUTH_INFO by editing the sendmail.cf file and deleting the authinfo ruleset. But this is not recommended.

 crab crab It'sasecret! wrotethebook.com DIGEST-MD5 

The first line defines the authorization identity, which is equivalent to the U : value in the access database. The second line defines the authentication identity, which is equivalent to the I : value. The third line contains the password, which is the P : value in the access database. The fourth line defines the SASL realm, which is the access database R : value. The fifth line specifies the authentication mechanism that should be used, which is equivalent to the M : value in the access database. (This fifth line is only useful with sendmail versions starting with 8.12; prior versions of sendmail will ignore it.) The file pointed to by confDEF_AUTH_INFO contains only one set of credentials that are used for authentication with all remote systems ”the access database permits you to define different credentials for each remote host. The access database is superior and should be used if at all possible.

This recipe configures AUTH for outbound connections. Recipe 7.1 configures inbound connections. Use saslpasswd as described in Recipe 7.1 to configure the passwords for systems that connect to your sendmail system. Use Authinfo : entries in the access database to configure the password your system uses when it connects to an external host. Combine these two recipes when your host both accepts inbound AUTH connections and makes outbound AUTH connections.

See Also

Recipe 7.3 provides an alternative way to configure AUTH credentials. Evaluate Recipe 7.3 before implementing this recipe. Recipe 1.5 covers compiling sendmail with SASL support. The access database is used and discussed in Chapter 3 and Chapter 6. The sendmail book covers the AuthInfo : tag in Section 10.9.3.2 and the confDEF_AUTH_INFO define in Section 24.9.27.