SMTP AUTH in sendmail 8.10-8.13

Last Update 2006-04-15

[Terminology] [Installation] [Configuration] [Operation] [Misc]

Introduction

sendmail 8.10 and later supports SMTP AUTH as defined in RFC 2554 which is based on SASL. This document describes the necessary steps for installation and operation of this feature with sendmail 8.10 and later versions.

(2000-03-23) If you use sendmail 8.10.0 as client for SMTP AUTH, please read the security warning.

Terminology

SASL defines two terms which are important in this context: authorization identifier and authentication identifer.
authorization identifier (userid)
The userid is the identifier an application uses to check whether operations are allowed (authorized).
authentication identifer (authid)
The authentication identifier is the identifier that is being used to authenticate the client. That is, the authentication credentials of the client contain the authentication identifier. This can be used for a proxy server to act as (proxy for) another user.

Installation

Cyrus SASL

Get, compile, and install cyrus-sasl. Read the docs (v1) (v2) which come with it (as well as README and INSTALL). If you want to use Cyrus SASL 2.x then you should use sendmail 8.13 (or later).

Make sure the libraries are installed in a location which sendmail uses on your system by default. The libraries must be "safe", i.e., they should be owned by root and only writable by that user. As usual, the whole path must be safe too.

Next, create a configuration file called Sendmail.conf if needed/wanted.

(SASLv1) Create a sasldb password file using saslpasswd if you use any mechanism (CRAM-MD5, DIGEST-MD5, PLAIN if pwcheck_method: sasldb is used in the .conf file) that requires it.
(SASLv2) Create a sasldb2 password file using saslpasswd2 if you use any mechanism (CRAM-MD5, DIGEST-MD5, PLAIN if pwcheck_method: auxprop is used in the .conf file) that requires it.
BTW: sendmail requires sasldb[2] to be owned by root or the trusted user and not be readable by anyone else since the file contains sensitive data (shared secrets). If there is a conflict with other applications that need to read it too, you can try a trick.

Compile sendmail

Compile sendmail with the correct options, i.e., add
APPENDDEF(`confENVDEF', `-DSASL')
APPENDDEF(`conf_sendmail_LIBS', `-lsasl')
for Cyrus SASLv1 or
APPENDDEF(`confENVDEF', `-DSASL=2')
APPENDDEF(`conf_sendmail_LIBS', `-lsasl2')
for Cyrus SASLv2 to your site.config.m4 (or OS specific) file in devtools/Site. You maybe need to set:
APPENDDEF(`confLIBDIRS', `-L/PATH/TO/SASL/lib')
APPENDDEF(`confINCDIRS', `-I/PATH/TO/SASL/include')
(obviously you have to replace /PATH/TO/SASL/ with the path on your system) if you haven't installed sasl in a location where the Build tool looks for include and library files. However, this may cause problems during runtime, since the sasl library is dynamically loaded, and most OS don't load libraries from "unknown" locations, esp. since sendmail is usually setuid root (and hence LD_LIBRARY_PATH is ignored to avoid security problems).

If you have a SASL library version before 1.5.10, then you should upgrade. Otherwise you have to set the value for SASL to the version number of the SASL library you use, using a simple conversion: a.b.c -> c + b*100 + a*10000, e.g. 1.5.5 -> 10505.
APPENDDEF(`confENVDEF', `-DSASL=10505')

Initial test

Run
sendmail -d0.1 -bv root | grep SASL
and make sure SASL appears in the output. Otherwise go back to compiling sendmail and make sure your site.config.m4 is really used.

Start the sendmail daemon, connect to it and see whether it comes up with

250-AUTH
in the EHLO response:
% telnet localhost 25
Trying 127.0.0.1...
Connected to localhost
Escape character is '^]'.
220 local.sendmail.ORG ESMTP Sendmail 8.10.0/8.10.0; Thu, 9 Sep 1999 10:48:44 -0700 (PDT)
ehlo localhost
250-local.sendmail.ORG Hello localhost [127.0.0.1], pleased to meet you
250-ENHANCEDSTATUSCODES
250-DSN
250-AUTH DIGEST-MD5 CRAM-MD5
250 HELP
quit
If it doesn't, check your logfile whether any security problems are listed (unsafe files). If this doesn't reveal any problems, increase the LogLevel to 13 and try again.

Examples of problems in the logfile:

Note: this fails in Cyrus-SASL 2.1.21 because it ignores environment variables if the application is set-user-ID or set-group-ID.

Some tips if authentication still fails:

Configuration

There are some options for the .cf (.mc) file which you may want to change from their default values:

AuthMechanisms (confAUTH_MECHANISMS)
defines a list of mechanisms which are offered at most for authentication. This list is intersected with the list of available (i.e., installed) mechanisms, and the result of the intersection is listed in the AUTH keyword value for the EHLO response.
default: GSSAPI KERBEROS_V4 DIGEST-MD5 CRAM-MD5
C{TrustAuthMech} (TRUST_AUTH_MECH())
defines a list of mechanisms which are used to allow relaying.
DefaultAuthInfo (confDEF_AUTH_INFO)
specifies a file in which the authorization identity, the authentication identity, the secret, and the realm to be used for authentication are stored. This file must be in a safe directory and unreadable by everyone except root (or TrustedUser). It is used when sendmail acts as a client to authenticate itself to a server. Example:
admin
admin
MySecretPassword
example.domain
Notes: all data is case sensitive (usually) and the entire line is used in each case (including any white space!).
recommended filename: /etc/mail/default-auth-info

Security Warning: sendmail 8.10.0 uses this data when sending e-mail and tries to authenticate against every server that offers SMTP AUTH. This may reveal the secret if the other side offers a plaintext authentication mechanism. Make sure the secret is not a real password used for an account somewhere. sendmail 8.10.1 minimizes this problem.

sendmail 8.12 (and later) offers a significantly better way to specify the client authentication information. See cf/README for details, look in the section SMTP AUTHENTICATION. Notice: the default 8.12 configuration file causes the option DefaultAuthInfo to fail since the ruleset authinfo is in the .cf file. If you really want to use DefaultAuthInfo (it is deprecated) then you have to remove the ruleset.

DaemonPortOptions (DAEMON_OPTIONS())
has now suboptions (called modifiers), one of which is `a'. This tells the daemon to require authentication for all connections to it.
Example for a .mc file (listing only the part relevant for SMTP AUTH):
TRUST_AUTH_MECH(`GSSAPI DIGEST-MD5')dnl
define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5')dnl
define(`confDEF_AUTH_INFO', `/etc/mail/auth/auth-info')dnl
FEATURE(`no_default_msa')dnl turn off default entry for MSA
DAEMON_OPTIONS(`Port=587, Name=MSA, M=E')dnl

Operation

SMTP AUTH allows relaying for senders who have successfully authenticated themselves. Per default, relaying is allowed for any user who authenticated via a trusted mechanism, i.e., one that is defined via
TRUST_AUTH_MECH(`list of mechanisms')
This is useful for roaming users and can replace POP-before-SMTP hacks if the MUA supports SMTP AUTH.

The ruleset trust_auth is used to decide whether the client's authentication identifier (authid) is trusted to act as (proxy for) the requested authorization identity (userid). The provided rules allow authid to act for userid if both are identical and they disallow it if the authentication failed. The ruleset Local_trust_auth can be used to provide further tests. As usual, it can either return the error mailer ($# error) to disallow proxying or $# OK to allow proxying.

New macros for SMTP AUTH are {auth_authen}, {auth_author}, and {auth_type}, which hold the client's authentication credentials (authid), the authorization identity (userid) (i.e., the AUTH= parameter of the MAIL command, if supplied), and the mechanism used for authentication.

Require AUTH

You can require the use of SMTP AUTH for relaying by simply turning off other means of relaying for incoming mail, e.g., the access map or class R. That is, if you have my.domain in /etc/mail/relay-domains or
my.domain	RELAY
in the access map, then remove the entry from class R (/etc/mail/relay-domains) and use
To:my.domain	RELAY
in the access map.

Requiring SMTP AUTH for all mails is in general a bad idea, because then you cannot receive mails from other users (since the cannot authenticate). So you must do this only on a server that is solely intended for your own users to send mail, not for a publically advertised (via MX records) server.

Using sendmail as a client with AUTH

(This section has been written by Benji Fisher. Thanks!)

If you are using sendmail only to transfer e-mail from your local computer to a mail server that requires SMTP AUTH, follow these instructions. They assume that sendmail 8.12 or later, and other software, is already installed on your computer. You should probably be logged in as root to perform these steps.

  1. Change directory to where your sendmail configuration files (sendmail.mc and sendmail.cf) are located, usually /etc/mail/.
  2. Create a safe subdirectory (suggested name auth/):
      # mkdir auth
      # chmod 700 auth
      
  3. Create a file with your authentication information (suggested name auth/client-info):
      AuthInfo:your.isp.net "U:root" "I:user" "P:password"
      
    filling in your ISP's mail server, your user name, and your password. (Note: Earthlink, and perhaps other ISP's, requires your full e-mail address as a user name.)
  4. Generate the authentication database and make both files readable only by root:
      # cd auth
      # makemap hash client-info < client-info
      # chmod 600 client-info*
      # cd ..
      
  5. Add the following lines to your sendmail.mc file, filling in your ISP's mail server:
      define(`SMART_HOST',`your.isp.net')dnl
      define(`confAUTH_MECHANISMS', `EXTERNAL GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN PLAIN')dnl
      FEATURE(`authinfo',`hash /etc/mail/auth/client-info')dnl
      
  6. Generate sendmail.cf:
      # m4 sendmail.mc > sendmail.cf
      
  7. Restart the sendmail daemon, e.g., (this depends on your OS):
      # kill -HUP `cat /var/run/sendmail.pid`
      
Note: if FEATURE(`authinfo') is used, then the hostname in the map entry must match exactly the hostname of the ISP mailserver as explained in cf/README: Note: searches for domain parts or IP nets are only performed if the access map is used; if the authinfo feature is used then only up to three lookups are performed (two exact matches, one default).

Misc

MUA?

Now that sendmail provides SMTP AUTHentication, you probably want a MUA that uses it. However, currently there are only a few clients (e.g., MUA) which support SASL. Many MUAs on Unix call sendmail directly, so for roaming users it is sufficient if their sendmail can authenticate itself against the mailserver.

Plain text authentication

Please don't use PLAIN or LOGIN as authentication mechanisms, unless a strong encryption layer, e.g., via STARTTLS or an external SSL tunnel, is active. If you use 8.12 (or later), then you can set p in AuthOptions (see Installation and Operations Guide). Quoting RFC 2595
6. PLAIN SASL mechanism

   Clear-text passwords are simple, interoperate with almost all
   existing operating system authentication databases, and are useful
   for a smooth transition to a more secure password-based
   authentication mechanism.  The drawback is that they are unacceptable
   for use over an unencrypted network connection.
If you use it anyway, and you use Netscape as MUA, then in some cases you may want to turn it off; add
user_pref("mail.auth_login", false);
to Netscape's preferences file.

Patches

If you run 8.12.x (x >= 4) and you use sendmail as client to authenticate against a server using LOGIN, then you need also this patch.

Cyrus SASL 2.1.13 - 2.1.17 broke EXTERNAL, 2.1.18 will have a fix (maybe check the CVS server for Cyrus SASL if you need the patch before 2.1.18 is released).

More Possible Problems

Realms can cause some problems because they are not standardized for all mechanisms.

Interoperability Problems

Mercury 1.48 doesn't follow RFC 2554 and sends "330" instead of "334" as continuation code. This is fixed in Mercury/32 according to Pegasus tech support.

Security Layer

SASL means Simple Authentication and Security Layer. sendmail 8.11 supports the security layer, while sendmail 8.10 only uses the authentication part.

Warning: If you have a Cyrus SASL version older than 1.5.15, make sure you compile the plugins without any encryption, e.g., DIGEST-MD5 without DES etc. sendmail 8.10 does not support encryption within SASL. If the SASL plugins negotiate a security layer, sendmail 8.10 won't be able to talk to the other side if that switches to the encrypted channel. This is a problem with Cyrus SASL which doesn't obey the maximum security settings of sendmail. You may want to apply a patch to plugins/digestmd5.c (1.5.13).

Other WWW Pages about SMTP AUTH

Some people complained that my explanations are too hard to understand for beginners. Maybe this link from Jon Fullmer helps them? Otherwise use a search engine to find more explanations or let me know how to enhance this WWW page.

Credits

The implementation of SMTP AUTH in sendmail 8.10 is based on a patch written by Tim Martin of CMU. He and Larry Greenfield also provided valuable feedback during further development and integrated our patches or implemented features we requested.

Ken Murchison gave us a patch to support Cyrus-SASL v2 (inofficially available since 8.12.4).


[(links)] [Hints] [Avoiding UBE] [cf/README] [New]
Copyright © Claus Aßmann Please send comments to: <ca at sendmail.org>
Disclaimer: the information provided may be inaccurate or outdated or incomplete. Please contact me if you find an error.