X-Git-Url: https://git.exim.org/users/heiko/exim.git/blobdiff_plain/c0635b6dfe65ee24c2fb8d165beabc608d2fd1a5..9122c6523b5c178a0ab4e28115e15179b1e6dea6:/doc/doc-txt/experimental-spec.txt diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt index d5140d58b..aa93e07bf 100644 --- a/doc/doc-txt/experimental-spec.txt +++ b/doc/doc-txt/experimental-spec.txt @@ -430,14 +430,13 @@ package controlled locations (/usr/include and /usr/lib). 2. Use the following global settings to configure DMARC: -Optional: +Required: dmarc_tld_file Defines the location of a text file of valid top level domains the opendmarc library uses during domain parsing. Maintained by Mozilla, the most current version can be downloaded from a link at http://publicsuffix.org/list/. - If unset, "/etc/exim/opendmarc.tlds" (hardcoded) - is used. + See also util/renew-opendmarc-tlds.sh script. Optional: dmarc_history_file Defines the location of a file to log results @@ -525,6 +524,9 @@ Of course, you can also use any other lookup method that Exim supports, including LDAP, Postgres, MySQL, etc, as long as the result is a list of colon-separated strings. +Performing the check sets up information used by the +${authresults } expansion item. + Several expansion variables are set before the DATA ACL is processed, and you can use them in this ACL. The following expansion variables are available: @@ -548,9 +550,8 @@ expansion variables are available: are "none", "reject" and "quarantine". It is blank when there is any error, including no DMARC record. - o $dmarc_ar_header - This is the entire Authentication-Results header which you can - add using an add_header modifier. +A now-redundant variable $dmarc_ar_header has now been withdrawn. +Use the ${authresults } expansion instead. 5. How to enable DMARC advanced operation: @@ -590,7 +591,6 @@ b. Configure, somewhere before the DATA ACL, the control option to warn dmarc_status = accept : none : off !authenticated = * log_message = DMARC DEBUG: $dmarc_status $dmarc_used_domain - add_header = $dmarc_ar_header warn dmarc_status = !accept !authenticated = * @@ -609,6 +609,8 @@ b. Configure, somewhere before the DATA ACL, the control option to !authenticated = * message = Message from $dmarc_used_domain failed sender's DMARC policy, REJECT + warn add_header = :at_start:${authresults {$primary_hostname}} + DSN extra information @@ -723,7 +725,7 @@ the queuefile driver. The transport only takes one option: * directory - This is used to specify the directory messages should be -copied to +copied to. Expanded. The generic transport options (body_only, current_directory, disable_logging, debug_print, delivery_date_add, envelope_to_add, event_action, group, @@ -756,6 +758,108 @@ to your Local/Makefile. (Re-)build/install exim. exim -d should show Experimental_QUEUEFILE in the line "Support for:". +ARC support +----------- +Specification: https://tools.ietf.org/html/draft-ietf-dmarc-arc-protocol-11 +Note that this is not an RFC yet, so may change. + +ARC is intended to support the utility of SPF and DKIM in the presence of +intermediaries in the transmission path - forwarders and mailinglists - +by establishing a cryptographically-signed chain in headers. + +Normally one would only bother doing ARC-signing when functioning as +an intermediary. One might do verify for local destinations. + +ARC uses the notion of a "ADministrative Management Domain" (ADMD). +Described in RFC 5598 (section 2.3), this is essentially the set of +mail-handling systems that the mail transits. A label should be chosen to +identify the ADMD. Messages should be ARC-verified on entry to the ADMD, +and ARC-signed on exit from it. + + +Verification +-- +An ACL condition is provided to perform the "verifier actions" detailed +in section 6 of the above specification. It may be called from the DATA ACL +and succeeds if the result matches any of a given list. +It also records the highest ARC instance number (the chain size) +and verification result for later use in creating an Authentication-Results: +standard header. + + verify = arc/ none:fail:pass + + add_header = :at_start:${authresults {}} + + Note that it would be wise to strip incoming messages of A-R headers + that claim to be from our own . + +There are three new variables: $arc_state, $arc_state_reason, $arc_domains: + + $arc_state One of pass, fail, none + $arc_state_reason (if fail, why) + $arc_domains colon-sep list of ARC chain domains, in chain order. + problematic elements may have empty list elements + $arc_oldest_pass lowest passing instance number of chain + +Example: + logwrite = oldest-p-ams: <${reduce {$lh_ARC-Authentication-Results:} \ + {} \ + {${if = {$arc_oldest_pass} \ + {${extract {i}{${extract {1}{;}{$item}}}}} \ + {$item} {$value}}} \ + }> + +Receive log lines for an ARC pass will be tagged "ARC". + + +Signing +-- +arc_sign = : : [ : ] +An option on the smtp transport, which constructs and prepends to the message +an ARC set of headers. The textually-first Authentication-Results: header +is used as a basis (you must have added one on entry to the ADMD). +Expanded as a whole; if unset, empty or forced-failure then no signing is done. +If it is set, all of the first three elements must be non-empty. + +The fourth element is optional, and if present consists of a comma-separated list +of options. The options implemented are + + timestamps Add a t= tag to the generated AMS and AS headers, with the + current time. + expire[=] Add an x= tag to the generated AMS header, with an expiry time. + If the value is an plain number it is used unchanged. + If it starts with a '+' then the following number is added + to the current time, as an offset in seconds. + If a value is not given it defaults to a one month offset. + +[As of writing, gmail insist that a t= tag on the AS is mandatory] + +Caveats: + * There must be an Authentication-Results header, presumably added by an ACL + while receiving the message, for the same ADMD, for arc_sign to succeed. + This requires careful coordination between inbound and outbound logic. + + Only one A-R header is taken account of. This is a limitation versus + the ARC spec (which says that all A-R headers from within the ADMD must + be used). + + * If passing a message to another system, such as a mailing-list manager + (MLM), between receipt and sending, be wary of manipulations to headers made + by the MLM. + + For instance, Mailman with REMOVE_DKIM_HEADERS==3 might improve + deliverability in a pre-ARC world, but that option also renames the + Authentication-Results header, which breaks signing. + + * Even if you use multiple DKIM keys for different domains, the ARC concept + should try to stick to one ADMD, so pick a primary domain and use that for + AR headers and outbound signing. + +Signing is not compatible with cutthrough delivery; any (before expansion) +value set for the option will result in cutthrough delivery not being +used via the transport in question. + + + -------------------------------------------------------------- End of file --------------------------------------------------------------