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.
Very briefly, the way SMTP authentication works is as follows:
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.
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 authenticator 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
AUTH_CRAM_MD5=yes AUTH_PLAINTEXT=yes
in `Local/Makefile', 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.
Almost all the code for handling authentication is omitted from Exim unless at least one AUTH_xxx is defined. This includes the code for implementing configuration options such as auth_hosts. Attempts to use such options provoke `unknown option' errors when no authentication code is included in the binary.
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
exim -bP authenticator_list exim -bP authenticators exim -bP authenticator <authenticator name>
Each authenticator can have both server and client functions. To make it clear which options apply to which, the prefixes server_ and client_ 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:
cram:
driver = cram_md5
public_name = CRAM-MD5
server_secret = ${if eq{$1}{ph10}{secret1}fail}
client_name = ph10
client_secret = secret2
The server_ option is used when Exim is acting as a server, and the client_ options when it is acting as a client.
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.
Type: string
Default: unset
This option must always be set. It specifies which of the available authenticators is to be used.
Type: string
Default: unset
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 public_name is not set, it defaults to the driver instance's name.
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.
Type: string, expanded
Default: unset
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 $authenticated_id. 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.
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 auth_hosts, it is required to authenticate itself before any commands other than HELO, EHLO, HELP, AUTH, NOOP, RSET, or QUIT are accepted.
You can insist that any client that uses the AUTH command for authentication must start a TLS encrypted session first, by setting auth_over_tls_hosts. For example,
auth_over_tls_hosts = *
means that all authentication must take place over secure sessions. See chapter 38 for details of TLS encryption.
A client that matches an item in host_auth_accept_relay is permitted to relay to any domain, provided that it is authenticated, whether or not it matches auth_hosts. In other words, an authenticated client is permitted to relay if it matches either host_accept_relay or host_auth_accept_relay, whereas an unauthenticated client host may relay only if it matches host_accept_relay.
Normally, an Exim server advertises the authentication mechanisms it supports in response to any EHLO command. However, if auth_always_advertise is set false, Exim advertises availability of the AUTH command only if the calling host is in auth_hosts, or if it is in host_auth_accept_relay and not in host_accept_relay. In other words, it advertises only when the host is required always to authenticate or to authenticate in order to relay.
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 host_accept_relay). Unsetting auth_always_advertise makes these clients more friendly in these circumstances, while still allowing you to use combinations such as
host_auth_accept_relay = * host_accept_relay = 10.9.8.0/24
without needing to fill up host_auth_accept_relay with exceptions.
When a message is received from an authenticated host, the value of $received_protocol is set to `asmtp' instead of `esmtp', and $sender_host_authenticated 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.
Exim's -bh 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:
use MIME::Base64;
printf ("%s", encode_base64(eval "\"$ARGV[0]\""));
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
encode '\0user\0password'
Note the use of single quotes to prevent the shell interpreting the
backslashes.
If you have the mimecode command installed, another way to do this is to run
the command
(but some versions of echo do not recognize the -n option).
echo -n `\0user\0password' | mimecode
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 `<>', it is set as the authenticated sender of the message. The value is available during delivery in the $authenticated_sender variable, and is passed on to other hosts to which Exim authenticates as a client. Do not confuse this value with $authenticated_id, which is a string obtained from the authentication process, and which is not usually a complete email address.
The smtp transport has an option called authenticate_hosts if Exim is built with authentication support. When the smtp transport connects to a server that announces support for authentication, and also matches an entry in authenticate_hosts, Exim (as a client) tries to authenticate as follows:
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 qualify_domain is treated as authenticated.
Go to the first, previous, next, last section, table of contents.