36. The cyrus_sasl 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 36 - The cyrus_sasl authenticator

The code for this authenticator was provided by Matthew Byng-Maddick while at A L Digital Ltd.

The cyrus_sasl authenticator provides server support for the Cyrus SASL library implementation of the RFC 2222 [https://www.rfc-editor.org/rfc/rfc2222] (“Simple Authentication and Security Layer”). This library supports a number of authentication mechanisms, including PLAIN and LOGIN, but also several others that Exim does not support directly. In particular, there is support for Kerberos authentication.

The cyrus_sasl authenticator provides a gatewaying mechanism directly to the Cyrus interface, so if your Cyrus library can do, for example, CRAM-MD5, then so can the cyrus_sasl authenticator. By default it uses the public name of the driver to determine which mechanism to support.

Where access to some kind of secret file is required, for example, in GSSAPI or CRAM-MD5, it is worth noting that the authenticator runs as the Exim user, and that the Cyrus SASL library has no way of escalating privileges by default. You may also find you need to set environment variables, depending on the driver you are using.

The application name provided by Exim is “exim”, so various SASL options may be set in exim.conf in your SASL directory. If you are using GSSAPI for Kerberos, note that because of limitations in the GSSAPI interface, changing the server keytab might need to be communicated down to the Kerberos layer independently. The mechanism for doing so is dependent upon the Kerberos implementation.

For example, for older releases of Heimdal, the environment variable KRB5_KTNAME may be set to point to an alternative keytab file. Exim will pass this variable through from its own inherited environment when started as root or the Exim user. The keytab file needs to be readable by the Exim user. With newer releases of Heimdal, a setuid Exim may cause Heimdal to discard the environment variable. In practice, for those releases, the Cyrus authenticator is not a suitable interface for GSSAPI (Kerberos) support. Instead, consider the heimdal_gssapi authenticator, described in chapter 39

### 1. Using cyrus_sasl as a server

The cyrus_sasl authenticator has four private options. It puts the username (on a successful authentication) into $auth1. For compatibility with previous releases of Exim, the username is also placed in $1. However, the use of this variable for this purpose is now deprecated, as it can lead to confusion in string expansions that also use numeric variables for other things.

server_hostname | Use: cyrus_sasl | Type: string† | Default: see below

This option selects the hostname that is used when communicating with the library. The default value is `$primary_hostname`. It is up to the underlying SASL plug-in what it does with this data.

server_mech | Use: cyrus_sasl | Type: string | Default: see below

This option selects the authentication mechanism this driver should use. The default is the value of the generic public_name option. This option allows you to use a different underlying mechanism from the advertised name. For example:

    sasl:
      driver = cyrus_sasl
      public_name = X-ANYTHING
      server_mech = CRAM-MD5
      server_set_id = $auth1

server_realm | Use: cyrus_sasl | Type: string† | Default: unset

This specifies the SASL realm that the server claims to be in.

server_service | Use: cyrus_sasl | Type: string | Default: `smtp`

This is the SASL service that the server claims to implement.

For straightforward cases, you do not need to set any of the authenticator’s private options. All you need to do is to specify an appropriate mechanism as the public name. Thus, if you have a SASL library that supports CRAM-MD5 and PLAIN, you could have two authenticators as follows:

    sasl_cram_md5:
      driver = cyrus_sasl
      public_name = CRAM-MD5
      server_set_id = $auth1

    sasl_plain:
      driver = cyrus_sasl
      public_name = PLAIN
      server_set_id = $auth2

Cyrus SASL does implement the LOGIN authentication method, even though it is not a standard method. It is disabled by default in the source distribution, but it is present in many binary distributions.

<-previous Table of Contents next->