WARNING: This documentation is for an old version of Exim (latest)
Chapter 36 - The cyrus_sasl authenticator
The code for this authenticator was provided by Matthew Byng-Maddick of A L Digital Ltd (http://www.aldigital.co.uk).
The cyrus_sasl authenticator provides server support for the Cyrus SASL library implementation of the RFC 2222 (“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.
