<?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>35. The cram_md5 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="ch34.html" title="34. The plaintext authenticator" /><link rel="next" href="ch36.html" title="36. The cyrus_sasl authenticator" /></head><body><div class="navheader"> <table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch34.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch36.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#toc0285" id="CHID9">35. The cram_md5 authenticator</a></h2></div> </div> </div> <p> <a id="IIDcramauth1" class="indexterm"></a> <a id="IIDcramauth2" class="indexterm"></a> <a id="id616482" class="indexterm"></a> <a id="id616493" class="indexterm"></a> The CRAM-MD5 authentication mechanism is described in RFC 2195. The server sends a challenge string to the client, and the response consists of a user name and the CRAM-MD5 digest of the challenge string combined with a secret string (password) which is known to both server and client. Thus, the secret is not sent over the network as plain text, which makes this authenticator more secure than <span><strong class="command">plaintext</strong></span>. However, the downside is that the secret has to be available in plain text at either end. </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#toc0286" id="SECID176">35.1 Using cram_md5 as a server</a></h3></div> </div> </div> <p> <a id="id616535" class="indexterm"></a> This authenticator has one server option, which must be set to configure the authenticator as a server: </p> <p> <a id="id616559" 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_secret</strong></span></td><td align="center">Use: <span class="emphasis"><em>cram_md5</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> <a id="id616644" class="indexterm"></a> When the server receives the client’s response, the user name is placed in the expansion variable <em class="varname">$auth1</em>, and <span><strong class="option">server_secret</strong></span> is expanded to obtain the password for that user. The server then computes the CRAM-MD5 digest that the client should have sent, and checks that it received the correct string. If the expansion of <span><strong class="option">server_secret</strong></span> is forced to fail, authentication fails. If the expansion fails for some other reason, a temporary error code is returned to the client. </p> <p> For compatibility with previous releases of Exim, the user name is also placed in <em class="varname">$1</em>. However, the use of this variables 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> For example, the following authenticator checks that the user name given by the client is “<span class="quote">ph10</span>”, and if so, uses “<span class="quote">secret</span>” as the password. For any other user name, authentication fails. </p> <pre class="literallayout">fixed_cram: driver = cram_md5 public_name = CRAM-MD5 server_secret = ${if eq{$auth1}{ph10}{secret}fail} server_set_id = $auth1 </pre><p> <a id="id616729" class="indexterm"></a> If authentication succeeds, the setting of <span><strong class="option">server_set_id</strong></span> preserves the user name in <em class="varname">$authenticated_id</em>. A more typical configuration might look up the secret string in a file, using the user name as the key. For example: </p> <pre class="literallayout">lookup_cram: driver = cram_md5 public_name = CRAM-MD5 server_secret = ${lookup{$auth1}lsearch{/etc/authpwd}\ {$value}fail} server_set_id = $auth1 </pre><p> Note that this expansion explicitly forces failure if the lookup fails because <em class="varname">$auth1</em> contains an unknown user name. </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#toc0287" id="SECID177">35.2 Using cram_md5 as a client</a></h3></div> </div> </div> <p> <a id="id616786" class="indexterm"></a> When used as a client, the <span><strong class="command">cram_md5</strong></span> authenticator has two options: </p> <p> <a id="id616815" 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_name</strong></span></td><td align="center">Use: <span class="emphasis"><em>cram_md5</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>the primary host name</em></span></td></tr></tbody></table></div> <p> This string is expanded, and the result used as the user name data when computing the response to the server’s challenge. </p> <p> <a id="id616909" 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_secret</strong></span></td><td align="center">Use: <span class="emphasis"><em>cram_md5</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 option must be set for the authenticator to work as a client. Its value is expanded and the result used as the secret string when computing the response. </p> <p> <a id="id617000" class="indexterm"></a> <a id="id617012" class="indexterm"></a> Different user names and secrets can be used for different servers by referring to <em class="varname">$host</em> or <em class="varname">$host_address</em> in the options. Forced failure of either expansion string is treated as an indication that this authenticator is not prepared to handle this case. Exim moves on to the next configured client authenticator. Any other expansion failure causes Exim to give up trying to send the message to the current server. </p> <p> A simple example configuration of a <span><strong class="command">cram_md5</strong></span> authenticator, using fixed strings, is: </p> <pre class="literallayout">fixed_cram: driver = cram_md5 public_name = CRAM-MD5 client_name = ph10 client_secret = secret </pre><p> <a id="id617059" class="indexterm"></a> <a id="id617071" 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="ch34.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch36.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>