Recipe 8.7 Requiring Outbound Encryption

Problem

To prevent mail bound for particular hosts from being sent in the clear, you have been asked to configure sendmail to only send mail to the specified hosts when the connection is satisfactorily encrypted.

Solution

OpenSSL and STARTTLS support are prerequisites. See Introduction and Recipe 8.4 for additional details on these basic components .

Specify the level of encryption required for outbound connections using a TLS_Srv : entry in the access database. The key field of each entry is the tag TLS_Srv : followed by the domain name or IP address of the remote TLS server to which the local host will connect. The return value should contain the keyword ENCR : followed by the number of bits of encryption required when connecting to the specified remote host.

Create a sendmail configuration that supports STARTTLS and the access database. Here are sample STARTTLS defines and an access_db FEATURE macro:

 dnl Point to the CA certificate directory define(`confCACERT_PATH', `/etc/mail/certs') dnl Point to the root CA's certificate define(`confCACERT', `/etc/mail/certs/cacert.pem') dnl Point to the certificate used for inbound connections define(`confSERVER_CERT', `/etc/mail/certs/cert.pem') dnl Point to the private key used for inbound connections define(`confSERVER_KEY', `/etc/mail/certs/key.pem') dnl Point to the certificate used for outbound connections define(`confCLIENT_CERT', `/etc/mail/certs/cert.pem') dnl Point to the private key used for outbound connections define(`confCLIENT_KEY', `/etc/mail/certs/key.pem') dnl Enable the access database FEATURE(`access_db') 

Rebuild and install the sendmail.cf file, then restart sendmail. See Recipe 1.8 as an example.

Discussion

Most mail is sent as clear text because the vast majority of systems do not use TLS. Even when STARTTLS is configured, a host sends outbound mail without regard to the level of encryption used. If you require encryption for mail sent to a specific site, you must tell sendmail about that requirement. The access database provides the means for informing sendmail of this requirement.

The TLS_Srv : entry defines the STARTTLS requirements for outbound connections. The format of the entry is:

 TLS_Srv:   name requirement   

TLS_Srv : is the required tag. name is the name of the remote TLS server, which can be defined by domain name or IP address. If the name field is blank, the entry applies to all outbound mail connections. Because most sendmail systems send mail to a wide variety of remote systems, some of which have STARTTLS and some of which do not, the name field is almost never blank. requirement is the keyword that tells sendmail what is required of this TLS connection.

The ENCR : keyword in the requirement field tells sendmail that encryption is required. The keyword is followed by the minimum number of encryption bits that must be used. Here is a sample access database entry:

 TLS_Srv:chef.wrotethebook.com     ENCR:168 

This entry tells sendmail that when a connection is made to chef.wrotethebook.com , the connection must be encrypted with at least 168-bit encryption.

168-bits is the default level of encryption used on our sample STARTTLS connection. You can check the level of encryption used on your link by sending a test message and looking at the Received : header in the message. For example:

 Received: from rodent.wrotethebook.com (rodent.wrotethebook.com     [192.168.0.3])         by chef.wrotethebook.com (8.12.9/8.12.9) with ESMTP id     h13GqDl5001443         (version=TLSv1/SSLv3 cipher=EDH-RSA-DES-CBC3-SHA bits=168 verify=OK)         for <[e-mail]>; Mon, 3 Feb 2003 11:52:14 -0500 

This header tells you that 168-bits encryption is used ( bits=168 ). If the TLS_Srv : entry shown above was installed on rodent , mail would flow to chef because the link between the two systems has a sufficient level of encryption. However, if the link between the two systems did not meet the minimum standard of encryption, the client would abort the connection before sending the mail, as this test demonstrates :

 #  sendmail -Am -v -t   To: [e-mail]   From: [e-mail]   Subject: Test ENCR:168 with no TLS link   Ctrl-D  [e-mail]... Connecting to chef.wrotethebook.com. via esmtp... 220 chef.wrotethebook.com ESMTP Sendmail 8.12.9/8.12.9; Fri, 22 Aug 2003 12:01:37 - 0400 >>> EHLO rodent.wrotethebook.com 250-chef.wrotethebook.com Hello rodent.wrotethebook.com [192.168.0.3], pleased to  meet you 250-ENHANCEDSTATUSCODES 250-PIPELINING 250-EXPN 250-VERB 250-8BITMIME 250-SIZE 250-DSN 250-ETRN 250-AUTH DIGEST-MD5 CRAM-MD5 250-DELIVERBY 250 HELP >>> QUIT 221 2.0.0 chef.wrotethebook.com closing connection [e-mail]... Deferred: 403 4.7.0 encryption too weak 0 less than  168 Closing connection to chef.wrotethebook.com. 

In this case, the server fails to offer STARTTLS, while the client's access database requires 168-bit encryption on this link. The client terminates the connection with an "encryption too weak" error message. The message displays the number of encryption bits used by the server (0 in this case because TLS did not start) and the number required by the client (168 in this example). The SMTP response code of this error message is 403, and the DSN code is 4.7.0. Each code starts with a 4, which indicates that this is a temporary failure. The keyword "Deferred" in the message indicates that sendmail will attempt to deliver this message again during the next queue run.

Treating a STARTTLS failure as a temporary failure, which is the default, is generally correct. Normally, a server is identified in a TLS_Srv : entry only when the server actually offers STARTTLS. If the server fails to successfully create a TLS connection with the client, the failure is probably temporary. However, it is up to you to decide whether the failure should be considered temporary. The requirement field in a TLS_Srv : entry can be preceded by the string TEMP+ to select a temporary failure, which is the default, or by the string PERM+ to select a permanent error. For example, assume the access database on rodent contained the following TLS_Srv : entry:

 TLS_Srv:chef.wrotethebook.com         PERM+ENCR:168 

If chef.wrotethebook.com does not offer at least 168-bit encryption, the client terminates the session and returns the mail to the sender. No more attempts are made to deliver the mail. The sender sees the following error in the returned message:

 ----- The following addresses had permanent fatal errors ----- [e-mail]     (reason: 503 5.7.0 encryption too weak 0 less than 168) 

Use the define TLS_PERM_ERR as an alternative to adding PERM+ to the requirement field. The following line added to the sendmail configuration changes the default from a temporary failure to a permanent failure:

 define(`TLS_PERM_ERR') 

With this setting, individual actions must be flagged as temporary failures using TEMP+ .

The search for TLS_Srv : access database entries occurs in the tls_server ruleset, which is called by the client when the client is ready to issue the STARTTLS command. The tls_server ruleset is called with the value returned by ${verify} in its workspace. The tls_server ruleset makes three attempts to find a TLS_Srv : match. It first uses ruleset D to find a TLS_Srv : entry that matches the hostname returned by ${server_name} . If no match is found, it then uses ruleset A to find a TLS_Srv : entry that matches the value returned by ${server_addr} . If there is still no match, it looks for a TLS_Srv : entry with a blank name field. These searches process all possible matches for a given domain name and IP address. For example, for a connection to foo.bar.example.com with IP address 192.168.23.45, the following lookups would happen, in the order listed, until a match was found:

 TLS_Srv:foo.bar.example.com TLS_Srv:bar.example.com TLS_Srv:example.com TLS_Srv:com TLS_Srv:192.168.23.45 TLS_Srv:192.168.23 TLS_Srv:192.168 TLS_Srv:192 TLS_Srv: 

The ruleset TLS_connection is called and passed anything returned by the access database lookups. It is TLS_connection that processes the ENCR : requirement field and compares the number of bits from that field to the number of bits returned by ${cipher_bits} . If the macro ${cipher_bits} is less than the value from the requirement field, an error message is displayed and the connection ends.

The m4 macro LOCAL_TLS_SERVER allows you to add custom sendmail.cf rewrite rules to the beginning of the tls_server process. Put the LOCAL_TLS_SERVER macro at the end of the master configuration file and list the custom rewrite rules after the macro.

See Also

Recipe 8.8 and Recipe 8.9 cover related access database entries. In particular, VERIFY : is an alternative action keyword that can be used to implement this recipe. See Recipe 8.9 for details on the VERIFY : keyword. Recipe 8.5 and Recipe 8.6 also describe how the access database is used with STARTTLS. The basic STARTTLS recipe upon which this recipe is built is covered in Recipe 8.4. The sendmail book covers the use of the access database with STARTTLS in Section 10.10.8.