<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><style xmlns="" type="text/css">
div.added { background-color: #ffff99; }
div.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
div.changed { background-color: #99ff99; }
div.off { }
span.added { background-color: #ffff99; }
span.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
span.changed { background-color: #99ff99; }
span.off { }
pre.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] pre.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] div.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
</style><title>36. The cyrus_sasl authenticator</title><meta name="generator" content="DocBook XSL Stylesheets V1.72.0" /><link rel="start" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="up" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="prev" href="ch35.html" title="35. The cram_md5 authenticator" /><link rel="next" href="ch37.html" title="37. The dovecot authenticator" /></head><body><div class="navheader">
<table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch35.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch37.html">Next</a></td></tr></table></div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a href="index.html#toc0288" id="CHID10">36. The cyrus_sasl authenticator</a></h2></div>
</div>
</div>
<p>
<a id="IIDcyrauth1" class="indexterm"></a>
<a id="IIDcyrauth2" class="indexterm"></a>
<a id="id617143" class="indexterm"></a>
<a id="id617158" class="indexterm"></a>
The code for this authenticator was provided by Matthew Byng-Maddick of A L
Digital Ltd (<span class="bold"><strong><a href="http://www.aldigital.co.uk" target="_top">http://www.aldigital.co.uk</a></strong></span>).
</p>
<p>
The <span><strong class="command">cyrus_sasl</strong></span> authenticator provides server support for the Cyrus SASL
library implementation of the RFC 2222 (“<span class="quote">Simple Authentication and Security
Layer</span>”). 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.
</p>
<p>
The <span><strong class="command">cyrus_sasl</strong></span> 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 <span><strong class="command">cyrus_sasl</strong></span> authenticator. By default it uses the public
name of the driver to determine which mechanism to support.
</p>
<p>
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.
</p>
<p>
The application name provided by Exim is “<span class="quote">exim</span>”, so various SASL options may
be set in <em class="filename">exim.conf</em> 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 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.
</p>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0289" id="SECID178">36.1 Using cyrus_sasl as a server</a></h3></div>
</div>
</div>
<p>
The <span><strong class="command">cyrus_sasl</strong></span> authenticator has four private options. It puts the username
(on a successful authentication) into <em class="varname">$auth1</em>. For compatibility with
previous releases of Exim, the username is also placed in <em class="varname">$1</em>. 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.
</p>
<p>
<a id="id617275" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">server_hostname</strong></span></td><td align="center">Use: <span class="emphasis"><em>cyrus_sasl</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>see below</em></span></td></tr></tbody></table></div>
<p>
This option selects the hostname that is used when communicating with the
library. The default value is <code class="literal">$primary_hostname</code>. It is up to the underlying
SASL plug-in what it does with this data.
</p>
<p>
<a id="id617372" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">server_mech</strong></span></td><td align="center">Use: <span class="emphasis"><em>cyrus_sasl</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>see below</em></span></td></tr></tbody></table></div>
<p>
This option selects the authentication mechanism this driver should use. The
default is the value of the generic <span><strong class="option">public_name</strong></span> option. This option allows
you to use a different underlying mechanism from the advertised name. For
example:
</p>
<pre class="literallayout">sasl:
driver = cyrus_sasl
public_name = X-ANYTHING
server_mech = CRAM-MD5
server_set_id = $auth1
</pre><p>
<a id="id617474" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">server_realm</strong></span></td><td align="center">Use: <span class="emphasis"><em>cyrus_sasl</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
This specifies the SASL realm that the server claims to be in.
</p>
<p>
<a id="id617561" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">server_service</strong></span></td><td align="center">Use: <span class="emphasis"><em>cyrus_sasl</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em><code class="literal">smtp</code></em></span></td></tr></tbody></table></div>
<p>
This is the SASL service that the server claims to implement.
</p>
<p>
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:
</p>
<pre class="literallayout">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 = $auth1
</pre><p>
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.
<a id="id617670" class="indexterm"></a>
<a id="id617680" class="indexterm"></a>
</p>
</div>
</div>
<div class="navfooter">
<table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch35.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch37.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div>
</body></html>
