<?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>34. The plaintext 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="ch33.html" title="33. SMTP authentication" /><link rel="next" href="ch35.html" title="35. The cram_md5 authenticator" /></head><body><div class="navheader">
<table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch33.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch35.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#toc0278" id="CHAPplaintext">34. The plaintext authenticator</a></h2></div>
</div>
</div>
<p>
<a id="IIDplaiauth1" class="indexterm"></a>
<a id="IIDplaiauth2" class="indexterm"></a>
The <span><strong class="command">plaintext</strong></span> authenticator can be configured to support the PLAIN and
LOGIN authentication mechanisms, both of which transfer authentication data as
plain (unencrypted) text (though base64 encoded). The use of plain text is a
security risk; you are strongly advised to insist on the use of SMTP encryption
(see chapter <a href="ch39.html" title="39. Encrypted SMTP connections using TLS/SSL">39</a>) if you use the PLAIN or LOGIN mechanisms. If you do
use unencrypted plain text, you should not use the same passwords for SMTP
connections as you do for login accounts.
</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#toc0279" id="SECID171">34.1 Plaintext options</a></h3></div>
</div>
</div>
<p>
<a id="id615201" class="indexterm"></a>
When configured as a server, <span><strong class="command">plaintext</strong></span> uses the following options:
</p>
<p>
<a id="id615229" 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_condition</strong></span></td><td align="center">Use: <span class="emphasis"><em>authenticators</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>unset</em></span></td></tr></tbody></table></div>
<p>
This is actually a global authentication option, but it must be set in order to
configure the <span><strong class="command">plaintext</strong></span> driver as a server. Its use is described below.
</p>
<p>
<a id="id615326" 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_prompts</strong></span></td><td align="center">Use: <span class="emphasis"><em>plaintext</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>unset</em></span></td></tr></tbody></table></div>
<p>
The contents of this option, after expansion, must be a colon-separated list of
prompt strings. If expansion fails, a temporary authentication rejection is
given.
</p>
</div>
<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#toc0280" id="SECTplainserver">34.2 Using plaintext in a server</a></h3></div>
</div>
</div>
<p>
<a id="id615427" class="indexterm"></a>
<a id="id615446" class="indexterm"></a>
<a id="id615466" class="indexterm"></a>
<a id="id615493" class="indexterm"></a>
<a id="id615510" class="indexterm"></a>
</p>
<p>
When running as a server, <span><strong class="command">plaintext</strong></span> performs the authentication test by
expanding a string. The data sent by the client with the AUTH command, or in
response to subsequent prompts, is base64 encoded, and so may contain any byte
values when decoded. If any data is supplied with the command, it is treated as
a list of strings, separated by NULs (binary zeros), the first three of which
are placed in the expansion variables <em class="varname">$auth1</em>, <em class="varname">$auth2</em>, and <em class="varname">$auth3</em>
(neither LOGIN nor PLAIN uses more than three strings).
</p>
<p>
For compatibility with previous releases of Exim, the values are also placed in
the expansion variables <em class="varname">$1</em>, <em class="varname">$2</em>, and <em class="varname">$3</em>. However, the use of these
variables for this purpose is now deprecated, as it can lead to confusion in
string expansions that also use them for other things.
</p>
<p>
If there are more strings in <span><strong class="option">server_prompts</strong></span> than the number of strings
supplied with the AUTH command, the remaining prompts are used to obtain more
data. Each response from the client may be a list of NUL-separated strings.
</p>
<p>
<a id="id615589" class="indexterm"></a>
Once a sufficient number of data strings have been received,
<span><strong class="option">server_condition</strong></span> is expanded. If the expansion is forced to fail,
authentication fails. Any other expansion failure causes a temporary error code
to be returned. If the result of a successful expansion is an empty string,
“<span class="quote">0</span>”, “<span class="quote">no</span>”, or “<span class="quote">false</span>”, authentication fails. If the result of the
expansion is “<span class="quote">1</span>”, “<span class="quote">yes</span>”, or “<span class="quote">true</span>”, authentication succeeds and the
generic <span><strong class="option">server_set_id</strong></span> option is expanded and saved in <em class="varname">$authenticated_id</em>.
For any other result, a temporary error code is returned, with the expanded
string as the error text.
</p>
<p>
<span class="bold"><strong>Warning</strong></span>: If you use a lookup in the expansion to find the user’s
password, be sure to make the authentication fail if the user is unknown.
There are good and bad examples at the end of the next section.
</p>
</div>
<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#toc0281" id="SECID172">34.3 The PLAIN authentication mechanism</a></h3></div>
</div>
</div>
<p>
<a id="id615665" class="indexterm"></a>
<a id="id615676" class="indexterm"></a>
<a id="id615690" class="indexterm"></a>
The PLAIN authentication mechanism (RFC 2595) specifies that three strings be
sent as one item of data (that is, one combined string containing two NUL
separators). The data is sent either as part of the AUTH command, or
subsequently in response to an empty prompt from the server.
</p>
<p>
The second and third strings are a user name and a corresponding password.
Using a single fixed user name and password as an example, this could be
configured as follows:
</p>
<pre class="literallayout">fixed_plain:
driver = plaintext
public_name = PLAIN
server_prompts = :
server_condition = \
${if and {{eq{$auth2}{username}}{eq{$auth3}{mysecret}}}}
server_set_id = $auth2
</pre><p>
Note that the default result strings from <span><strong class="option">if</strong></span> (“<span class="quote">true</span>” or an empty string)
are exactly what we want here, so they need not be specified. Obviously, if the
password contains expansion-significant characters such as dollar, backslash,
or closing brace, they have to be escaped.
</p>
<p>
The <span><strong class="option">server_prompts</strong></span> setting specifies a single, empty prompt (empty items at
the end of a string list are ignored). If all the data comes as part of the
AUTH command, as is commonly the case, the prompt is not used. This
authenticator is advertised in the response to EHLO as
</p>
<pre class="literallayout">250-AUTH PLAIN
</pre><p>
and a client host can authenticate itself by sending the command
</p>
<pre class="literallayout">AUTH PLAIN AHVzZXJuYW1lAG15c2VjcmV0
</pre><p>
As this contains three strings (more than the number of prompts), no further
data is required from the client. Alternatively, the client may just send
</p>
<pre class="literallayout">AUTH PLAIN
</pre><p>
to initiate authentication, in which case the server replies with an empty
prompt. The client must respond with the combined data string.
</p>
<p>
The data string is base64 encoded, as required by the RFC. This example,
when decoded, is <<span class="emphasis"><em>NUL</em></span>><code class="literal">username</code><<span class="emphasis"><em>NUL</em></span>><code class="literal">mysecret</code>, where <<span class="emphasis"><em>NUL</em></span>>
represents a zero byte. This is split up into three strings, the first of which
is empty. The <span><strong class="option">server_condition</strong></span> option in the authenticator checks that the
second two are <code class="literal">username</code> and <code class="literal">mysecret</code> respectively.
</p>
<p>
Having just one fixed user name and password, as in this example, is not very
realistic, though for a small organization with only a handful of
authenticating clients it could make sense.
</p>
<p>
A more sophisticated instance of this authenticator could use the user name in
<em class="varname">$auth2</em> to look up a password in a file or database, and maybe do an encrypted
comparison (see <span><strong class="option">crypteq</strong></span> in chapter <a href="ch11.html" title="11. String expansions">11</a>). Here is a example of
this approach, where the passwords are looked up in a DBM file. <span class="bold"><strong>Warning</strong></span>:
This is an incorrect example:
</p>
<pre class="literallayout">server_condition = \
${if eq{$auth3}{${lookup{$auth2}dbm{/etc/authpwd}}}}
</pre><p>
The expansion uses the user name (<em class="varname">$auth2</em>) as the key to look up a password,
which it then compares to the supplied password (<em class="varname">$auth3</em>). Why is this example
incorrect? It works fine for existing users, but consider what happens if a
non-existent user name is given. The lookup fails, but as no success/failure
strings are given for the lookup, it yields an empty string. Thus, to defeat
the authentication, all a client has to do is to supply a non-existent user
name and an empty password. The correct way of writing this test is:
</p>
<pre class="literallayout">server_condition = ${lookup{$auth2}dbm{/etc/authpwd}\
{${if eq{$value}{$auth3}}} {false}}
</pre><p>
In this case, if the lookup succeeds, the result is checked; if the lookup
fails, “<span class="quote">false</span>” is returned and authentication fails. If <span><strong class="option">crypteq</strong></span> is being
used instead of <span><strong class="option">eq</strong></span>, the first example is in fact safe, because <span><strong class="option">crypteq</strong></span>
always fails if its second argument is empty. However, the second way of
writing the test makes the logic clearer.
</p>
</div>
<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#toc0282" id="SECID173">34.4 The LOGIN authentication mechanism</a></h3></div>
</div>
</div>
<p>
<a id="id615953" class="indexterm"></a>
<a id="id615964" class="indexterm"></a>
The LOGIN authentication mechanism is not documented in any RFC, but is in use
in a number of programs. No data is sent with the AUTH command. Instead, a
user name and password are supplied separately, in response to prompts. The
plaintext authenticator can be configured to support this as in this example:
</p>
<pre class="literallayout">fixed_login:
driver = plaintext
public_name = LOGIN
server_prompts = User Name : Password
server_condition = \
${if and {{eq{$auth1}{username}}{eq{$auth2}{mysecret}}}}
server_set_id = $auth1
</pre><p>
Because of the way plaintext operates, this authenticator accepts data supplied
with the AUTH command (in contravention of the specification of LOGIN), but
if the client does not supply it (as is the case for LOGIN clients), the prompt
strings are used to obtain two data items.
</p>
<p>
Some clients are very particular about the precise text of the prompts. For
example, Outlook Express is reported to recognize only “<span class="quote">Username:</span>” and
“<span class="quote">Password:</span>”. Here is an example of a LOGIN authenticator that uses those
strings. It uses the <span><strong class="option">ldapauth</strong></span> expansion condition to check the user
name and password by binding to an LDAP server:
</p>
<pre class="literallayout">login:
driver = plaintext
public_name = LOGIN
server_prompts = Username:: : Password::
server_condition = ${if ldapauth \
{user="cn=${quote_ldap_dn:$auth1},ou=people,o=example.org" \
pass=${quote:$auth2} \
ldap://ldap.example.org/}}
server_set_id = uid=$auth1,ou=people,o=example.org
</pre><p>
Note the use of the <span><strong class="option">quote_ldap_dn</strong></span> operator to correctly quote the DN for
authentication. However, the basic <span><strong class="option">quote</strong></span> operator, rather than any of the
LDAP quoting operators, is the correct one to use for the password, because
quoting is needed only to make the password conform to the Exim syntax. At the
LDAP level, the password is an uninterpreted string.
</p>
</div>
<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#toc0283" id="SECID174">34.5 Support for different kinds of authentication</a></h3></div>
</div>
</div>
<p>
A number of string expansion features are provided for the purpose of
interfacing to different ways of user authentication. These include checking
traditionally encrypted passwords from <em class="filename">/etc/passwd</em> (or equivalent), PAM,
Radius, <span><strong class="option">ldapauth</strong></span>, <span class="emphasis"><em>pwcheck</em></span>, and <span class="emphasis"><em>saslauthd</em></span>. For details see section
<a href="ch11.html#SECTexpcond" title="11.7 Expansion conditions">11.7</a>.
</p>
</div>
<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#toc0284" id="SECID175">34.6 Using plaintext in a client</a></h3></div>
</div>
</div>
<p>
<a id="id616105" class="indexterm"></a>
The <span><strong class="command">plaintext</strong></span> authenticator has two client options:
</p>
<p>
<a id="id616134" 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">client_ignore_invalid_base64</strong></span></td><td align="center">Use: <span class="emphasis"><em>plaintext</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
If the client receives a server prompt that is not a valid base64 string,
authentication is abandoned by default. However, if this option is set true,
the error in the challenge is ignored and the client sends the response as
usual.
</p>
<p>
<a id="id616224" 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">client_send</strong></span></td><td align="center">Use: <span class="emphasis"><em>plaintext</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>unset</em></span></td></tr></tbody></table></div>
<p>
The string is a colon-separated list of authentication data strings. Each
string is independently expanded before being sent to the server. The first
string is sent with the AUTH command; any more strings are sent in response
to prompts from the server. Before each string is expanded, the value of the
most recent prompt is placed in the next <em class="varname">$auth</em><<span class="emphasis"><em>n</em></span>> variable, starting
with <em class="varname">$auth1</em> for the first prompt. Up to three prompts are stored in this
way. Thus, the prompt that is received in response to sending the first string
(with the AUTH command) can be used in the expansion of the second string, and
so on. If an invalid base64 string is received when
<span><strong class="option">client_ignore_invalid_base64</strong></span> is set, an empty string is put in the
<em class="varname">$auth</em><<span class="emphasis"><em>n</em></span>> variable.
</p>
<p>
<span class="bold"><strong>Note</strong></span>: You cannot use expansion to create multiple strings, because
splitting takes priority and happens first.
</p>
<p>
Because the PLAIN authentication mechanism requires NUL (binary zero) bytes in
the data, further processing is applied to each string before it is sent. If
there are any single circumflex characters in the string, they are converted to
NULs. Should an actual circumflex be required as data, it must be doubled in
the string.
</p>
<p>
This is an example of a client configuration that implements the PLAIN
authentication mechanism with a fixed user name and password:
</p>
<pre class="literallayout">fixed_plain:
driver = plaintext
public_name = PLAIN
client_send = ^username^mysecret
</pre><p>
The lack of colons means that the entire text is sent with the AUTH
command, with the circumflex characters converted to NULs. A similar example
that uses the LOGIN mechanism is:
</p>
<pre class="literallayout">fixed_login:
driver = plaintext
public_name = LOGIN
client_send = : username : mysecret
</pre><p>
The initial colon means that the first string is empty, so no data is sent with
the AUTH command itself. The remaining strings are sent in response to
prompts.
<a id="id616398" class="indexterm"></a>
<a id="id616410" 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="ch33.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch35.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>
