Exim Internet Mailer

1. Support for the legacy ssmtp (aka smtps) protocol

Early implementations of encrypted SMTP used a different TCP port from normal SMTP, and expected an encryption negotiation to start immediately, instead of waiting for a STARTTLS command from the client using the standard SMTP port. The protocol was called “ssmtp” or “smtps”, and port 465 was allocated for this purpose.

This approach was abandoned when encrypted SMTP was standardized, but there are still some legacy clients that use it. Exim supports these clients by means of the tls_on_connect_ports global option. Its value must be a list of port numbers; the most common use is expected to be:

tls_on_connect_ports = 465

The port numbers specified by this option apply to all SMTP connections, both via the daemon and via inetd. You still need to specify all the ports that the daemon uses (by setting daemon_smtp_ports or local_interfaces or the -oX command line option) because tls_on_connect_ports does not add an extra port – rather, it specifies different behaviour on a port that is defined elsewhere.

There is also a -tls-on-connect command line option. This overrides tls_on_connect_ports; it forces the legacy behaviour for all ports.

2. OpenSSL vs GnuTLS

The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS followed later, when the first versions of GnuTLS were released. To build Exim to use GnuTLS, you need to set

USE_GNUTLS=yes

in Local/Makefile, in addition to

SUPPORT_TLS=yes

You must also set TLS_LIBS and TLS_INCLUDE appropriately, so that the include files and libraries for GnuTLS can be found.

There are some differences in usage when using GnuTLS instead of OpenSSL:

• The tls_verify_certificates option must contain the name of a file, not the name of a directory (for OpenSSL it can be either).

• The default value for tls_dhparam differs for historical reasons.

• Distinguished Name (DN) strings reported by the OpenSSL library use a slash for separating fields; GnuTLS uses commas, in accordance with RFC 2253. This affects the value of the $tls_peerdn variable.

• OpenSSL identifies cipher suites using hyphens as separators, for example: DES-CBC3-SHA. GnuTLS historically used underscores, for example: RSA_ARCFOUR_SHA. What is more, OpenSSL complains if underscores are present in a cipher list. To make life simpler, Exim changes underscores to hyphens for OpenSSL and passes the string unchanged to GnuTLS (expecting the library to handle its own older variants) when processing lists of cipher suites in the tls_require_ciphers options (the global option and the smtp transport option).

• The tls_require_ciphers options operate differently, as described in the sections 41.4 and 41.5.

• Some other recently added features may only be available in one or the other. This should be documented with the feature. If the documentation does not explicitly state that the feature is infeasible in the other TLS implementation, then patches are welcome.

3. GnuTLS parameter computation

This section only applies if tls_dhparam is set to historic or to an explicit path; if the latter, then the text about generation still applies, but not the chosen filename. By default, as of Exim 4.80 a hard-coded D-H prime is used. See the documentation of tls_dhparam for more information.

GnuTLS uses D-H parameters that may take a substantial amount of time to compute. It is unreasonable to re-compute them for every TLS session. Therefore, Exim keeps this data in a file in its spool directory, called gnutls-params-NNNN for some value of NNNN, corresponding to the number of bits requested. The file is owned by the Exim user and is readable only by its owner. Every Exim process that start up GnuTLS reads the D-H parameters from this file. If the file does not exist, the first Exim process that needs it computes the data and writes it to a temporary file which is renamed once it is complete. It does not matter if several Exim processes do this simultaneously (apart from wasting a few resources). Once a file is in place, new Exim processes immediately start using it.

For maximum security, the parameters that are stored in this file should be recalculated periodically, the frequency depending on your paranoia level. If you are avoiding using the fixed D-H primes published in RFCs, then you are concerned about some advanced attacks and will wish to do this; if you do not regenerate then you might as well stick to the standard primes.

Arranging this is easy in principle; just delete the file when you want new values to be computed. However, there may be a problem. The calculation of new parameters needs random numbers, and these are obtained from /dev/random. If the system is not very active, /dev/random may delay returning data until enough randomness (entropy) is available. This may cause Exim to hang for a substantial amount of time, causing timeouts on incoming connections.

The solution is to generate the parameters externally to Exim. They are stored in gnutls-params-N in PEM format, which means that they can be generated externally using the certtool command that is part of GnuTLS.

To replace the parameters with new ones, instead of deleting the file and letting Exim re-create it, you can generate new parameters using certtool and, when this has been done, replace Exim’s cache file by renaming. The relevant commands are something like this:

# ls
[ look for file; assume gnutls-params-2236 is the most recent ]
# rm -f new-params
# touch new-params
# chown exim:exim new-params
# chmod 0600 new-params
# certtool --generate-dh-params --bits 2236 >>new-params
# openssl dhparam -noout -text -in new-params | head
[ check the first line, make sure it's not more than 2236;
  if it is, then go back to the start ("rm") and repeat
  until the size generated is at most the size requested ]
# chmod 0400 new-params
# mv new-params gnutls-params-2236

If Exim never has to generate the parameters itself, the possibility of stalling is removed.

The filename changed in Exim 4.80, to gain the -bits suffix. The value which Exim will choose depends upon the version of GnuTLS in use. For older GnuTLS, the value remains hard-coded in Exim as 1024. As of GnuTLS 2.12.x, there is a way for Exim to ask for the "normal" number of bits for D-H public-key usage, and Exim does so. This attempt to remove Exim from TLS policy decisions failed, as GnuTLS 2.12 returns a value higher than the current hard-coded limit of the NSS library. Thus Exim gains the tls_dh_max_bits global option, which applies to all D-H usage, client or server. If the value returned by GnuTLS is greater than tls_dh_max_bits then the value will be clamped down to tls_dh_max_bits. The default value has been set at the current NSS limit, which is still much higher than Exim historically used.

The filename and bits used will change as the GnuTLS maintainers change the value for their parameter GNUTLS_SEC_PARAM_NORMAL, as clamped by tls_dh_max_bits. At the time of writing (mid 2012), GnuTLS 2.12 recommends 2432 bits, while NSS is limited to 2236 bits.

In fact, the requested value will be *lower* than tls_dh_max_bits, to increase the chance of the generated prime actually being within acceptable bounds, as GnuTLS has been observed to overshoot. Note the check step in the procedure above. There is no sane procedure available to Exim to double-check the size of the generated prime, so it might still be too large.

4. Requiring specific ciphers in OpenSSL

There is a function in the OpenSSL library that can be passed a list of cipher suites before the cipher negotiation takes place. This specifies which ciphers are acceptable. The list is colon separated and may contain names like DES-CBC3-SHA. Exim passes the expanded value of tls_require_ciphers directly to this function call. Many systems will install the OpenSSL manual-pages, so you may have ciphers(1) available to you. The following quotation from the OpenSSL documentation specifies what forms of item are allowed in the cipher string:

• It can consist of a single cipher suite such as RC4-SHA.

• It can represent a list of cipher suites containing a certain algorithm, or cipher suites of a certain type. For example SHA1 represents all ciphers suites using the digest algorithm SHA1 and SSLv3 represents all SSL v3 algorithms.

• Lists of cipher suites can be combined in a single cipher string using the + character. This is used as a logical and operation. For example SHA1+DES represents all cipher suites containing the SHA1 and the DES algorithms.

Each cipher string can be optionally preceded by one of the characters !, - or +.

• If ! is used, the ciphers are permanently deleted from the list. The ciphers deleted can never reappear in the list even if they are explicitly stated.

• If - is used, the ciphers are deleted from the list, but some or all of the ciphers can be added again by later options.

• If + is used, the ciphers are moved to the end of the list. This option does not add any new ciphers; it just moves matching existing ones.

If none of these characters is present, the string is interpreted as a list of ciphers to be appended to the current preference list. If the list includes any ciphers already present they will be ignored: that is, they will not be moved to the end of the list.

The OpenSSL ciphers(1) command may be used to test the results of a given string:

# note single-quotes to get ! past any shell history expansion
$ openssl ciphers 'HIGH:!MD5:!SHA1'

This example will let the library defaults be permitted on the MX port, where there’s probably no identity verification anyway, but ups the ante on the submission ports where the administrator might have some influence on the choice of clients used:

# OpenSSL variant; see man ciphers(1)
tls_require_ciphers = ${if =={$received_port}{25}\
                           {DEFAULT}\
                           {HIGH:!MD5:!SHA1}}

5. Requiring specific ciphers or other parameters in GnuTLS

The GnuTLS library allows the caller to provide a "priority string", documented as part of the gnutls_priority_init function. This is very similar to the ciphersuite specification in OpenSSL.

The tls_require_ciphers option is treated as the GnuTLS priority string.

The tls_require_ciphers option is available both as an global option, controlling how Exim behaves as a server, and also as an option of the smtp transport, controlling how Exim behaves as a client. In both cases the value is string expanded. The resulting string is not an Exim list and the string is given to the GnuTLS library, so that Exim does not need to be aware of future feature enhancements of GnuTLS.

Documentation of the strings accepted may be found in the GnuTLS manual, under "Priority strings". This is online as http://www.gnu.org/software/gnutls/manual/html_node/Priority-Strings.html, but beware that this relates to GnuTLS 3, which may be newer than the version installed on your system. If you are using GnuTLS 3, then the example code on that site can be used to test a given string.

Prior to Exim 4.80, an older API of GnuTLS was used, and Exim supported three additional options, "gnutls_require_kx", "gnutls_require_mac" and "gnutls_require_protocols". tls_require_ciphers was an Exim list.

This example will let the library defaults be permitted on the MX port, where there’s probably no identity verification anyway, and lowers security further by increasing compatibility; but this ups the ante on the submission ports where the administrator might have some influence on the choice of clients used:

# GnuTLS variant
tls_require_ciphers = ${if =={$received_port}{25}\
                           {NORMAL:%COMPAT}\
                           {SECURE128}}

6. Configuring an Exim server to use TLS

When Exim has been built with TLS support, it advertises the availability of the STARTTLS command to client hosts that match tls_advertise_hosts, but not to any others. The default value of this option is unset, which means that STARTTLS is not advertised at all. This default is chosen because you need to set some other options in order to make TLS available, and also it is sensible for systems that want to use TLS only as a client.

If a client issues a STARTTLS command and there is some configuration problem in the server, the command is rejected with a 454 error. If the client persists in trying to issue SMTP commands, all except QUIT are rejected with the error

554 Security failure

If a STARTTLS command is issued within an existing TLS session, it is rejected with a 554 error code.

To enable TLS operations on a server, you must set tls_advertise_hosts to match some hosts. You can, of course, set it to * to match all hosts. However, this is not all you need to do. TLS sessions to a server won’t work without some further configuration at the server end.

It is rumoured that all existing clients that support TLS/SSL use RSA encryption. To make this work you need to set, in the server,

tls_certificate = /some/file/name
tls_privatekey = /some/file/name

These options are, in fact, expanded strings, so you can make them depend on the identity of the client that is connected if you wish. The first file contains the server’s X509 certificate, and the second contains the private key that goes with it. These files need to be readable by the Exim user, and must always be given as full path names. They can be the same file if both the certificate and the key are contained within it. If tls_privatekey is not set, or if its expansion is forced to fail or results in an empty string, this is assumed to be the case. The certificate file may also contain intermediate certificates that need to be sent to the client to enable it to authenticate the server’s certificate.

If you do not understand about certificates and keys, please try to find a source of this background information, which is not Exim-specific. (There are a few comments below in section 41.12.)

Note: These options do not apply when Exim is operating as a client – they apply only in the case of a server. If you need to use a certificate in an Exim client, you must set the options of the same names in an smtp transport.

With just these options, an Exim server will be able to use TLS. It does not require the client to have a certificate (but see below for how to insist on this). There is one other option that may be needed in other situations. If

tls_dhparam = /some/file/name

is set, the SSL library is initialized for the use of Diffie-Hellman ciphers with the parameters contained in the file.

Set this to none to disable use of DH entirely, by making no prime available:

tls_dhparam = none

This may also be set to a string identifying a standard prime to be used for DH; if it is set to default or, for OpenSSL, is unset, then the prime used is ike23. There are a few standard primes available, see the documetnation for tls_dhparam for the complete list.

See the command

openssl dhparam

for a way of generating file data.

The strings supplied for these three options are expanded every time a client host connects. It is therefore possible to use different certificates and keys for different hosts, if you so wish, by making use of the client’s IP address in $sender_host_address to control the expansion. If a string expansion is forced to fail, Exim behaves as if the option is not set.

The variable $tls_cipher is set to the cipher suite that was negotiated for an incoming TLS connection. It is included in the Received: header of an incoming message (by default – you can, of course, change this), and it is also included in the log line that records a message’s arrival, keyed by “X=”, unless the tls_cipher log selector is turned off. The encrypted condition can be used to test for specific cipher suites in ACLs. (For outgoing SMTP deliveries, $tls_cipher is reset – see section 41.9.)

Once TLS has been established, the ACLs that run for subsequent SMTP commands can check the name of the cipher suite and vary their actions accordingly. The cipher suite names vary, depending on which TLS library is being used. For example, OpenSSL uses the name DES-CBC3-SHA for the cipher suite which in other contexts is known as TLS_RSA_WITH_3DES_EDE_CBC_SHA. Check the OpenSSL or GnuTLS documentation for more details.

7. Requesting and verifying client certificates

If you want an Exim server to request a certificate when negotiating a TLS session with a client, you must set either tls_verify_hosts or tls_try_verify_hosts. You can, of course, set either of them to * to apply to all TLS connections. For any host that matches one of these options, Exim requests a certificate as part of the setup of the TLS session. The contents of the certificate are verified by comparing it with a list of expected certificates. These must be available in a file or, for OpenSSL only (not GnuTLS), a directory, identified by tls_verify_certificates.

A file can contain multiple certificates, concatenated end to end. If a directory is used (OpenSSL only), each certificate must be in a separate file, with a name (or a symbolic link) of the form <hash>.0, where <hash> is a hash value constructed from the certificate. You can compute the relevant hash by running the command

openssl x509 -hash -noout -in /cert/file

where /cert/file contains a single certificate.

The difference between tls_verify_hosts and tls_try_verify_hosts is what happens if the client does not supply a certificate, or if the certificate does not match any of the certificates in the collection named by tls_verify_certificates. If the client matches tls_verify_hosts, the attempt to set up a TLS session is aborted, and the incoming connection is dropped. If the client matches tls_try_verify_hosts, the (encrypted) SMTP session continues. ACLs that run for subsequent SMTP commands can detect the fact that no certificate was verified, and vary their actions accordingly. For example, you can insist on a certificate before accepting a message for relaying, but not when the message is destined for local delivery.

When a client supplies a certificate (whether it verifies or not), the value of the Distinguished Name of the certificate is made available in the variable $tls_peerdn during subsequent processing of the message.

Because it is often a long text string, it is not included in the log line or Received: header by default. You can arrange for it to be logged, keyed by “DN=”, by setting the tls_peerdn log selector, and you can use received_header_text to change the Received: header. When no certificate is supplied, $tls_peerdn is empty.

8. Revoked certificates

Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when certificates are revoked. If you have such a list, you can pass it to an Exim server using the global option called tls_crl and to an Exim client using an identically named option for the smtp transport. In each case, the value of the option is expanded and must then be the name of a file that contains a CRL in PEM format.

9. Configuring an Exim client to use TLS

The tls_cipher and tls_peerdn log selectors apply to outgoing SMTP deliveries as well as to incoming, the latter one causing logging of the server certificate’s DN. The remaining client configuration for TLS is all within the smtp transport.

It is not necessary to set any options to have TLS work in the smtp transport. If Exim is built with TLS support, and TLS is advertised by a server, the smtp transport always tries to start a TLS session. However, this can be prevented by setting hosts_avoid_tls (an option of the transport) to a list of server hosts for which TLS should not be used.

If you do not want Exim to attempt to send messages unencrypted when an attempt to set up an encrypted connection fails in any way, you can set hosts_require_tls to a list of hosts for which encryption is mandatory. For those hosts, delivery is always deferred if an encrypted connection cannot be set up. If there are any other hosts for the address, they are tried in the usual way.

When the server host is not in hosts_require_tls, Exim may try to deliver the message unencrypted. It always does this if the response to STARTTLS is a 5xx code. For a temporary error code, or for a failure to negotiate a TLS session after a success response code, what happens is controlled by the tls_tempfail_tryclear option of the smtp transport. If it is false, delivery to this host is deferred, and other hosts (if available) are tried. If it is true, Exim attempts to deliver unencrypted after a 4xx response to STARTTLS, and if STARTTLS is accepted, but the subsequent TLS negotiation fails, Exim closes the current connection (because it is in an unknown state), opens a new one to the same host, and then tries the delivery unencrypted.

The tls_certificate and tls_privatekey options of the smtp transport provide the client with a certificate, which is passed to the server if it requests it. If the server is Exim, it will request a certificate only if tls_verify_hosts or tls_try_verify_hosts matches the client.

If the tls_verify_certificates option is set on the smtp transport, it must name a file or, for OpenSSL only (not GnuTLS), a directory, that contains a collection of expected server certificates. The client verifies the server’s certificate against this collection, taking into account any revoked certificates that are in the list defined by tls_crl.

If tls_require_ciphers is set on the smtp transport, it must contain a list of permitted cipher suites. If either of these checks fails, delivery to the current host is abandoned, and the smtp transport tries to deliver to alternative hosts, if any.

Note: These options must be set in the smtp transport for Exim to use TLS when it is operating as a client. Exim does not assume that a server certificate (set by the global options of the same name) should also be used when operating as a client.

All the TLS options in the smtp transport are expanded before use, with $host and $host_address containing the name and address of the server to which the client is connected. Forced failure of an expansion causes Exim to behave as if the relevant option were unset.

Before an SMTP connection is established, the $tls_bits, $tls_cipher, $tls_peerdn and $tls_sni variables are emptied. (Until the first connection, they contain the values that were set when the message was received.) If STARTTLS is subsequently successfully obeyed, these variables are set to the relevant values for the outgoing connection.

10. Use of TLS Server Name Indication

With TLS1.0 or above, there is an extension mechanism by which extra information can be included at various points in the protocol. One of these extensions, documented in RFC 6066 (and before that RFC 4366) is “Server Name Indication”, commonly “SNI”. This extension is sent by the client in the initial handshake, so that the server can examine the servername within and possibly choose to use different certificates and keys (and more) for this session.

This is analagous to HTTP’s “Host:” header, and is the main mechanism by which HTTPS-enabled web-sites can be virtual-hosted, many sites to one IP address.

With SMTP to MX, there are the same problems here as in choosing the identity against which to validate a certificate: you can’t rely on insecure DNS to provide the identity which you then cryptographically verify. So this will be of limited use in that environment.

With SMTP to Submission, there is a well-defined hostname which clients are connecting to and can validate certificates against. Thus clients can choose to include this information in the TLS negotiation. If this becomes wide-spread, then hosters can choose to present different certificates to different clients. Or even negotiate different cipher suites.

The tls_sni option on an SMTP transport is an expanded string; the result, if not empty, will be sent on a TLS session as part of the handshake. There’s nothing more to it. Choosing a sensible value not derived insecurely is the only point of caution. The $tls_sni variable will be set to this string for the lifetime of the client connection (including during authentication).

Except during SMTP client sessions, if $tls_sni is set then it is a string received from a client. It can be logged with the log_selector item +tls_sni.

If the string tls_sni appears in the main section’s tls_certificate option (prior to expansion) then the following options will be re-expanded during TLS session handshake, to permit alternative values to be chosen:

• tls_certificate

• tls_crl

• tls_privatekey

• tls_verify_certificates

Great care should be taken to deal with matters of case, various injection attacks in the string (../ or SQL), and ensuring that a valid filename can always be referenced; it is important to remember that $tls_sni is arbitrary unverified data provided prior to authentication.

The Exim developers are proceeding cautiously and so far no other TLS options are re-expanded.

When Exim is built againt OpenSSL, OpenSSL must have been built with support for TLS Extensions. This holds true for OpenSSL 1.0.0+ and 0.9.8+ with enable-tlsext in EXTRACONFIGURE. If you invoke openssl s_client -h and see -servername in the output, then OpenSSL has support.

When Exim is built against GnuTLS, SNI support is available as of GnuTLS 0.5.10. (Its presence predates the current API which Exim uses, so if Exim built, then you have SNI support).

11. Multiple messages on the same encrypted TCP/IP connection

Exim sends multiple messages down the same TCP/IP connection by starting up an entirely new delivery process for each message, passing the socket from one process to the next. This implementation does not fit well with the use of TLS, because there is quite a lot of state information associated with a TLS connection, not just a socket identification. Passing all the state information to a new process is not feasible. Consequently, Exim shuts down an existing TLS session before passing the socket to a new process. The new process may then try to start a new TLS session, and if successful, may try to re-authenticate if AUTH is in use, before sending the next message.

The RFC is not clear as to whether or not an SMTP session continues in clear after TLS has been shut down, or whether TLS may be restarted again later, as just described. However, if the server is Exim, this shutdown and reinitialization works. It is not known which (if any) other servers operate successfully if the client closes a TLS session and continues with unencrypted SMTP, but there are certainly some that do not work. For such servers, Exim should not pass the socket to another process, because the failure of the subsequent attempt to use it would cause Exim to record a temporary host error, and delay other deliveries to that host.

To test for this case, Exim sends an EHLO command to the server after closing down the TLS session. If this fails in any way, the connection is closed instead of being passed to a new delivery process, but no retry information is recorded.

There is also a manual override; you can set hosts_nopass_tls on the smtp transport to match those hosts for which Exim should not pass connections to new processes if TLS has been used.

12. Certificates and all that

In order to understand fully how TLS works, you need to know about certificates, certificate signing, and certificate authorities. This is not the place to give a tutorial, especially as I do not know very much about it myself. Some helpful introduction can be found in the FAQ for the SSL addition to Apache, currently at

http://www.modssl.org/docs/2.7/ssl_faq.html#ToC24

Other parts of the modssl documentation are also helpful, and have links to further files. Eric Rescorla’s book, SSL and TLS, published by Addison-Wesley (ISBN 0-201-61598-3), contains both introductory and more in-depth descriptions. Some sample programs taken from the book are available from

http://www.rtfm.com/openssl-examples/

13. Certificate chains

The file named by tls_certificate may contain more than one certificate. This is useful in the case where the certificate that is being sent is validated by an intermediate certificate which the other end does not have. Multiple certificates must be in the correct order in the file. First the host’s certificate itself, then the first intermediate certificate to validate the issuer of the host certificate, then the next intermediate certificate to validate the issuer of the first intermediate certificate, and so on, until finally (optionally) the root certificate. The root certificate must already be trusted by the recipient for validation to succeed, of course, but if it’s not preinstalled, sending the root certificate along with the rest makes it available for the user to install if the receiving end is a client MUA that can interact with a user.

14. Self-signed certificates

You can create a self-signed certificate using the req command provided with OpenSSL, like this:

openssl req -x509 -newkey rsa:1024 -keyout file1 -out file2 \
            -days 9999 -nodes

file1 and file2 can be the same file; the key and the certificate are delimited and so can be identified independently. The -days option specifies a period for which the certificate is valid. The -nodes option is important: if you do not set it, the key is encrypted with a passphrase that you are prompted for, and any use that is made of the key causes more prompting for the passphrase. This is not helpful if you are going to use this certificate and key in an MTA, where prompting is not possible.

A self-signed certificate made in this way is sufficient for testing, and may be adequate for all your requirements if you are mainly interested in encrypting transfers, and not in secure identification.

However, many clients require that the certificate presented by the server be a user (also called “leaf” or “site”) certificate, and not a self-signed certificate. In this situation, the self-signed certificate described above must be installed on the client host as a trusted root certification authority (CA), and the certificate used by Exim must be a user certificate signed with that self-signed certificate.

For information on creating self-signed CA certificates and using them to sign user certificates, see the General implementation overview chapter of the Open-source PKI book, available online at http://ospkibook.sourceforge.net/.