Table of Contents for

sendmail, 4th Edition

The last step when tuning SASL is to create a file called Sendmail.conf in the /usr/lib/sasl2/ directory (or for V1, the /usr/lib/sasl/ directory). At a minimum, one line should appear in that file and that line should indicate your preferred password verification method:

pwcheck_method: method

Here, method is selected from the methods listed in Table 5-1.

If you chose a method that is unsupported, sendmail will log the following warning and disallow the authentication:

Dec 14 09:49:31 your.host.domain sendmail[6985]: unknown password verifier

In the next section, we show how to run sendmail in a manner that allows you to determine whether it supports the method you’ve chosen.

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:

# 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.14.1/8.14.1; Fri, 14 Dec 2007 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. If you ran as root and the test still failed, examine your syslog file. 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 saslpasswd2(8) or saslpasswd(8) program as described in Get and Install the SASL Library on page 184.

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.^[90] Another might be that the directory pointed to by the symbolic link /usr/lib/sasl2, or /usr/lib/sasl, is unsafe. Revise any offending permissions and rerun the test until it succeeds.

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 logfile for additional error information.

To debug authentication before using it to send and receive real email, we recommend you first set up an authenticating sendmail test daemon that listens on a non-standard port and is bound to the loopback interface. That way, you can test without interfering with real email on your system. To begin, set up the following minimal mc configuration file in the cf/cf directory under the sendmail source and call it test.mc:

OSTYPE(linux)
FEATURE(no_default_msa)
DAEMON_OPTIONS(``A=localhost, P=26, N=authsmtp, M=a'')
MAILER(smtp)

Here, you should replace linux with the type of your operating system (Relays on page 602). The second line (the no_default_msa feature; FEATURE(no_default_msa) on page 635) disables all listening daemons. The second from last line (the DAEMON_OPTIONS; DaemonPortOptions on page 993) declares a single daemon with the name authsmtp that will bind to localhost (the loopback interface) and will listen on the nonstandard port numbered 26.^[91] The M=a tells this server to always require connection authentication. The last line (the MAILER; MAILER( ) m4 macro on page 590) allows mail to be relayed using smtp over the Internet.

Save this text to a file named test.mc, and then run the following command in the cf/cf directory to create a cf file from that mc file:

# make test.cf
rm -f test.cf
m4 ../m4/cf.m4 test.mc > test.cf || ( rm -f test.cf && exit 1 )
echo "### test.mc ###" >>test.cf
sed -e 's/^/# /' test.mc >>test.cf
chmod 444 test.cf

You may then perform your tests by running the following command in one window while sending email in another:

# ../../obj.*/sendmail/sendmail -Ctest.cf -X/tmp/auth.log -bD

Here, the -X command-line switch (Log Transactions with -X on page 512) causes a copy of any SMTP transactions to be saved in the file /tmp/auth.log. The -bD runs sendmail as a daemon but leaves it connected to your keyboard so that you can easily stop and restart it.

After running these tests, you should test with an email client that can use AUTH for sender authentication. If you use Thunderbird, for example, select Preferences, and then select Outgoing Server. Change the port to the port you specified earlier (the P=26 for port 26). Also put a check in the box that says “Use name and password.” Then enter the appropriate username for testing. If a realm is required, this may have to be in user@your.domain form.

Now, send an email message. After it is sent or fails, exit sendmail and look at the /tmp/auth.log file you created. If the test has failed, the contents of that file may look, in part, like this:

13885 >>> 250-AUTH GSSAPI DIGEST-MD5 CRAM-MD5
13885 >>> 250-DELIVERBY
13885 >>> 250 HELP
13885 <<< AUTH CRAM-MD5
13885 >>> 334 PW4gPDIyMDg3MzU4ODAuMTI1NTgxMzFAeW91ci5ob3N0LmRvbWFpbj4K
13885 <<< dGVzdGVyQGxvY2FsaG9zdCAzMDRhNDAwMTBmYWE5MjhiOWYzZTllZmIyOTJkODYxMQ==
13885 >>> 535 5.7.0 authentication failed
13885 <<< [EOF]
13885 >>> 421 4.4.1 your.host.domain Lost input channel from localhost [127.0.0.1]

Here, CRAM-MD5 was the only authentication mechanism offered by sendmail and so was the only mechanism used by Thunderbird, and the test failed. To fix this, we will try to add the PLAIN authentication mechanism to the test.mc file (we cover confAUTH_MECHANISMS in the next section), by adding the following line to the test.mc file and rebuilding the cf file:

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

After you build a new test.cf file, run the same test again. This time, authentication succeeds and the /tmp/auth.log file contains, in part, lines like the following:

14062 >>> 250-AUTH CRAM-MD5 PLAIN
14062 >>> 250-DELIVERBY
14062 >>> 250 HELP
14062 <<< AUTH CRAM-MD5
14062 >>> 334 PW4gPDIyMDg3MzU4ODAuMTI1NTgxMzFAeW91ci5ob3N0LmRvbWFpbj4K
14062 <<< dGVzdGVyQGxvY2FsaG9zdCAzMDRhNDAwMTBmYWE5MjhiOWYzZTllZmIyOTJkODYxMQ==
14062 >>> 535 5.7.0 authentication failed
14062 <<< AUTH PLAIN dGVzdHVzZXJcMFRlc3RQYXNzd2QK
14062 >>> 235 2.0.0 OK Authenticated

Here, CRAM-MD5 fails as before, but now Thunderbird tries the PLAIN authentication mechanism and that mechanism succeeds with “235 2.0.0 OK Authenticated”.

Note that you should probably not use PLAIN if you are expecting authentication over the Internet, because it allows usernames and passwords to pass in the clear.^[92] To see for yourself, use mimencode(1) or a similar program to decode the expression following AUTH PLAIN earlier. You will see the following, when you decode it:

testuser\0TestPasswd

If the -X file does not give you enough information to solve your problem, try increasing the log level to 13 as we described earlier, and examine your logs for additional information:

# ../../obj.*/sendmail/sendmail -Ctest.cf -X/tmp/auth.log -bD -OLogLevel=13

Your server can require AUTH for all connections only if it is not connected to the Internet for inbound email. For example, if your server functions as an outbound-only relay for machines behind a firewall, it might be appropriate to require AUTH for all connections.

For a normal server, one which functions as both an outbound relay and an inbound mail server, AUTH should be required only to enable relaying.

In general, the outbound role is handled by requiring AUTH upon connection, and the inbound role is based on the envelope sender. The two can, however, be combined, as when an AUTH mechanism (like CRAM-MD5) must be valid before the envelope sender may be checked.

The AuthMechanisms option (AuthMechanisms on page 975) 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')

This only defines the mechanisms that will be required if AUTH is required for inbound connections. Whether or not connections must be authenticated is determined by the setting of the DaemonOptions option (discussed shortly).

The class $={TrustAuthMech} contains a list of authentication mechanisms that allow relaying. It must contain a subset, or a matching set,^[93] 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 that authentication (if successful) will provide an authorization to relay.

Prior to V8.13 sendmail, if authentication required a realm, the value of the $j macro (the canonical name of the local host) was used as the realm. Beginning with V8.13, the AuthRealm option (AuthRealm on page 978) can be invoked to define a realm to use in place of the value of the $j macro:

define(`confAUTH_REALM', `our.domain')

You may wish to define a different realm if your server has multiple network interfaces, and sendmail chooses as the value of $j the canonical name associated with the wrong interface. Or you may wish to define a different realm if you want to use your own domain name, rather than the host’s canonical name. Whatever your need, this confAUTH_REALM m4 macro allows you to define a realm of your choice.

The AuthOptions option (AuthOptions on page 977) is used to specify how authentication should be handled by your server (or client; see AUTH Running As a Client on page 195). For example, if you wish to disallow any mechanism that permits anonymous logins, you would specify the y setting for this option:

define(`confAUTH_OPTIONS', `y')

The complete list of characters that determine AUTH usage and policy are listed in Table 5-2. Each character sets a single tuning parameter. If more than one character is listed, each character must be separated from the next by either a comma or a space:

define(`confAUTH_OPTIONS', `A y')
define(`confAUTH_OPTIONS', ``A,y'')

Note that if you use a comma, the entire expression must be doubly quoted.

If you are also using STARTTLS (STARTTLS on page 202), you may want to also define the AuthMaxBits option (AuthMaxBits on page 975) to suppress encryption within encryption when the CRAM-MD5 mechanism is used.

The M=a for the DaemonPortOptions option (DaemonPortOptions=Modify= on page 996) determines whether the connection must be authenticated for all connections, or whether only a sender that tries to relay must be authenticated. You saw examples of M=a (earlier) that require connection authentication for all inbound connections to the server. To turn that off and only require the sender to authenticate, use M=A. For example:

DAEMON_OPTIONS(``..., M=A'')

With this M=A setting, you can screen individual users for relaying permission using rule sets, as we demonstrate next. If your server receives mail from the Internet, you must use M=A instead of M=a.

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) on page 616). For example:

FEATURE(`authinfo')

Here, instead of looking up client authentication information in the access database, sendmail will 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.^[95] One line in such a source text file might look like this:

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

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 5-3.

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-insensitive—that 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 it 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 it 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 on page 830) unless the AuthRealm option (AuthRealm on page 978) is used to define a realm to use in place of the value of the $j macro.

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 mechanisms listed in the AuthMechanisms option (AuthMechanisms on page 975).

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} on page 845). The server_addr is the value of the ${server_addr} sendmail macro ${server_addr} on page 845). 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.14, there is no way to add your own rules to this rule set.

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 previous section).

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

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 on page 1112).

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

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.

Sun Microsystems provides an equivalent to /dev/urandom, called /dev/random, as part of its SUNWski package for Solaris. If it is not already installed on your system, you can install it from a variety of sources. Look for it on your Solaris Server Intranet Extension CD.

For Solaris 2.6, look for patch number 106754, 106755, or 106756, which contains the SUNWski package.

EGD is a persistent daemon that provides excellent pseudorandom numbers via a Unix domain socket. It is available as perl(1) source from http://egd.sourceforge.net/.

If you choose to download and install this daemon, you can advise sendmail of that fact by defining the RandFile option (RandFile on page 1076) in your mc configuration file:

define(`confRAND_FILE', `egd:/etc/entropy')

Here, a decision was made to run the EGD daemon at the system level, and to have it create its socket as /etc/entropy.^[98] If you place that socket in a different location, you should replace /etc/entropy in the confRAND_FILE line (as discussed earlier) with the new location. The egd: prefix is required and constant.

Note that to include support inside sendmail for use with this daemon, you must build sendmail with the EGD compile-time macro defined (EGD on page 111):

APPENDDEF(`confENVDEF', `-DEGD')   ← in your Build m4 file

PRNGD is an EGD-compatible daemon available from http://prngd.sourceforge.net/.

You download and install it, and then use it in the same manner described in the preceding section for EGD.

It is possible to use a file created by you that contains random numbers. To do this, first define the location of that file with sendmail’s RandFile option (RandFile on page 1076). Such a declaration might look like this:

define(`confRAND_FILE', `file:/var/run/randfile')

Note that the file: prefix is literal and must be present. The file, here named /var/run/randfile, contains at least 128 bytes of random data.

For such a file to work, you need to update its contents more often than once every 10 minutes. If you update it less often, sendmail might refuse to use it upon startup (as a daemon or simply to send an email message). That is, the modification time of the file must always be within 10 minutes of any envocation of sendmail.

The first step to create your own certificates is to decide where on the filesystem they may safely be stored. For email purposes, we suggest /etc/mail/CA or a similar path that is writable only by root, and where the private subdirectory under it is readable only by root. We use /etc/mail/CA in the examples to follow:

# cd /etc/mail
# mkdir CA CA/certs CA/crl CA/newcerts CA/private
# chmod -R 700 CA/private
# cd CA

For the rest of this discussion, we presume you will be working inside the CA directory; hence the cd CA in the preceding code. We also presume that the openssl(1) program is in your path. If it isn’t, you may need to prefix openssl in the examples that follow with its full path. For example:

# /usr/local/ssl/bin/openssl .....

Alternatively, you can temporarily modify root’s path:

# PATH=/usr/local/ssl/bin:$PATH; export PATH

Next, you generate your certificate authority (your CA). You need to do this only once. We use the req function for OpenSSL (http://www.openssl.org/docs/apps/req.html) to manage and create certificates:

# echo `01' > serial
# cp /dev/null index.txt
# openssl req -nodes -new -x509 -keyout private/cakey.pem -out cacert.pem

The -nodes prevents the resulting certificate from being encrypted. This is necessary for use with sendmail because sendmail must be able to start unattended without the need for an operator to type in a password each time.

The last command is a two-step process combined into one. The -keyout private/cakey.pem command creates an encryption key that will be used to sign the certificate:

Generating a 1024 bit RSA private key
.........++++++
.........................++++++
writing new private key to `private/cakey.pem'

This step can be slow on older systems, especially those that lack a good random number generator (one without sufficient entropy). You may, for example, be required to rapidly type characters to help generate random events.

This key must be protected, so we place it in the private subdirectory. If anyone were to access it, that person would be able to decrypt anything encrypted with it.

The second step creates the actual certificate. Because this is a standard X.509 certificate, you will be prompted to fill in some X.509 information.^[100] We suggest the following answers for illustrative purposes only. Naturally, you need to enter information specific to your situation and your site:

You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:California
Locality Name (eg, city) []:Emeryville
Organization Name (eg, company) [Internet Widgits Pty Ltd]:your domain
Organizational Unit Name (eg, section) []:.
Common Name (eg, YOUR name) []:mail.your.domain
Email Address []:you@your.domain

Note that the “Common Name” must exactly match the hostname of the system on which the certificate will be used. If it differs, some clients may complain about a certificate-to-hostname mismatch.

The next step is to create a certificate for use with sendmail. You will have to perform this step whenever a new cert is required. The umask(1) in the following code ensures that every file created for the rest of this session will be writable only by root.

# umask 0066
# openssl req -nodes -new -x509 -keyout key.pem -out newcert.pem

The preceding command creates a certificate for use with sendmail. It is unsigned and still needs to be signed by the CA, which we will do next. Like the previous step, this creates a key (which may be a long process) and then prompts you for X.509 information. Fill in that information as you did earlier.

The last step is to sign the new sendmail certificate (called newcert.pem), which requires two commands. The first command generates a certificate request:

# openssl x509 -x509toreq -in newcert.pem -signkey key.pem -out csr.pem
Getting request Private Key
Generating certificate request

The second command uses the CA cert key in private/cakey.pem to sign the newcert.pem certificate. The request for the signature is in the csr.pem file we created earlier (where csr stands for Certificate Signing Request):

# openssl ca -policy policy_anything -out cert.pem -infiles csr.pem
Check that the request matches the signature
Signature ok
Certificate Details:
        Serial Number: 1 (0x1)
        Validity
            Not Before: Feb  2 18:05:01 2007 GMT
            Not After : Feb  2 18:05:01 2008 GMT
        Subject:
            countryName               = US
            stateOrProvinceName       = California
            localityName              = Emeryville
            organizationName          = your domain
            commonName                = mail.your.domain
            emailAddress              = you@your.domain
        X509v3 extensions:
            X509v3 Basic Constraints:
                CA:FALSE
            Netscape Comment:
                OpenSSL Generated Certificate
            X509v3 Subject Key Identifier:
                44:76:FB:B4:54:F2:2E:FC:F6:35:3B:11:CD:FB:16:12:90:71:7B:B3
            X509v3 Authority Key Identifier:
                keyid:B7:A1:33:10:67:6E:15:E0:4D:BA:C4:B4:77:93:BA:5E:55:44:15:6C
Certificate is to be certified until Dec 15 18:05:01 2008 GMT (365 days)
Sign the certificate? [y/n]:

Here you are prompted to say yes or no to signing the certificate. This gives you the opportunity to review the information displayed. Certificates are sensitive to all sorts of minor errors and need to be handled carefully. You should select y only if all looks correct:

Sign the certificate? [y/n]:y

Committing means adding this particular certificate to your collection of certificates. The next question is whether you wish to commit the certificate:

1 out of 1 certificate requests certified, commit? [y/n]

We recommend yes. It will be added to your index.txt file.

1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
Data Base Updated

If the above command fails, you may see the following error:

Error opening CA certificate ./demoCA/cacert.pem
2561:error:02001002:system library:fopen:No such file or directory:bss_file.c:352:
fopen('.demoCA/cacert.pem','r')
2561:error:20074002:BIO routines:FILE_CTRL:system lib:bss_file.c:354:
unable to load certificate

This just means that you have not yet set up your openssl(8) configuration defaults. If so, you can create the following symbolic link as a shortcut just to verify that the prior command will actually work:

# ln -s ../CA demoCA

If all went well, you “clean up.” The csr.pem file may be removed because it was only a scratch file needed for signing. The newcert.pem may be removed because it is the unsigned cert. The file cert.pem contains the CA signed cert.

To view the certificate you created (or any certificate, for that matter) simply use a command like the following:

# openssl x509 -noout -fingerprint -text -in cert.pem

We don’t show the output of this command because it can run to multiple pages. You can redirect this output into a file, if you wish, and share that file on a web site. Its output is your CA signed public key in text format.

Lastly, recall that sendmail can run as either a client or a server. Whether you use the same certificate for both roles is a matter of policy. But if you wish to offer TLS for both roles using separate certs for each, you should now rename the cert.pem and key.pem files for the server’s use and create (using the procedure we just outlined) another CA signed certificate for use with the client:

# mv cert.pem server.cert.pem
# mv key.pem server.key.pem
... create another CA signed cert here
# mv cert.pem client.cert.pem
# mv key.pem client.key.pem

Note that the preceding code generates separate certs for client and server. Note also that we will use the preceding filenames in the discussions to follow.

Beginning with V8.12 sendmail, OpenSSL version 0.9.7 and later support the ability to screen certificates against a revocation list. In the preceding section, you created certificates that possessed a default life of one year. But what happens if you want to cancel a certificate and replace it with another? For housekeeping purposes, you can add the canceled certificate to a list of canceled certificates called a “revocation list.”

For use with sendmail, you may create an empty revocation file with the following commands:

# echo "01" > crlnumber
# openssl ca -gencrl -out crl/crl.pem

Later, when you need to add certificates to this file, you may. But in the meantime, an empty file works just fine for sendmail’s needs. Visit http://www.openssl.org/docs/apps/crl.html for additional guidance.

To view your empty revocation list, you may use the following command:

# openssl crl -in crl/crl.pem -noout -text

There can be much more to the creation and signing of certificates than we show here. The following lists a few resources that provide additional guidance to certificate creation and management:

In the rule set Local_Relay_Auth, the STARTTLS-related sendmail macro ${verify} (which contains the result of connection verification) is compared to the literal value OK. If it is not OK, the other relaying checks are performed.

If ${verify} is OK, the value in the sendmail macro ${cert_issuer} (${cert_issuer} on page 809) is prefixed with CERTISSUER:, and the result is looked up in the access database. That macro contains as its value the distinguished name of the authority that signed the presented certificate. The value undergoes special translation before the lookup. Specifically, all nonprinting characters, the space and tab characters, and the special characters:

< > ( ) " +

are replaced with the hexadecimal value of the character prefixed with a plus sign. For example, Sendmail CA becomes Sendmail+20CA.

Therefore, if the issuer has the following distinguished name:

/C=US/ST=California/L=Berkeley/O=Sendmail.org/CN=Sendmail CA/

that value undergoes special translation, and is prefixed with the special prefix CERTISSUER: just before the lookup. So the following is looked up:

CERTISSUER:/C=US/ST=California/L=Berkeley/O=Sendmail.org/CN=Sendmail+20CA/

If that prefix and distinguished name are found in the database, and if the value returned is the keyword RELAY, relaying is allowed. If the value returned is the keyword SUBJECT instead of RELAY, the value of the sendmail macro ${cert_subject} (${cert_subject} on page 809) is looked up in the access database. That macro contains as its value the distinguished name of the connecting site. That value also undergoes translation, and is prefixed with the special prefix CERTSUBJECT: just before the lookup. For example, if the distinguished name of the certificate for the connecting site is:

/C=US/ST=California/L=Berkeley/O=Sendmail.org/CN=Eric Allman/

the following is looked up:

CERTSUBJECT:/C=US/ST=California/L=Berkeley/O=Sendmail.org/CN=Eric+20Allman/

If the prefixed macro’s value is found, and if the value returned is the keyword RELAY, relaying is allowed.

The tls_server rule set is called after the local sendmail issued (or should have issued) the STARTTLS SMTP command. This rule set handles outbound connections.

The tls_client rule set is called at two possible points: just after the connecting host’s STARTTLS SMTP command is offered; and from the check_mail rule set (which is called just after the connecting host issues the MAIL From: command). This tls_client rule set handles inbound connections.

Both rule sets are given the value of the ${verify} sendmail macro in their workspaces. The tls_client rule set is given that value, followed by a $| operator, and a literal string that is MAIL when tls_client is called from the check_mail rule set, or STARTTLS otherwise.

If the access database is not used, the connection is allowed in all cases, both inbound and outbound, unless the value in ${verify} is SOFTWARE, in which case the connection is not allowed.

If the access database is used, the tls_server rule set looks up the hostname of the destination host in the access database using the TLS_Srv: prefix. For example, if the local sendmail connected to the server insecure.host.domain, and if the negotiation for the TLS connection was good, the following lookup is performed:

TLS_Srv:insecure.host.domain

The tls_client rule set looks up the hostname of the inbound connecting host in the access database using the TLS_Clt: prefix. For example, if the local sendmail accepts a connection from ssl.host.domain, and if the negotiation for TLS connection was good, the following lookup is performed:

TLS_Clt:ssl.host.domain

For both rule sets, if the host or domain is not found, the host.domain and then the domain are looked up, and if neither is found, a bare prefix is looked up to determine the default behavior:

TLS_Clt:                           VERIFY
TLS_Srv:                           VERIFY

Here, the default for inbound and outbound connections is to require that they all be verified.

The access database righthand-side string VERIFY means that the value in the ${verify} macro must be OK.

In addition to the VERIFY value keyword, a number of bits (key length) can also be specified as:

VERIFY:bits

In addition to requiring that the certificate be verified, the number of bits in the ${cipher_bits} sendmail macro must be at least as wide as the number of bits specified in bits.

If the number of bits is the only item of concern, and if certificate verification is not of concern, the VERIFY in VERIFY:bits can be changed into ENCR:

ENCR:bits

Here, no certificate verification is required, but the number of bits in the ${cipher_bits} sendmail macro must be at least as wide as the number of bits specified in bits.

If the certificate is verified, and/or the number of bits is sufficient, the connection is allowed. Otherwise, it is rejected. When rejected, the rejection is temporary by default. You can prefix the VERIFY or ENCR with a TEMP+ to make a particular failure temporary, or with a PERM+ to make it permanent:

TEMP+VERIFY      ← temporary failure
PERM+ENCR:bits   ← permanent failure

You can also define the TLS_PERM_ERR macro in your mc configuration file to redefine the default to be a permanent failure:

define(`TLS_PERM_ERR')

If you wish to add your own rule to the tls_client or tls_server rule set, you can do so with an appropriate mc configuration command:

LOCAL_TLS_CLIENT ← additional rules for
tls_client here
LOCAL_TLS_SERVER ← additional rules for
tls_server here

Your rules, if any, will be called first. That is, for example, if you add rules to tls_client, those rules will be called before those that were already in the tls_client rule set. You do not need to restore the workspace at the end of your rules, however, because that restoration is taken care of for you.

In the preceding section, you learned that the tls_server rule set could be used to require that all mail to a particular site always be encrypted. For example, an access database entry such as the following does just that for the hostA.domain site:

TLS_Srv:hostA.domain   ENCR:128

However, because of MX records, mail might not always be sent to the hostA.domain’s mail server. Consider these two MX records:

hostA.domain.  IN MX 10        mail.hostA.domain.
hostA.domain.  IN MX 50        mail.someother.domain.

When the server mail.hostA.domain is down or heavily loaded, your local sendmail will likely connect to the backup MX site mail.someother.domain. When this happens, the requirement that all mail be encrypted (as set in the access database) will not be honored. Because you have no way of knowing ahead of time what host will serve as an MX backup, you probably won’t have that backup host listed in your access database:

TLS_Srv:hostA.domain   ENCR:128       ← mail.someother.domain not listed

When sendmail connects to mail.someother.domain (and when mail.someother.domain does not support STARTTLS) the message will be transmitted in plain text (unencrypted).

The tls_rcpt rule set was created specifically to deal with this problem. It is called just before a RCPT To: command is sent to the other site.

The workspace supplied to tls_rcpt is the current recipient (the one that will be given in the RCPT To: command when it is issued). This rule set is allowed to require encryption or verification of the recipient’s MTA, even if the message was redirected with MX records to another site.

The tls_rcpt rule set looks up the recipient in four different ways, where the format of the recipient address is user@host.domain. Each lookup is prefixed with a literal TLS_Rcpt:. The lookups are:

TLS_Rcpt:user@host.domain
TLS_Rcpt:user@
TLS_Rcpt:host.domain
TLS_Rcpt:domain
TLS_Rcpt:

The tls_rcpt rule set accepts the righthand-side value from the first matched lookup. If there is no match, the recipient address is considered good and the RCPT To: command is allowed to be issued.

The allowable righthand-side values are the same as those described for the tls_server rule set in the preceding section. The requirements in the righthand side are compared to the ${verify} and ${cipher_bits} macros, as appropriate, and the connection is either allowed to continue, or not, based on the result.

To illustrate, consider the MX example given earlier. If the access database contains the following entry:

TLS_Rcpt:hostA.domain   ENCR:128

encryption is required for any recipient at hostA.domain, even if delivery is redirected with an MX record to another site, such as mail.someother.domain.

In addition to the righthand-side values described earlier, the tls_rcpt rule set allows four righthand-side suffixes. Each starts with a plus sign, and when two or more are listed, each is separated from the others with two plus signs:

TLS_Rcpt:hostA.domain   ENCR:128+CN:smtp.hostA.domain++CI:hostB.domain

The suffixes allow further checks to be applied to the connection in addition to those required by the existing righthand-side value. The suffixes and their meanings are:

If you wish to add your own rules to the tls_rcpt rule set, you can do so with the following mc configuration command:

LOCAL_TLS_RCPT
 ← additional rules for tls_rcpt here

If your rules return a #error or #discard delivery agent, the connection is rejected. If they return a $#OK,^[101] the connection is accepted and subsequent tls_rcpt rule set rules are skipped (the access database lookups are not performed):

R $*              $# OK      skip subsequent tls_rcpt rule set rules

But if they return a $@OK, further tls_rcpt rule set rules are allowed, and the access database lookups are performed, which might subsequently reject the connection:

R $*              $@ OK      allow subsequent tls_rcpt rule set rules

Your rules, if any, will be called first. That is, for example, if you add rules to tls_rcpt, those rules will be called before those that were already in the tls_rcpt rule set. You need not restore the workspace at the end of your rules, however, because that restoration is taken care of for you.

By default, STARTTLS is used whenever possible. Unfortunately, some hosts on the Internet do not properly implement STARTTLS, so even though they offer STARTTLS, they don’t use it properly and the connection fails. If you know ahead of time which hosts have this problem, you can list them in the access database and cause STARTTLS to be skipped for them.

The try_tls rule set allows you to exempt specific connecting hosts and domains from STARTTLS support. This rule set simply looks up the connecting host’s hostname and address in the access database. Each lookup is prefixed with a literal Try_TLS:. If the lookup finds the host or address (if either is in the access database), the use of STARTTLS is suppressed:

Try_TLS:broken.server                NO      ← a domain
Try_TLS:host.broken.server           NO      ← a host
Try_TLS:123.45.67.89                 NO      ← an IPv4 address
Try_TLS:IPv6:2002:c0a8:51d2::23f4    NO      ← an IPv6 address

The righthand-side value for this lookup can be anything. All the try_tls rule set cares about is whether the lookup succeeds.

If you wish to add your own rule to the try_tls rule set, you can do so with the following mc configuration command:

LOCAL_TRY_TLS
 ← additional rules for try_tls here

If your rules return a #error or #discard delivery agent, STARTTLS is suppressed. If they return a $#OK,^[102] STARTTLS is offered and subsequent try_tls rule set rules are skipped (the access database lookups are not performed):

R $*              $# OK      skip subsequent try_tls rule set rules

But if they return a $@OK, STARTTLS might be offered. We say “might” because further try_tls rule set rules are allowed, and access database lookups are performed, which, in turn, can subsequently disallow STARTTLS:

R $*              $@ OK      allow subsequent try_tls rule set rules

Your rules, if any, will be called first. That is, for example, if you add rules to try_tls, those rules will be called before those that were already in the try_tls rule set. You need not restore the workspace at the end of your rules, however, because that restoration is taken care of for you.