<!DOCTYPE html PUBLIC "XSLT-compat">
<html lang="en-GB">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="../../../../common.css">
<meta name="author" content="The Exim Project. <http://www.exim.org/>">
<meta name="copyright" content="Copyright ©2010 The Exim Project. All rights reserved">
<meta name="description" content="Exim is a message transfer agent (MTA) developed at the University of Cambridge for use on Unix systems connected to the Internet.">
<meta name="keywords" content="exim,smtp,mta,email">
<meta name="robots" content="noodp,noydir,index,follow">
<meta name="viewport" content="width=device-width">
<title>54. Support for DKIM (DomainKeys Identified Mail) - RFC4871</title>
<link rel="stylesheet" type="text/css" href="../../../../doc/chapter.css">
<link rel="canonical" href="http://www.exim.org/exim-html-current/doc/html/spec_html/ch54.html">
</head>
<body>
<h1 id="header"><a href="../../../..">Exim Internet Mailer</a></h1>
<div id="outer">
<ul id="nav_flow" class="nav">
<li><a href="../../../../index.html">Home</a></li>
<li><a href="../../../../mirrors.html">Download</a></li>
<li><a href="../../../../docs.html">Documentation</a></li>
<li><a href="../../../../maillist.html">Mailing Lists</a></li>
<li><a href="http://wiki.exim.org/">Wiki</a></li>
<li><a href="http://www.exim.org/bugzilla/">Bugs</a></li>
<li><a href="../../../../credits.html">Credits</a></li>
<li class="search"><form action="http://www.google.com/search" method="get">
<span class="search_field_container"><input type="search" name="q" placeholder="Search Docs" class="search_field"></span><input type="hidden" name="hl" value="en"><input type="hidden" name="ie" value="UTF-8"><input type="hidden" name="as_qdr" value="all"><input type="hidden" name="q" value="site:www.exim.org"><input type="hidden" name="q" value="inurl:exim-html-current">
</form></li>
</ul>
<div id="inner"><div id="content">
<a class="previous_page" href="ch53.html"><-previous</a><a class="next_page" href="ch55.html">next-></a><div id="chapter" class="chapter">
<h2 id="CHID12" class="">Chapter 54 - Support for DKIM (DomainKeys Identified Mail) - RFC4871</h2>
<p>
</p>
<p>
Since version 4.70, DKIM support is compiled into Exim by default. It can be
disabled by setting DISABLE_DKIM=yes in Local/Makefile.
</p>
<p>
Exim’s DKIM implementation allows to
</p>
<ol>
<li>
<p>
Sign outgoing messages: This function is implemented in the SMTP transport.
It can co-exist with all other Exim features, including transport filters.
</p>
</li>
<li>
<p>
Verify signatures in incoming messages: This is implemented by an additional
ACL (acl_smtp_dkim), which can be called several times per message, with
different signature contexts.
</p>
</li>
</ol>
<p>
In typical Exim style, the verification implementation does not include any
default "policy". Instead it enables you to build your own policy using
Exim’s standard controls.
</p>
<p>
Please note that verification of DKIM signatures in incoming mail is turned
on by default for logging purposes. For each signature in incoming email,
exim will log a line displaying the most important signature details, and the
signature status. Here is an example:
</p>
<div class="docbook_literallayout"><pre>
2009-09-09 10:22:28 1MlIRf-0003LU-U3 DKIM: d=facebookmail.com s=q1-2009b c=relaxed/relaxed a=rsa-sha1 i=@facebookmail.com t=1252484542 [verification succeeded]
</pre></div>
<p>
You might want to turn off DKIM verification processing entirely for internal
or relay mail sources. To do that, set the <span class="docbook_option">dkim_disable_verify</span> ACL
control modifier. This should typically be done in the RCPT ACL, at points
where you accept mail from relay sources (internal hosts or authenticated
senders).
</p>
<div class="section">
<h3 id="SECID513" class="">1. Signing outgoing messages</h3>
<p>
</p>
<p>
Signing is implemented by setting private options on the SMTP transport.
These options take (expandable) strings as arguments.
</p>
<p>
</p>
<table>
<tr>
<td><span class="docbook_option">dkim_domain</span></td>
<td>Use: <span class="docbook_emphasis">smtp</span>
</td>
<td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span>
</td>
<td>Default: <span class="docbook_emphasis">unset</span>
</td>
</tr>
</table>
<p>
MANDATORY:
The domain you want to sign with. The result of this expanded
option is put into the <span class="docbook_option">$dkim_domain</span> expansion variable.
</p>
<p>
</p>
<table>
<tr>
<td><span class="docbook_option">dkim_selector</span></td>
<td>Use: <span class="docbook_emphasis">smtp</span>
</td>
<td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span>
</td>
<td>Default: <span class="docbook_emphasis">unset</span>
</td>
</tr>
</table>
<p>
MANDATORY:
This sets the key selector string. You can use the <span class="docbook_option">$dkim_domain</span> expansion
variable to look up a matching selector. The result is put in the expansion
variable <span class="docbook_option">$dkim_selector</span> which should be used in the <span class="docbook_option">dkim_private_key</span>
option along with <span class="docbook_option">$dkim_domain</span>.
</p>
<p>
</p>
<table>
<tr>
<td><span class="docbook_option">dkim_private_key</span></td>
<td>Use: <span class="docbook_emphasis">smtp</span>
</td>
<td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span>
</td>
<td>Default: <span class="docbook_emphasis">unset</span>
</td>
</tr>
</table>
<p>
MANDATORY:
This sets the private key to use. You can use the <span class="docbook_option">$dkim_domain</span> and
<span class="docbook_option">$dkim_selector</span> expansion variables to determine the private key to use.
The result can either
</p>
<ul>
<li>
<p>
be a valid RSA private key in ASCII armor, including line breaks.
</p>
</li>
<li>
<p>
start with a slash, in which case it is treated as a file that contains
the private key.
</p>
</li>
<li>
<p>
be "0", "false" or the empty string, in which case the message will not
be signed. This case will not result in an error, even if <span class="docbook_option">dkim_strict</span>
is set.
</p>
</li>
</ul>
<p>
</p>
<table>
<tr>
<td><span class="docbook_option">dkim_canon</span></td>
<td>Use: <span class="docbook_emphasis">smtp</span>
</td>
<td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span>
</td>
<td>Default: <span class="docbook_emphasis">unset</span>
</td>
</tr>
</table>
<p>
OPTIONAL:
This option sets the canonicalization method used when signing a message.
The DKIM RFC currently supports two methods: "simple" and "relaxed".
The option defaults to "relaxed" when unset. Note: the current implementation
only supports using the same canonicalization method for both headers and body.
</p>
<p>
</p>
<table>
<tr>
<td><span class="docbook_option">dkim_strict</span></td>
<td>Use: <span class="docbook_emphasis">smtp</span>
</td>
<td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span>
</td>
<td>Default: <span class="docbook_emphasis">unset</span>
</td>
</tr>
</table>
<p>
OPTIONAL:
This option defines how Exim behaves when signing a message that
should be signed fails for some reason. When the expansion evaluates to
either "1" or "true", Exim will defer. Otherwise Exim will send the message
unsigned. You can use the <span class="docbook_option">$dkim_domain</span> and <span class="docbook_option">$dkim_selector</span> expansion
variables here.
</p>
<p>
</p>
<table>
<tr>
<td><span class="docbook_option">dkim_sign_headers</span></td>
<td>Use: <span class="docbook_emphasis">smtp</span>
</td>
<td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span>
</td>
<td>Default: <span class="docbook_emphasis">unset</span>
</td>
</tr>
</table>
<p>
OPTIONAL:
When set, this option must expand to (or be specified as) a colon-separated
list of header names. Headers with these names will be included in the message
signature. When unspecified, the header names recommended in RFC4871 will be
used.
</p>
</div>
<div class="section">
<h3 id="SECID514" class="">2. Verifying DKIM signatures in incoming mail</h3>
<p>
</p>
<p>
Verification of DKIM signatures in incoming email is implemented via the
<span class="docbook_option">acl_smtp_dkim</span> ACL. By default, this ACL is called once for each
syntactically(!) correct signature in the incoming message.
</p>
<p>
To evaluate the signature in the ACL a large number of expansion variables
containing the signature status and its details are set up during the
runtime of the ACL.
</p>
<p>
Calling the ACL only for existing signatures is not sufficient to build
more advanced policies. For that reason, the global option
<span class="docbook_option">dkim_verify_signers</span>, and a global expansion variable
<span class="docbook_option">$dkim_signers</span> exist.
</p>
<p>
The global option <span class="docbook_option">dkim_verify_signers</span> can be set to a colon-separated
list of DKIM domains or identities for which the ACL <span class="docbook_option">acl_smtp_dkim</span> is
called. It is expanded when the message has been received. At this point,
the expansion variable <span class="docbook_option">$dkim_signers</span> already contains a colon-separated
list of signer domains and identities for the message. When
<span class="docbook_option">dkim_verify_signers</span> is not specified in the main configuration,
it defaults as:
</p>
<div class="docbook_literallayout"><pre>
dkim_verify_signers = $dkim_signers
</pre></div>
<p>
This leads to the default behaviour of calling <span class="docbook_option">acl_smtp_dkim</span> for each
DKIM signature in the message. Current DKIM verifiers may want to explicitly
call the ACL for known domains or identities. This would be achieved as follows:
</p>
<div class="docbook_literallayout"><pre>
dkim_verify_signers = paypal.com:ebay.com:$dkim_signers
</pre></div>
<p>
This would result in <span class="docbook_option">acl_smtp_dkim</span> always being called for "paypal.com"
and "ebay.com", plus all domains and identities that have signatures in the message.
You can also be more creative in constructing your policy. For example:
</p>
<div class="docbook_literallayout"><pre>
dkim_verify_signers = $sender_address_domain:$dkim_signers
</pre></div>
<p>
If a domain or identity is listed several times in the (expanded) value of
<span class="docbook_option">dkim_verify_signers</span>, the ACL is only called once for that domain or identity.
</p>
<p>
Inside the <span class="docbook_option">acl_smtp_dkim</span>, the following expansion variables are
available (from most to least important):
</p>
<dl>
<dt><span class="docbook_option">$dkim_cur_signer</span></dt>
<dd>
<p>
The signer that is being evaluated in this ACL run. This can be a domain or
an identity. This is one of the list items from the expanded main option
<span class="docbook_option">dkim_verify_signers</span> (see above).
</p>
</dd>
<dt><span class="docbook_option">$dkim_verify_status</span></dt>
<dd>
<p>
A string describing the general status of the signature. One of
</p>
<ul>
<li>
<p>
<span class="docbook_option">none</span>: There is no signature in the message for the current domain or
identity (as reflected by <span class="docbook_option">$dkim_cur_signer</span>).
</p>
</li>
<li>
<p>
<span class="docbook_option">invalid</span>: The signature could not be verified due to a processing error.
More detail is available in <span class="docbook_option">$dkim_verify_reason</span>.
</p>
</li>
<li>
<p>
<span class="docbook_option">fail</span>: Verification of the signature failed. More detail is
available in <span class="docbook_option">$dkim_verify_reason</span>.
</p>
</li>
<li>
<p>
<span class="docbook_option">pass</span>: The signature passed verification. It is valid.
</p>
</li>
</ul>
</dd>
<dt><span class="docbook_option">$dkim_verify_reason</span></dt>
<dd>
<p>
A string giving a litte bit more detail when <span class="docbook_option">$dkim_verify_status</span> is either
"fail" or "invalid". One of
</p>
<ul>
<li>
<p>
<span class="docbook_option">pubkey_unavailable</span> (when <span class="docbook_option">$dkim_verify_status</span>="invalid"): The public
key for the domain could not be retrieved. This may be a temporary problem.
</p>
</li>
<li>
<p>
<span class="docbook_option">pubkey_syntax</span> (when <span class="docbook_option">$dkim_verify_status</span>="invalid"): The public key
record for the domain is syntactically invalid.
</p>
</li>
<li>
<p>
<span class="docbook_option">bodyhash_mismatch</span> (when <span class="docbook_option">$dkim_verify_status</span>="fail"): The calculated
body hash does not match the one specified in the signature header. This
means that the message body was modified in transit.
</p>
</li>
<li>
<p>
<span class="docbook_option">signature_incorrect</span> (when <span class="docbook_option">$dkim_verify_status</span>="fail"): The signature
could not be verified. This may mean that headers were modified,
re-written or otherwise changed in a way which is incompatible with
DKIM verification. It may of course also mean that the signature is forged.
</p>
</li>
</ul>
</dd>
<dt><span class="docbook_option">$dkim_domain</span></dt>
<dd>
<p>
The signing domain. IMPORTANT: This variable is only populated if there is
an actual signature in the message for the current domain or identity (as
reflected by <span class="docbook_option">$dkim_cur_signer</span>).
</p>
</dd>
<dt><span class="docbook_option">$dkim_identity</span></dt>
<dd>
<p>
The signing identity, if present. IMPORTANT: This variable is only populated
if there is an actual signature in the message for the current domain or
identity (as reflected by <span class="docbook_option">$dkim_cur_signer</span>).
</p>
</dd>
<dt><span class="docbook_option">$dkim_selector</span></dt>
<dd>
<p>
The key record selector string.
</p>
</dd>
<dt><span class="docbook_option">$dkim_algo</span></dt>
<dd>
<p>
The algorithm used. One of ’rsa-sha1’ or ’rsa-sha256’.
</p>
</dd>
<dt><span class="docbook_option">$dkim_canon_body</span></dt>
<dd>
<p>
The body canonicalization method. One of ’relaxed’ or ’simple’.
</p>
</dd>
<dt><span class="docbook_option">dkim_canon_headers</span></dt>
<dd>
<p>
The header canonicalization method. One of ’relaxed’ or ’simple’.
</p>
</dd>
<dt><span class="docbook_option">$dkim_copiedheaders</span></dt>
<dd>
<p>
A transcript of headers and their values which are included in the signature
(copied from the ’z=’ tag of the signature).
</p>
</dd>
<dt><span class="docbook_option">$dkim_bodylength</span></dt>
<dd>
<p>
The number of signed body bytes. If zero ("0"), the body is unsigned. If no
limit was set by the signer, "9999999999999" is returned. This makes sure
that this variable always expands to an integer value.
</p>
</dd>
<dt><span class="docbook_option">$dkim_created</span></dt>
<dd>
<p>
UNIX timestamp reflecting the date and time when the signature was created.
When this was not specified by the signer, "0" is returned.
</p>
</dd>
<dt><span class="docbook_option">$dkim_expires</span></dt>
<dd>
<p>
UNIX timestamp reflecting the date and time when the signer wants the
signature to be treated as "expired". When this was not specified by the
signer, "9999999999999" is returned. This makes it possible to do useful
integer size comparisons against this value.
</p>
</dd>
<dt><span class="docbook_option">$dkim_headernames</span></dt>
<dd>
<p>
A colon-separated list of names of headers included in the signature.
</p>
</dd>
<dt><span class="docbook_option">$dkim_key_testing</span></dt>
<dd>
<p>
"1" if the key record has the "testing" flag set, "0" if not.
</p>
</dd>
<dt><span class="docbook_option">$dkim_key_nosubdomaining</span></dt>
<dd>
<p>
"1" if the key record forbids subdomaining, "0" otherwise.
</p>
</dd>
<dt><span class="docbook_option">$dkim_key_srvtype</span></dt>
<dd>
<p>
Service type (tag s=) from the key record. Defaults to "*" if not specified
in the key record.
</p>
</dd>
<dt><span class="docbook_option">$dkim_key_granularity</span></dt>
<dd>
<p>
Key granularity (tag g=) from the key record. Defaults to "*" if not specified
in the key record.
</p>
</dd>
<dt><span class="docbook_option">$dkim_key_notes</span></dt>
<dd>
<p>
Notes from the key record (tag n=).
</p>
</dd>
</dl>
<p>
In addition, two ACL conditions are provided:
</p>
<dl>
<dt><span class="docbook_option">dkim_signers</span></dt>
<dd>
<p>
ACL condition that checks a colon-separated list of domains or identities
for a match against the domain or identity that the ACL is currently verifying
(reflected by <span class="docbook_option">$dkim_cur_signer</span>). This is typically used to restrict an ACL
verb to a group of domains or identities. For example:
</p>
<div class="docbook_literallayout"><pre>
# Warn when message apparently from GMail has no signature at all
warn log_message = GMail sender without DKIM signature
sender_domains = gmail.com
dkim_signers = gmail.com
dkim_status = none
</pre></div>
</dd>
<dt><span class="docbook_option">dkim_status</span></dt>
<dd>
<p>
ACL condition that checks a colon-separated list of possible DKIM verification
results agains the actual result of verification. This is typically used
to restrict an ACL verb to a list of verification outcomes, like:
</p>
<div class="docbook_literallayout"><pre>
deny message = Message from Paypal with invalid or missing signature
sender_domains = paypal.com:paypal.de
dkim_signers = paypal.com:paypal.de
dkim_status = none:invalid:fail
</pre></div>
<p>
The possible status keywords are: ’none’,’invalid’,’fail’ and ’pass’. Please
see the documentation of the <span class="docbook_option">$dkim_verify_status</span> expansion variable above
for more information of what they mean.
</p>
</dd>
</dl>
</div>
</div>
<a class="previous_page" href="ch53.html"><-previous</a><a class="next_page" href="ch55.html">next-></a>
</div></div>
<iframe id="branding" name="branding" src="../../../../branding/branding.html" height="0" frameborder="no" scrolling="no"></iframe><div id="footer">Website design by <a href="https://secure.grepular.com/">Mike Cardwell</a>, of <a href="http://cardwellit.com/">Cardwell IT Ltd.</a>
</div>
<div class="left_bar"></div>
<div class="right_bar"></div>
<div id="toc">
<ul class="hidden"></ul>
<img src="../../../../doc/contents.png" width="16" height="155">
</div>
</div>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script><script type="text/javascript" src="../../../../common.js"></script><script type="text/javascript" src="../../../../doc/chapter.js"></script>
</body>
</html>
