# Exim Internet Mailer

<-previous next->

## Chapter 57 - Support for DKIM (DomainKeys Identified Mail)

DKIM is a mechanism by which messages sent by some entity can be provably linked to a domain which that entity controls. It permits reputation to be tracked on a per-domain basis, rather than merely upon source IP address. DKIM is documented in RFC 4871.

DKIM support is compiled into Exim by default if TLS support is present. It can be disabled by setting DISABLE_DKIM=yes in Local/Makefile.

Exim’s DKIM implementation allows for

1. Signing outgoing messages: This function is implemented in the SMTP transport. It can co-exist with all other Exim features (including transport filters) except cutthrough delivery.

2. Verifying 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.

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.

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 (with line-breaks added for clarity):

    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]

You might want to turn off DKIM verification processing entirely for internal or relay mail sources. To do that, set the dkim_disable_verify 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).

### 1. Signing outgoing messages

Signing is enabled by setting private options on the SMTP transport. These options take (expandable) strings as arguments.

dkim_domain | Use: smtp | Type: string | Default: list†

The domain(s) you want to sign with.

After expansion, this can be a list. Each element in turn is put into the $dkim_domain expansion variable while expanding the remaining signing options.

If it is empty after expansion, DKIM signing is not done.

dkim_selector | Use: smtp | Type: string | Default: list†

This sets the key selector string.

After expansion, which can use $dkim_domain, this can be a list. Each element in turn is put in the expansion variable $dkim_selector which may be used in the dkim_private_key option along with $dkim_domain. If the option is empty after expansion, DKIM signing is not done for this domain.

dkim_private_key | Use: smtp | Type: string† | Default: unset

This sets the private key to use. You can use the $dkim_domain and $dkim_selector expansion variables to determine the private key to use. The result can either

- be a valid RSA private key in ASCII armor, including line breaks.

- start with a slash, in which case it is treated as a file that contains the private key.

- 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 dkim_strict is set.

If the option is empty after expansion, DKIM signing is not done.

dkim_hash | Use: smtp | Type: string† | Default: sha256

Can be set alternatively to “sha1” to use an alternate hash method. Note that sha1 is now condidered insecure, and deprecated.

dkim_identity | Use: smtp | Type: string† | Default: unset

If set after expansion, the value is used to set an "i=" tag in the signing header. The DKIM standards restrict the permissible syntax of this optional tag to a mail address, with possibly-empty local part, an @, and a domain identical to or subdomain of the "d=" tag value. Note that Exim does not check the value.

dkim_canon | Use: smtp | Type: string† | Default: unset

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.

dkim_strict | Use: smtp | Type: string† | Default: unset

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 $dkim_domain and $dkim_selector expansion variables here.

dkim_sign_headers | Use: smtp | Type: string† | Default: see below

If set, this option must expand to a colon-separated list of header names.

Headers with these names, or the absence or such a header, will be included in the message signature. When unspecified, the header names listed in RFC4871 will be used, whether or not each header is present in the message. The default list is available for the expansion in the macro "_DKIM_SIGN_HEADERS".

If a name is repeated, multiple headers by that name (or the absence therof) will be signed. The textually later headers in the headers part of the message are signed first, if there are multiples.

A name can be prefixed with either an ’=’ or a ’+’ character. If an ’=’ prefix is used, all headers that are present with this name will be signed. If a ’+’ prefix if used, all headers that are present with this name will be signed, and one signtature added for a missing header with the name will be appended.

### 2. Verifying DKIM signatures in incoming mail

Verification of DKIM signatures in SMTP incoming email is implemented via the acl_smtp_dkim ACL. By default, this ACL is called once for each syntactically(!) correct signature in the incoming message. A missing ACL definition defaults to accept. If any ACL call does not accept, the message is not accepted. If a cutthrough delivery was in progress for the message, that is summarily dropped (having wasted the transmission effort).

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.

Calling the ACL only for existing signatures is not sufficient to build more advanced policies. For that reason, the global option dkim_verify_signers, and a global expansion variable $dkim_signers exist.

The global option dkim_verify_signers can be set to a colon-separated list of DKIM domains or identities for which the ACL acl_smtp_dkim is called. It is expanded when the message has been received. At this point, the expansion variable $dkim_signers already contains a colon-separated list of signer domains and identities for the message. When dkim_verify_signers is not specified in the main configuration, it defaults as:

    dkim_verify_signers = $dkim_signers

This leads to the default behaviour of calling acl_smtp_dkim 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:

    dkim_verify_signers = paypal.com:ebay.com:$dkim_signers

This would result in acl_smtp_dkim 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:

    dkim_verify_signers = $sender_address_domain:$dkim_signers

If a domain or identity is listed several times in the (expanded) value of dkim_verify_signers, the ACL is only called once for that domain or identity.

If multiple signatures match a domain (or identity), the ACL is called once for each matching signature.

Inside the acl_smtp_dkim, the following expansion variables are available (from most to least important):

$dkim_cur_signer

  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 dkim_verify_signers (see above).

$dkim_verify_status

  Within the DKIM ACL, a string describing the general status of the signature. One of

  - none: There is no signature in the message for the current domain or identity (as reflected by $dkim_cur_signer).

  - invalid: The signature could not be verified due to a processing error. More detail is available in $dkim_verify_reason.

  - fail: Verification of the signature failed. More detail is available in $dkim_verify_reason.

  - pass: The signature passed verification. It is valid.

  This variable can be overwritten using an ACL ’set’ modifier. This might, for instance, be done to enforce a policy restriction on hash-method or key-size:

        warn	condition =	${if eq {$dkim_algo}{rsa-sha1}}
      	condition =	${if eq {$dkim_verify_status}{pass}}
      	logwrite =	NOTE: forcing dkim verify fail (was pass)
      	set dkim_verify_status = fail
      	set dkim_verify_reason = hash too weak

  After all the DKIM ACL runs have completed, the value becomes a colon-separated list of the values after each run.

$dkim_verify_reason

  A string giving a little bit more detail when $dkim_verify_status is either "fail" or "invalid". One of

  - pubkey_unavailable (when $dkim_verify_status="invalid"): The public key for the domain could not be retrieved. This may be a temporary problem.

  - pubkey_syntax (when $dkim_verify_status="invalid"): The public key record for the domain is syntactically invalid.

  - bodyhash_mismatch (when $dkim_verify_status="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.

  - signature_incorrect (when $dkim_verify_status="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.

  This variable can be overwritten using an ACL ’set’ modifier.

$dkim_domain

  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 $dkim_cur_signer).

$dkim_identity

  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 $dkim_cur_signer).

$dkim_selector

  The key record selector string.

$dkim_algo

  The algorithm used. One of ’rsa-sha1’ or ’rsa-sha256’.

$dkim_canon_body

  The body canonicalization method. One of ’relaxed’ or ’simple’.

$dkim_canon_headers

  The header canonicalization method. One of ’relaxed’ or ’simple’.

$dkim_copiedheaders

  A transcript of headers and their values which are included in the signature (copied from the ’z=’ tag of the signature). Note that RFC6376 requires that verification fail if the From: header is not included in the signature. Exim does not enforce this; sites wishing strict enforcement should code the check explicitly.

$dkim_bodylength

  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.

$dkim_created

  UNIX timestamp reflecting the date and time when the signature was created. When this was not specified by the signer, "0" is returned.

$dkim_expires

  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.

$dkim_headernames

  A colon-separated list of names of headers included in the signature.

$dkim_key_testing

  "1" if the key record has the "testing" flag set, "0" if not.

$dkim_key_nosubdomains

  "1" if the key record forbids subdomaining, "0" otherwise.

$dkim_key_srvtype

  Service type (tag s=) from the key record. Defaults to "*" if not specified in the key record.

$dkim_key_granularity

  Key granularity (tag g=) from the key record. Defaults to "*" if not specified in the key record.

$dkim_key_notes

  Notes from the key record (tag n=).

$dkim_key_length

  Number of bits in the key.

In addition, two ACL conditions are provided:

dkim_signers

  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 $dkim_cur_signer). This is typically used to restrict an ACL verb to a group of domains or identities. For example:

      # Warn when Mail purportedly from GMail has no gmail signature
      warn log_message = GMail sender without gmail.com DKIM signature
           sender_domains = gmail.com
           dkim_signers = gmail.com
           dkim_status = none

  Note that the above does not check for a total lack of DKIM signing; for that check for empty $h_DKIM-Signature: in the data ACL.

dkim_status

  ACL condition that checks a colon-separated list of possible DKIM verification results against the actual result of verification. This is typically used to restrict an ACL verb to a list of verification outcomes, for example:

      deny message = Mail from Paypal with invalid/missing signature
           sender_domains = paypal.com:paypal.de
           dkim_signers = paypal.com:paypal.de
           dkim_status = none:invalid:fail

  The possible status keywords are: ’none’,’invalid’,’fail’ and ’pass’. Please see the documentation of the $dkim_verify_status expansion variable above for more information of what they mean.

<-previous Table of Contents next->