The ``authenticators'' section of Exim's run time configuration is concerned with SMTP authentication. This facility 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:
The server advertises a number of authentication mechanisms.
The client issues an AUTH command, naming a specific mechanism. The command may, optionally, contain some authentication data.
The server may issue one or more challenges, to which the client must send appropriate responses. In 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.
The server either accepts or denies authentication.
If authentication succeeds, the client may optionally make use of the AUTH option on the MAIL command to pass an authenticated sender in subsequent mail transactions. Authentication lasts for the remainder of the SMTP connection.
If authentication fails, the client may give up, or it may try a different authentication mechanism, or it may try transferring mail over the unauthenticated connection.
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. For example:
$ telnet server.example 25
Trying 192.168.34.25...
Connected to server.example.
Escape character is '^]'.
220 server.example ESMTP Exim 4.00 ...
ehlo client.example
250-server.example Hello client.example [10.8.4.5]
250-SIZE 52428800
250-PIPELINING
250-AUTH PLAIN
250 HELP
The second-last line of this example output shows that the server supports authentication using the PLAIN mechanism.
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 are configured by specifying authenticator drivers for Exim. Like the routers and transports, which authenticators are included in the binary is controlled by build-time definitions. The following are currently available, included by setting
AUTH_CRAM_MD5=yes AUTH_PLAINTEXT=yes AUTH_SPA=yes
in Local/Makefile, respectively. The first of these supports the CRAM-MD5 authentication mechanism (RFC 2195), and 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. The third authenticator supports Microsoft's Secure Password Authentication mechanism.
The authenticators are configured using the same syntax as other drivers (see section 6.14). If none are required, no authentication section need be present in the configuration file. Each authenticator can in principle 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 in Exim.
This option must always be set. It specifies which of the available authenticators is to be used.
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's instance 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.
If this option is set and authentication debugging is enabled (see the -d command line option), the string is expanded and included in the debugging output when the authenticator is run as a server. This can help with checking out the values of variables.
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.
This option allows a server to discard authenticated sender addresses supplied in MAIL commands according to configured conditions. If the option is unset, addresses supplied by the AUTH option of MAIL commands are always accepted. Otherwise, when an authenticated client supplies an AUTH value on a MAIL command, the value of this option is expanded. If it yields an empty string, ``0'', ``no'', or ``false'', the AUTH address is ignored. If the expansion yields any other value, the AUTH address is retained and passed on with the message. During the expansion, the address that was supplied by the AUTH keyword is available in $authenticated_sender.
When an Exim server receives an AUTH command from a client, it runs the ACL specified by acl_smtp_auth in order to decide whether to accept the command or not. If acl_smtp_auth is not set, AUTH is accepted from any client host. You can insist that any client that uses the AUTH command must first start a TLS encrypted session, by checking for encryption in the ACL that runs for AUTH (see the example in section 37.4). Other ACLs, for example, those that run for the RCPT or ETRN commands, can check whether the SMTP session has been authenticated or not.
If AUTH is not rejected by the ACL, Exim searches its configuration for a server authentication mechanism that matches the one named in the AUTH command, and then runs the appropriate authentication protocol.
Normally, an Exim server advertises the authentication mechanisms it supports in response to any EHLO command. However, this is in fact controlled by the global option auth_advertise_hosts, which defaults to *. You can use this option to turn off the authentication advertisement to certain hosts.
Some mail clients (for example, Netscape) require the user to provide a name and password for authentication whenever AUTH is advertised, even though authentication may not in fact be needed (for example, Exim may be set up to allow unconditional relaying from the client). You can make such clients more friendly by not advertising AUTH to them. For example, if clients on the 10.9.8.0/24 network are permitted (by the ACL that runs for RCPT) to relay without authentication, you should set
auth_advertise_hosts = ! 10.9.8.0/24
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. This variable 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, so that they can be interpreted by Perl to specify characters whose code value is zero. If you have the mimencode command installed, another way to do this is to run the command
echo -e -n `\0user\0password' | mimencode
The -e option of echo enables the interpretation of backslash escapes in the argument, and the -n option specifies no newline at the end of its output. However, not all versions of echo recognize these options, so you should check your version before relying on this suggestion.
Warning: If either of the user or password strings starts with an octal digit, you must use three zeros instead of one after the leading backslash. If you do not, the octal digit that starts your string will be incorrectly interpreted as part of the code for the first character.
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 two options called hosts_require_auth and hosts_try_auth. When the smtp transport connects to a server that announces support for authentication, and the host matches an entry in either of these options, Exim (as a client) tries to authenticate as follows:
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.
When it finds one that matches, it runs the authenticator's client code. The variables $host and $host_address 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.
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.
If the response to authentication is a permanent error (5xx code), Exim carries on searching the list of authenticators and tries another one if possible. If all authentication attempts give permanent errors, or if there are no attempts because no mechanisms match, what happens depends on whether the host matches hosts_require_auth or hosts_try_auth. In the first case, a temporary error is generated, and delivery is deferred. The error can be detected in the retry rules, and thereby turned into a permanent error if you wish. In the second case, Exim tries to deliver the message unauthenticated.
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.