File: spec_38.html

package info (click to toggle)
exim-html 3.20-1
links: PTS
area: main
in suites: etch, etch-m68k, sarge, woody
size: 2,868 kB
ctags: 4,188
sloc: makefile: 40; sh: 19
file content (386 lines) | stat: -rw-r--r-- 13,532 bytes
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
     from spec on 25 November 2000 -->

<TITLE>Exim Specification - 38. Encrypted SMTP connections using TLS/SSL</TITLE>
</HEAD>
<body bgcolor="#FFFFFF" text="#00005A" link="#FF6600" alink="#FF9933" vlink="#990000">
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_37.html">previous</A>, <A HREF="spec_39.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC772" HREF="spec_toc.html#TOC772">38. Encrypted SMTP connections using TLS/SSL</A></H1>
<P>
<A NAME="IDX1700"></A>
<A NAME="IDX1701"></A>
<A NAME="IDX1702"></A>
<A NAME="IDX1703"></A>
<font color=green>
Support for TLS (Transport Layer Security), otherwise known as SSL (Secure
Sockets Layer), is implemented by making use of the OpenSSL library. There is no
cryptographic code in the Exim distribution itself. In order to use this
feature you must install OpenSSL, and then build a version that includes TLS
support. You also need to understand the basic concepts of encryption at a
managerial level, and in particular, the way that public keys, private keys,
and certificates are used.

</P>
<P>
RFC 2487 defines how SMTP connections can make use of encryption. Once a
connection is established, the client issues a STARTTLS command. If the
server accepts this, they negotate an encryption mechanism. If the negotiation
succeeds, the data that subsequently passes between them is encrypted.

</P>

<P>



<H2><A NAME="SEC773" HREF="spec_toc.html#TOC773">38.1 Configuring Exim to use TLS as a server</A></H2>

<P>
When Exim has been built with TLS support, it advertises the availability of
the STARTTLS command to client hosts that match <EM>tls_advertise_hosts</EM>,
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 it
is sensible for systems that wans to use TLS only as a client. To make it work
as a server, you must set <EM>tls_advertise_hosts</EM> 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 (see below).

</P>
<P>
If a client issues a STARTTLS command and there is some configuration
problem in the server code, 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

<PRE>
554 Security failure
</PRE>

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

</P>
<P>
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,

<PRE>
tls_certificate = /some/file/name
tls_privatekey = /some/file/name
</PRE>

<P>
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. They can be the same file if both the certificate and the key are
contained within it. If you don't 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.)

</P>
<P>
With just these two options set, Exim will work as a server with clients such
Netscape. 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

<PRE>
tls_dhparam = /some/file/name
</PRE>

<P>
is set, the SSL library is initialized for the use of Diffie-Hellman
ciphers with the parameters contained in the file. This increases the
set of ciphers that the server supports. (See the command

<PRE>
openssl dhparam
</PRE>

<P>
for a way of generating this data.)

</P>
<P>
The strings supplied for these 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 $<EM>sender_host_address</EM> to control the expansion. If a string
expansion is forced to fail, Exim behaves as if the option is not set.

</P>
<P>
<A NAME="IDX1704"></A>
<A NAME="IDX1705"></A>
The variable $<EM>tls_cipher</EM> is set to the cipher that was negotiated for an
incoming TLS connection. It is included in the <EM>Received:</EM> 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 <EM>tls_log_cipher</EM> is set false.

</P>
<P>
If you want to enforce conditions on incoming TLS connections, you must
set <EM>tls_verify_hosts</EM> to match the relevant clients. By default this host
list is unset. You could, of course, use

<PRE>
tls_verify_hosts = *
</PRE>

<P>
to make it apply to all TLS connections. When a client host is in this
list, two further options are relevant:

</P>

<UL>

<LI>

<A NAME="IDX1706"></A>
<EM>tls_verify_ciphers</EM> contains a colon-separated list of permitted
ciphers. The list is passed to the OpenSSL library, so it must
always be colon-separated -- Exim's alternate separator feature
does not apply. For example:

<PRE>
tls_verify_ciphers = DES-CBC3-SHA:IDEA-CBC-MD5
</PRE>

With this option set, all TLS sessions must use one of the listed
ciphers.

<LI>

<A NAME="IDX1707"></A>
<EM>tls_verify_certificates</EM> contains the name of a file or a directory
that contains a collection of expected certificates. A file can
contain multiple certificates, concatenated end to end. If a directory
is used, each certificate must be in a separate file, with a name (or
a symbolic link) of the form &#60;<EM>hash</EM>&#62;.0, where &#60;<EM>hash</EM>&#62; is a hash value
constructed from the certificate. You can compute the relevant hash by running
the command

<PRE>
openssl x509 -hash -noout -in /cert/file
</PRE>

where <EM>/cert/file</EM> contains a single certificate.

When <EM>tls_verify_certificates</EM> is set, Exim always requests a
certificate from the client, and fails if one is not provided. The
value of the Distinguished Name of the certificate is made available
in the variable $<EM>tls_peerdn</EM> during subsequent processing of the
message.
<A NAME="IDX1708"></A>
Because it is often a long text string, it is not included in the log line or
<EM>Received:</EM> header by default. You can arrange for it to be logged, keyed by
`DN=', by setting <EM>tls_log_peerdn</EM>, and you can use <EM>received_header_text</EM>
to change the <EM>Received:</EM> header.
</UL>

<P>
Both these options are expanded before use, so again you can make them
do different things for different hosts.

</P>
<P>
You can insist that certain client hosts use TLS, by setting <EM>tls_hosts</EM> to
match them. When a host is in <EM>tls_hosts</EM>, STARTTLS is always advertised to
it, even if it is not in <EM>tls_advertise_hosts</EM>. If such a host attempts to
send a message without starting a TLS session, the MAIL command is
rejected with the error

<PRE>
503 Use of TLS required
</PRE>

<P>
You can permit client hosts to relay, provided they are in a TLS session,
by setting <EM>tls_host_accept_relay</EM>. Note that all the host relay checks are
alternatives. Relaying is permitted if any of the checks is passed, that
is, if

</P>

<UL>

<LI>

The host matches <EM>host_accept_relay</EM>, OR

<LI>

The host is authenticated and matches <EM>host_auth_accept_relay</EM> OR

<LI>

The host is using a TLS session and matches <EM>tls_host_accept_relay</EM>.
</UL>

<P>
Using <EM>tls_host_accept_relay</EM> probably makes sense only if you are checking
the  client's certificate.

</P>
<P>
You can insist that any client that uses the AUTH command for
authentication must start a TLS session first, by setting
<EM>auth_over_tls_hosts</EM>. For example,

<PRE>
auth_over_tls_hosts = *
</PRE>

<P>
means that all authentication must take place over secure sessions. This
setting does not force the matching hosts to use AUTH, but if they do, they
must issue STARTTLS first. The availability of the AUTH command is
advertised to such hosts only after a TLS session has been started.

</P>



<H2><A NAME="SEC774" HREF="spec_toc.html#TOC774">38.2 Configuring Exim to use TLS as a client</A></H2>

<P>
<A NAME="IDX1709"></A>
<A NAME="IDX1710"></A>
<A NAME="IDX1711"></A>
The <EM>tls_log_cipher</EM> and <EM>tls_log_peerdn</EM> options 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 <EM>smtp</EM> transport.

</P>
<P>
It is not necessary to set any options to have TLS work in the <EM>smtp</EM>
transport. If TLS is advertised by a server, the <EM>smtp</EM> transport will attempt
to start a TLS session. However, this can be prevented by setting
<EM>hosts_avoid_tls</EM> (an option of the transport) to a list of server hosts for
which TLS should not be used.

</P>
<P>
If an attempt to start a TLS session fails for a temporary reason
(for example, a 4<EM>xx</EM> response to STARTTLS), delivery to this host is
not attempted. If there are alternative hosts, they are tried; otherwise
delivery is deferred. If, on the other hand, the STARTTLS command is
rejected with a 5<EM>xx</EM> error code, the <EM>smtp</EM> transport attempts to deliver
the message in clear, unless the server matches <EM>hosts_require_tls</EM>, in which
case delivery is again deferred unless there are other hosts to try.

</P>
<P>
There are a number of options for the <EM>smtp</EM> transport which match the
global TLS options for the server, and have the same names. They are all
expanded before use, with $<EM>host</EM> and $<EM>host_address</EM> 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.

</P>

<UL>

<LI>

<EM>tls_certificate</EM>, and <EM>tls_privatekey</EM> provide the client with a
certificate, which is passed to the server if it requests it. (If the
server is Exim, it will request it only if <EM>tls_verify_certificates</EM> is set.)

<LI>

<EM>tls_verify_certificates</EM> and <EM>tls_verify_ciphers</EM> on the <EM>smtp</EM> transport
act exactly like their namesakes on the server: they do appropriate
verification on the server's certificate and the negotiated cipher,
respectively.
</UL>



<H2><A NAME="SEC775" HREF="spec_toc.html#TOC775">38.3 Multiple messages on the same TCP/IP connection</A></H2>

<P>
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 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. If
the server is Exim, this reinitialization works. It is not known if other
servers operate successfully in these circumstances. If they do not, it may be
necessary to set

<PRE>
batch_max = 1
</PRE>

<P>
on the smtp transport, to disable multiple messages down a single TCP/IP
connection.

</P>


<H2><A NAME="SEC776" HREF="spec_toc.html#TOC776">38.4 Certificates and all that</A></H2>

<P>
<A NAME="IDX1712"></A>
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 don't know very much about it
myself. Some helpful introduction can be found in the FAQ for the SSL
addition to Apache, at

<PRE>
<A HREF="http://www.modssl.org/docs/2.6/ssl_faq.html#ToC24">http://www.modssl.org/docs/2.6/ssl_faq.html#ToC24</A>
</PRE>

<P>
and other parts of the <EM>modssl</EM> documentation are also helpful, and have
links to further files.

</P>
<P>
You can create a self-signed certificate using the <EM>req</EM> command provided
with OpenSSLL, like this:

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

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

</P>
<P>
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.
</font>

</P>

<P><HR><P>
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_37.html">previous</A>, <A HREF="spec_39.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
</BODY>
</HTML>