File: spec_35.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 (403 lines) | stat: -rw-r--r-- 13,386 bytes
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
     from spec on 25 November 2000 -->

<TITLE>Exim Specification - 35. SMTP authentication</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_34.html">previous</A>, <A HREF="spec_36.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="SEC751" HREF="spec_toc.html#TOC751">35. SMTP authentication</A></H1>
<P>
<A NAME="IDX1681"></A>
<A NAME="IDX1682"></A>
The seventh part of Exim's run time configuration, following the rewriting
configuration, is concerned with SMTP authentication. This is an extension to
the SMTP protocol, described in RFC 2554, which allows a client SMTP host to
authenticate itself to a server. By this means a server might, for example,
recognize clients that are permitted to use it as a relay. SMTP authentication
is not of relevance to the transfer of mail between servers that have no
managerial connection with each other.

</P>
<P>
<font color=green>
Very briefly, the way SMTP authentication works is as follows:

</P>

<UL>

<LI>

The server advertises a number of authentication <EM>mechanisms</EM>.

<LI>

The client issues an AUTH command, naming a specific mechanism. The command
may, optionally, contain some authentication data.

<LI>

The server may issue one or more <EM>challenges</EM>, to which the client must send
appropriate responses. In the simple authentication mechanisms, the
challenges are just prompts for user names and passwords. The server does not
have to issue any challenges -- in some mechanisms the relevant data may all be
transmitted with the AUTH command.

<LI>

The server either accepts or denies authentication.
</UL>

<P>
If you are setting up a client, and want to know which authentication
mechanisms the server supports, you can use Telnet to connect to port 25 (the
SMTP port) on the server, and issue an EHLO command. The response to this
includes the list of supported mechanisms.
</font>

</P>
<P>
When Exim is receiving SMTP mail, it is acting as a server; when it is sending
out messages over SMTP, it is acting as a client. Configuration options are
provided for use in both these circumstances. The different authentication
mechanisms. These are configured by specifying <EM>authenticator</EM> drivers for
Exim. Like the directors, routers, and transports, which authenticators are
included in the binary is controlled by build-time definitions. Two are
currently available, included by setting

<PRE>
AUTH_CRAM_MD5=yes
AUTH_PLAINTEXT=yes
</PRE>

<P>
in <TT>`Local/Makefile'</TT>, respectively. The first of these supports the CRAM-MD5
authentication mechanism (RFC 2195), while the second can be configured to
support the PLAIN authentication mechanism (RFC 2595) or the LOGIN mechanism,
which is not formally documented, but used by several MUAs.

</P>
<P>
Almost all the code for handling authentication is omitted from Exim unless at
least one AUTH_<EM>xxx</EM> is defined. This includes the code for implementing
configuration options such as <EM>auth_hosts</EM>. Attempts to use such options
provoke `unknown option' errors when no authentication code is included in the
binary.

</P>
<P>
The authenticators are configured using the same syntax as other drivers (see
chapter 12). If none are required, the entire seventh section of
the configuration file may be omitted. If at least one authenticator is
included in the binary, the contents of the configuration can be obtained by
running one of

<PRE>
exim -bP authenticator_list
exim -bP authenticators
exim -bP authenticator &#60;<EM>authenticator name</EM>&#62;
</PRE>

<P>
Each authenticator can have both server and client functions. To make it clear
which options apply to which, the prefixes <EM>server_</EM> and <EM>client_</EM> are used
on option names which are specific to either the server or the client function,
respectively. Server and client functions are disabled if none of their options
are set. If an authenticator is to be used for both server and client
functions, a single definition, using both sets of options, is required.
For example:

<PRE>
cram:
  driver = cram_md5
  public_name = CRAM-MD5
  server_secret = ${if eq{$1}{ph10}{secret1}fail}
  client_name = ph10
  client_secret = secret2
</PRE>

<P>
The <EM>server_</EM> option is used when Exim is acting as a server, and the
<EM>client_</EM> options when it is acting as a client.

</P>
<P>
Descriptions of the individual authenticators are given in subsequent chapters.
The remainder of this chapter covers the generic options for the
authenticators, followed by general discussion of the way authentication works.

</P>

<P>



<H2><A NAME="SEC752" HREF="spec_toc.html#TOC752">35.1 Generic options for authenticators</A></H2>

<P>
<A NAME="IDX1683"></A>

</P>

<P>

<P>
<A NAME="IDX1684"></A>


<H3><A NAME="SEC753" HREF="spec_toc.html#TOC753">driver</A></H3>

<P>
Type: string<BR>
Default: unset

</P>
<P>
This option must always be set. It specifies which of the available
authenticators is to be used.

</P>
<P>
<A NAME="IDX1685"></A>


<H3><A NAME="SEC754" HREF="spec_toc.html#TOC754">public_name</A></H3>

<P>
Type: string<BR>
Default: unset

</P>
<P>
This option specifies the name of the authentication mechanism which the driver
implements, and by which it is known to the outside world. These names should
contain only upper case letters, digits, underscores, and hyphens (RFC 2222),
but Exim in fact matches them caselessly. If <EM>public_name</EM> is not set, it
defaults to the driver instance's name.

</P>
<P>
The public names of authenticators that are configured as servers are
advertised by Exim when it receives an EHLO command, in the order in which
they are defined. When an AUTH command is received, the list of
authenticators is scanned in definition order for one whose public name matches
the mechanism given in the AUTH command.

</P>
<P>
<A NAME="IDX1686"></A>


<H3><A NAME="SEC755" HREF="spec_toc.html#TOC755">server_set_id</A></H3>

<P>
Type: string, expanded<BR>
Default: unset

</P>
<P>
When an Exim server successfully authenticates a client, this string
is expanded using data from the authentication, and preserved for any incoming
messages in the variable $<EM>authenticated_id</EM>. It is also included in the log
lines for incoming messages. For example, a user/password authenticator
configuration might preserve the user name which was used to authenticate, and
refer to it subsequently during delivery of the message.

</P>



<H2><A NAME="SEC756" HREF="spec_toc.html#TOC756">35.2 Authentication on an Exim server</A></H2>

<P>
<A NAME="IDX1687"></A>
<font color=green>
When any server authentication mechanisms are configured, the SMTP AUTH
command is accepted from any connected client host. If, however, the client
host matches an item in <EM>auth_hosts</EM>, it is required to authenticate itself
before any commands other than HELO, EHLO, HELP, AUTH,
NOOP, RSET, or QUIT are accepted.

</P>
<P>
You can insist that any client that uses the AUTH command for
authentication must start a TLS encrypted 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. See chapter
38 for details of TLS encryption.

</P>
<P>
<A NAME="IDX1688"></A>
A client that matches an item in <EM>host_auth_accept_relay</EM> is permitted to
relay to any domain, provided that it is authenticated, whether or not it
matches <EM>auth_hosts</EM>. In other words, an authenticated client is permitted to
relay if it matches either <EM>host_accept_relay</EM> or
<EM>host_auth_accept_relay</EM>, whereas an unauthenticated client host may relay
only if it matches <EM>host_accept_relay</EM>.

</P>
<P>
Normally, an Exim server advertises the authentication mechanisms it supports
in response to any EHLO command. However, if <EM>auth_always_advertise</EM> is
set false, Exim advertises availability of the AUTH command only if the
calling host is in <EM>auth_hosts</EM>, or if it is in <EM>host_auth_accept_relay</EM>
and not in <EM>host_accept_relay</EM>. In other words, it advertises only when the
host is required always to authenticate or to authenticate in order to relay.

</P>
<P>
Otherwise, Exim does not advertise AUTH, though it is always prepared to
accept it. Certain mail clients (for example, Netscape) require to the user to
provide a name and password for authentication if AUTH is advertised, even
though it may not be needed (the host may be in <EM>host_accept_relay</EM>).
Unsetting <EM>auth_always_advertise</EM> makes these clients more friendly in these
circumstances, while still allowing you to use combinations such as

<PRE>
host_auth_accept_relay = *
host_accept_relay = 10.9.8.0/24
</PRE>

<P>
without needing to fill up <EM>host_auth_accept_relay</EM> with exceptions.
</font>

</P>
<P>
When a message is received from an authenticated host, the value of
$<EM>received_protocol</EM> is set to `asmtp' instead of `esmtp', and
$<EM>sender_host_authenticated</EM> contains the name (not the public name) of the
authenticator driver which successfully authenticated the client from which the
message was received. It is empty if there was no successful authentication.

</P>



<H2><A NAME="SEC757" HREF="spec_toc.html#TOC757">35.3 Testing server authentication</A></H2>

<P>
<A NAME="IDX1689"></A>
Exim's -<EM>bh</EM> option can be useful for testing server
authentication configurations. The data for the AUTH command has to be sent
encoded in base 64. A quick way to produce such data for testing is the
following Perl script:

<PRE>
use MIME::Base64;
printf ("%s", encode_base64(eval "\"$ARGV[0]\""));
</PRE>

<P>
This interprets its argument as a Perl string, and then encodes it. The
interpretation as a Perl string allows binary zeros, which are required for
some kinds of authentication, to be included in the data. For example, a
command line to run this script on such data might be

<PRE>
encode '\0user\0password'
</PRE>

<P>
Note the use of single quotes to prevent the shell interpreting the
backslashes.
<font color=green>
If you have the <EM>mimecode</EM> command installed, another way to do this is to run
the command

<PRE>
echo -n `\0user\0password' | mimecode
</PRE>

<P>
(but some versions of <EM>echo</EM> do not recognize the -<EM>n</EM> option).
</font>

</P>



<H2><A NAME="SEC758" HREF="spec_toc.html#TOC758">35.4 Authenticated senders</A></H2>

<P>
<A NAME="IDX1690"></A>
When a client host has authenticated itself, Exim pays attention to the
AUTH parameter on incoming SMTP MAIL commands. Otherwise, it accepts
the syntax, but ignores the data. Unless the data is the string `&#60;&#62;', it is
set as the authenticated sender of the message. The value is available during
delivery in the $<EM>authenticated_sender</EM> variable, and is passed on to other
hosts to which Exim authenticates as a client. Do not confuse this value with
$<EM>authenticated_id</EM>, which is a string obtained from the authentication
process, and which is not usually a complete email address.

</P>



<H2><A NAME="SEC759" HREF="spec_toc.html#TOC759">35.5 Authentication by an Exim client</A></H2>

<P>
<A NAME="IDX1691"></A>
The <EM>smtp</EM> transport has an option called <EM>authenticate_hosts</EM> if Exim is
built with authentication support. When the <EM>smtp</EM> transport connects to a
server that announces support for authentication, and also matches an entry in
<EM>authenticate_hosts</EM>, Exim (as a client) tries to authenticate as follows:

</P>

<UL>

<LI>

For each authenticator that is configured as a client, it searches the
authentication mechanisms announced by the server for one whose name
matches the public name of the authenticator.

<LI>

When it finds one that matches, it runs the authenticator's client code.
The variables $<EM>host</EM> and $<EM>host_address</EM> are available for any string
expansions that the client might do. They are set to the server's name and
IP address. If any expansion is forced to fail, the authentication attempt
is abandoned. Otherwise an expansion failure causes delivery to be
deferred.

<LI>

If the result is a temporary error or a timeout, Exim abandons trying
to send the message to the host for the moment. It will try again later. If
there are any backup hosts available, they are tried in the usual way.

<LI>

If the response to authentication is a permanent error (5xx code), Exim carries
on searching the list of authenticators. If all authentication attempts give
permanent errors, or if there are no attempts because no mechanisms match, it
tries to deliver the message unauthenticated.
</UL>

<P>
When Exim has authenticated itself to a remote server, it adds the AUTH
parameter to the MAIL commands it sends, if it has got an authenticated
sender for the message. If a local process calls Exim to send a message, the
sender address that is built from the login name and <EM>qualify_domain</EM> is
treated as authenticated.

</P>

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