Recipe 8.4 Configuring sendmail for STARTTLS

Problem

You have been asked to configure sendmail to offer STARTTLS service for transport layer security.

Solution

STARTTLS requires that OpenSSL is properly installed and configured. See Introduction for information on installing OpenSSL. It also requires a copy of sendmail compiled with STARTTLS support, as described in Recipe 1.6 and Recipe 1.7. Additionally, the sendmail host needs a certificate if it will be accepting inbound STARTTLS connections. Use OpenSSL to create the certificate, as described in Recipe 8.2 and Recipe 8.3.

Create a sendmail configuration with defines pointing to the files that contain the host's certificate, the host's private key, the root CA certificate file, and the directory where CA certificates are stored. Here are examples of the defines:

 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') 

Build the sendmail.cf file, copy it to /etc/mail/sendmail.cf , and then restart sendmail, as described in Recipe 1.8.

Discussion

This recipe provides a full STARTTLS configuration. A system configured with all of these defines can act as a TLS server or client and can perform both encryption and authentication. The six defines point sendmail to the files necessary for this full range of service:

confCACERT_PATH

Sets the value for the CACERTPath option in the sendmail.cf file. The CACERTPath option points to the directory in which certificate authority certificates are stored. It is very common for this directory to be the same one that holds the server and client certificates.

confCACERT

Sets the value for the CACERTFile option, which points to the certificate of the root certificate authority. The value provided to this define is the full pathname of the file that holds the CA certificate.

confSERVER_CERT

Sets the value for the sendmail.cf ServerCertFile option, which holds the full pathname of the file containing the server certificate used for inbound conenctions.

confSERVER_KEY

Sets the value for the ServerKeyFile option. The ServerKeyFile option points to the file that holds the server's private key.

confCLIENT_CERT

Sets the value for the sendmail.cf ClientCertFile option, which holds the full pathname of the file containing the client certificate used for inbound connections.

confCLIENT_KEY

Sets the value for the ClientKeyFile option. The ClientKeyFile option points to the file that holds the client's private key.

If OpenSSL is installed, sendmail is compiled with STARTTLS support, and these defines point to valid certificates, sendmail will advertise STARTTLS in response to the SMTP EHLO command. A simple telnet test shows that STARTTLS is ready for use:

 #  telnet localhost smtp  Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. 220 chef.wrotethebook.com ESMTP Sendmail 8.12.9/8.12.9; Fri, 22 Aug 2003 12:01:37 - 0400  ehlo localhost  250-chef.wrotethebook.com Hello IDENT:6l4ZhaGP3Qczqknqm/KdTFGsrBe2SCYC@localhost  [127.0.0.1], 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-STARTTLS 250-DELIVERBY 250 HELP  QUIT  221 2.0.0 chef.wrotethebook.com closing connection Connection closed by foreign host. 

If your system doesn't advertise STARTTLS in response to the EHLO command, check the logfile to make sure that all file permissions are correct. If they are, try increasing the LogLevel to 14 to log additional STARTTLS debugging information. See Recipe 1.10 for information on setting the LogLevel .

This recipe shows a system configured with both client and server certificates and keys. Many systems are configured as both clients and servers for STARTTLS because mail is often forwarded by one system to another. When the system receives inbound mail, it acts as a STARTTLS server. When it forwards that mail on to another system, it acts as a STARTTLS client. Therefore, the system needs to act as both a STARTTLS server and a STARTTLS client. Normally such a system uses the same certificate and key for both its client and server roles.

A STARTTLS client will attempt to use STARTTLS whenever the server offers it. Running the sendmail command with the -v option shows the STARTTLS client side of this sample configuration. An example of this is seen in the following code:

 #  sendmail -Am -v -t   To: [e-mail]   From: [e-mail]   Subject: First STARTTLS test   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-STARTTLS 250-DELIVERBY 250 HELP >>> STARTTLS 220 2.0.0 Ready to start TLS >>> 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 EXTERNAL DIGEST-MD5 CRAM-MD5 250-DELIVERBY 250 HELP >>> MAIL From:<[e-mail]> SIZE=97 AUTH=[e-mail]. com 250 2.1.0 <[e-mail]>... Sender ok >>> RCPT To:<[e-mail]> >>> DATA 250 2.1.5 <[e-mail]>... Recipient ok 354 Enter mail, end with "." on a line by itself >>> . 250 2.0.0 h0UGn9P7001230 Message accepted for delivery [e-mail]... Sent (h0UGn9P7001230 Message accepted for delivery) Closing connection to chef.wrotethebook.com. >>> QUIT 221 2.0.0 chef.wrotethebook.com closing connection 

The client ( rodent ) connects to the server ( chef ) and issues an EHLO command. In response to that command, the server advertises that STARTTLS is available. The client then issues a STARTTLS command to open the TLS connection. The server responds with the message:

 220 2.0.0 Ready to start TLS 

Immediately after the response, the test shows another EHLO message. Many system administrators are confused by this. Don't be. The STARTTLS negotiation takes place "outside" of the email exchange. STARTTLS creates the encrypted tunnel through which the mail travels . The first EHLO , the server's STARTTLS advertisement, the client's STARTTLS command, and the server's TLS ready response are all used to create the tunnel. The second EHLO command and all that follows it are part of the standard SMTP protocol exchange, which is sent inside the encrypted tunnel. Note that this SMTP protocol exchange is displayed by the sendmail -v command as clear text. The mail stream is only encrypted on the network. Within the end systems, the mail stream is clear text.

The effect of the STARTTLS protocol can be indirectly observed in the headers of the mail message that passed through the encrypted tunnel. The following headers are from the test message sent by the sendmail -Am -v -t command used above:

 Return-Path: <[e-mail]> 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 h0UGn9P7001230         (version=TLSv1/SSLv3 cipher=EDH-RSA-DES-CBC3-SHA bits=168 verify=OK)         for <[e-mail]>; Thu, 30 Jan 2003 11:49:10 -0500 Received: (from root@localhost)         by rodent.wrotethebook.com (8.12.9/8.12.9) id h0UGvpSD010157;         Thu, 30 Jan 2003 11:57:51 -0500 Date: Thu, 30 Jan 2003 11:57:51 -0500 Message-Id: <[e-mail]> To: [e-mail] From: [e-mail] Subject: First STARTTLS test 

The Received : header generated by chef.wrotethebook.com , which is the STARTTLS server in this exchange, shows the TLS characteristics of the link over which the mail was received. The header displays the version of the TLS protocol that was used for the connection, the type of encryption used for the connection, the number of bits used for the encryption, and whether the client's certificate was verified . Because this information is only placed in the header when TLS is used for the connection, it tells us that the client is properly configured to use TLS when communicating with this server.

See Also

Recipe 8.2 and Recipe 8.3 cover how certificates and keys are created. Chapter 1 provides additional information on compiling sendmail. The sendmail book covers STARTTLS in Section 10.10.