Exim Internet Mailer

1. 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 6376.

As DKIM relies on the message being unchanged in transit, messages handled by a mailing-list (which traditionally adds to the message) will not match any original DKIM signature.

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 (in the <= line) purposes.

Additional log detail can be enabled using the dkim_verbose log_selector. When set, 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).

2. Signing outgoing messages

For signing to be usable you must have published a DKIM record in DNS. Note that RFC 8301 says:

rsa-sha1 MUST NOT be used for signing or verifying.

Signers MUST use RSA keys of at least 1024 bits for all keys.
Signers SHOULD use RSA keys of at least 2048 bits.

Note also that the key content (the ’p=’ field) in the DNS record is different between RSA and EC keys; for the former it is the base64 of the ASN.1 for the RSA public key (equivalent to the private-key .pem with the header/trailer stripped) but for EC keys it is the base64 of the pure key; no ASN.1 wrapping.

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

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, and no error will result even if dkim_strict is set.

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, and no error will result even if dkim_strict is set.

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 (.pem file), including line breaks

• with GnuTLS 3.6.0 or OpenSSL 1.1.1 or later, be a valid Ed25519 private key (same format as above)

• 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.

To generate keys under OpenSSL:

openssl genrsa -out dkim_rsa.private 2048
openssl rsa -in dkim_rsa.private -out /dev/stdout -pubout -outform PEM

Take the base-64 lines from the output of the second command, concatenated, for the DNS TXT record. See section 3.6 of RFC6376 for the record specification.

Under GnuTLS:

certtool --generate-privkey --rsa --bits=2048 --password='' -8 --outfile=dkim_rsa.private
certtool --load-privkey=dkim_rsa.private --pubkey-info

Note that RFC 8301 says:

Signers MUST use RSA keys of at least 1024 bits for all keys.
Signers SHOULD use RSA keys of at least 2048 bits.

Support for EC keys is being developed under https://datatracker.ietf.org/doc/draft-ietf-dcrup-dkim-crypto/. They are considerably smaller than RSA keys for equivalent protection. As they are a recent development, users should consider dual-signing (by setting a list of selectors, and an expansion for this option) for some transition period. The "_CRYPTO_SIGN_ED25519" macro will be defined if support is present for EC keys.

OpenSSL 1.1.1 and GnuTLS 3.6.0 can create Ed25519 private keys:

openssl genpkey -algorithm ed25519 -out dkim_ed25519.private
certtool --generate-privkey --key-type=ed25519 --outfile=dkim_ed25519.private

To produce the required public key value for a DNS record:

openssl pkey -outform DER -pubout -in dkim_ed25519.private | tail -c +13 | base64
certtool --load_privkey=dkim_ed25519.private --pubkey_info --outder | tail -c +13 | base64

Note that the format of Ed25519 keys in DNS has not yet been decided; this release supports both of the leading candidates at this time, a future release will probably drop support for whichever proposal loses.

Can be set to any one of the supported hash methods, which are:

• sha1 – should not be used, is old and insecure

• sha256 – the default

• sha512 – possibly more secure but less well supported

Note that RFC 8301 says:

rsa-sha1 MUST NOT be used for signing or verifying.

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.

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.

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.

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 thereof) 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 signature added for a missing header with the name will be appended.

3. 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.

Performing verification sets up information used by the $authresults expansion item.

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_verify_status}{pass}}
       condition       = ${if eq {${length_3:$dkim_algo}}{rsa}}
       condition       = ${if or {{eq {$dkim_algo}{rsa-sha1}} \
                                  {< {$dkim_key_length}{1024}}}}
       logwrite        = NOTE: forcing DKIM verify fail (was pass)
       set dkim_verify_status = fail
       set dkim_verify_reason = hash too weak or key too short

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, with any value, 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’.

If running under GnuTLS 3.6.0 or OpenSSL 1.1.1 or later, may also be ’ed25519-sha256’. The "_CRYPTO_SIGN_ED25519" macro will be defined if support is present for EC keys.

Note that RFC 8301 says:

rsa-sha1 MUST NOT be used for signing or verifying.

DKIM signatures identified as having been signed with historic
algorithms (currently, rsa-sha1) have permanently failed evaluation

To enforce this you must have a DKIM ACL which checks this variable and overwrites the $dkim_verify_status variable as discussed above.

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

Note that Exim does not check 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.

Note that RFC 8301 says:

Verifiers MUST NOT consider signatures using RSA keys of
less than 1024 bits as valid signatures.

To enforce this you must have a DKIM ACL which checks this variable and overwrites the $dkim_verify_status variable as discussed above. As EC keys are much smaller, the check should only do this for RSA keys.

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.

4. SPF (Sender Policy Framework)

SPF is a mechanism whereby a domain may assert which IP addresses may transmit messages with its domain in the envelope from, documented by RFC 7208. For more information on SPF see http://www.openspf.org.

Messages sent by a system not authorised will fail checking of such assertions. This includes retransmissions done by traditional forwarders.

SPF verification support is built into Exim if SUPPORT_SPF=yes is set in Local/Makefile. The support uses the libspf2 library http://www.libspf2.org/. There is no Exim involvement in the transmission of messages; publishing certain DNS records is all that is required.

For verification, an ACL condition and an expansion lookup are provided.

Performing verification sets up information used by the $authresults expansion item.

The ACL condition "spf" can be used at or after the MAIL ACL. It takes as an argument a list of strings giving the outcome of the SPF check, and will succeed for any matching outcome. Valid strings are:

pass

The SPF check passed, the sending host is positively verified by SPF.

fail

The SPF check failed, the sending host is NOT allowed to send mail for the domain in the envelope-from address.

softfail

The SPF check failed, but the queried domain can’t absolutely confirm that this is a forgery.

none

The queried domain does not publish SPF records.

neutral

The SPF check returned a "neutral" state. This means the queried domain has published a SPF record, but wants to allow outside servers to send mail under its domain as well. This should be treated like "none".

permerror

This indicates a syntax error in the SPF record of the queried domain. You may deny messages when this occurs.

temperror

This indicates a temporary error during all processing, including Exim’s SPF processing. You may defer messages when this occurs.

You can prefix each string with an exclamation mark to invert its meaning, for example "!fail" will match all results but "fail". The string list is evaluated left-to-right, in a short-circuit fashion.

Example:

deny spf = fail
     message = $sender_host_address is not allowed to send mail from \
               ${if def:sender_address_domain \
                    {$sender_address_domain}{$sender_helo_name}}.  \
               Please see http://www.openspf.org/Why?scope=\
               ${if def:sender_address_domain {mfrom}{helo}};\
               identity=${if def:sender_address_domain \
                             {$sender_address}{$sender_helo_name}};\
               ip=$sender_host_address

When the spf condition has run, it sets up several expansion variables:

$spf_header_comment

This contains a human-readable string describing the outcome of the SPF check. You can add it to a custom header or use it for logging purposes.

$spf_received

This contains a complete Received-SPF: header that can be added to the message. Please note that according to the SPF draft, this header must be added at the top of the header list. Please see section 10 on how you can do this.

Note: in case of "Best-guess" (see below), the convention is to put this string in a header called X-SPF-Guess: instead.

$spf_result

This contains the outcome of the SPF check in string form, one of pass, fail, softfail, none, neutral, permerror or temperror.

$spf_result_guessed

This boolean is true only if a best-guess operation was used and required in order to obtain a result.

$spf_smtp_comment

This contains a string that can be used in a SMTP response to the calling party. Useful for "fail".

In addition to SPF, you can also perform checks for so-called "Best-guess". Strictly speaking, "Best-guess" is not standard SPF, but it is supported by the same framework that enables SPF capability. Refer to http://www.openspf.org/FAQ/Best_guess_record for a description of what it means.

To access this feature, simply use the spf_guess condition in place of the spf one. For example:

deny spf_guess = fail
     message = $sender_host_address doesn't look trustworthy to me

In case you decide to reject messages based on this check, you should note that although it uses the same framework, "Best-guess" is not SPF, and therefore you should not mention SPF at all in your reject message.

When the spf_guess condition has run, it sets up the same expansion variables as when spf condition is run, described above.

Additionally, since Best-guess is not standardized, you may redefine what "Best-guess" means to you by redefining the main configuration spf_guess option. For example, the following:

spf_guess = v=spf1 a/16 mx/16 ptr ?all

would relax host matching rules to a broader network range.

A lookup expansion is also available. It takes an email address as the key and an IP address as the database:

  ${lookup {username@domain} spf {ip.ip.ip.ip}}

The lookup will return the same result strings as can appear in $spf_result (pass,fail,softfail,neutral,none,err_perm,err_temp). Currently, only IPv4 addresses are supported.