42. The tls authenticator
Author: The Exim Project. <https://www.exim.org/>
Description: Exim is a message transfer agent (MTA) developed at the University of Cambridge for use on Unix systems connected to the Internet.
Keywords: exim,smtp,mta,email

# Exim Internet Mailer

<-previous next->

## Chapter 42 - The tls authenticator

The tls authenticator provides server support for authentication based on client certificates.

It is not an SMTP authentication mechanism and is not advertised by the server as part of the SMTP EHLO response. It is an Exim authenticator in the sense that it affects the protocol element of the log line, can be tested for by the authenticated ACL condition, and can set the $authenticated_id variable.

The client must present a verifiable certificate, for which it must have been requested via the tls_verify_hosts or tls_try_verify_hosts main options (see 43).

If an authenticator of this type is configured it is run immediately after a TLS connection being negotiated (due to either STARTTLS or TLS-on-connect) and can authenticate the connection. If it does, SMTP authentication is not subsequently offered.

A maximum of one authenticator of this type may be present.

The tls authenticator has three server options:

server_param1 | Use: tls | Type: string† | Default: unset

This option is expanded after the TLS negotiation and the result is placed in $auth1. If the expansion is forced to fail, authentication fails. Any other expansion failure causes a temporary error code to be returned.

server_param2 | Use: tls | Type: string† | Default: unset

server_param3 | Use: tls | Type: string† | Default: unset

As above, for $auth2 and $auth3.

server_param1 may also be spelled server_param.

Example:

    tls:
      driver = tls
      server_param1 =     ${certextract {subj_altname,mail,>:} \
                                        {$tls_in_peercert}}
      server_condition =  ${if and { {eq{$tls_in_certificate_verified}{1}} \
                                     {forany {$auth1} \
                                {!= {0} \
                                    {${lookup ldap{ldap:///\
                             mailname=${quote_ldap_dn:${lc:$item}},\
                             ou=users,LDAP_DC?mailid} {$value}{0} \
                           }    }  } }}}
      server_set_id =     ${if = {1}{${listcount:$auth1}} {$auth1}{}}

This accepts a client certificate that is verifiable against any of your configured trust-anchors (which usually means the full set of public CAs) and which has a SAN with a good account name.

Note that, up to TLS1.2, the client cert is on the wire in-clear, including the SAN, The account name is therefore guessable by an opponent. TLS 1.3 protects both server and client certificates, and is not vulnerable in this way. Likewise, a traditional plaintext SMTP AUTH done inside TLS is not.

Note that because authentication is traditionally an SMTP operation, the authenticated ACL condition cannot be used in a connect- or helo-ACL.

<-previous Table of Contents next->