From 1899bab2d862898cb92c3ec9765f3357acb2bfc9 Mon Sep 17 00:00:00 2001 From: Todd Lyons Date: Mon, 1 Apr 2013 11:36:30 -0700 Subject: [PATCH] DMARC documentation and license --- doc/doc-docbook/spec.xfpt | 9 ++ doc/doc-txt/experimental-spec.txt | 203 ++++++++++++++++++++++++++++++ src/LICENSE.opendmarc | 29 +++++ 3 files changed, 241 insertions(+) create mode 100644 src/LICENSE.opendmarc diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 063d74a92..018c88ff4 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -746,6 +746,7 @@ the Exim documentation, &"spool"& is always used in the first sense. .cindex "incorporated code" .cindex "regular expressions" "library" .cindex "PCRE" +.cindex "OpenDMARC" A number of pieces of external code are included in the Exim distribution. .ilist @@ -870,6 +871,14 @@ ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .endblockquote +.next +.cindex "opendmarc" "acknowledgment" +The DMARC implementation uses the OpenDMARC library which is Copyrighted by +The Trusted Domain Project. Portions of Exim source which use OpenDMARC +derived code are indicated in the respective source files. The full OpenDMARC +license is provided in the LICENSE.opendmarc file contained in the distributed +source code. + .next Many people have contributed code fragments, some large, some small, that were not covered by any specific licence requirements. It is assumed that the diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt index 385f0526e..d58f3961b 100644 --- a/doc/doc-txt/experimental-spec.txt +++ b/doc/doc-txt/experimental-spec.txt @@ -627,6 +627,209 @@ mout.gmx.net 212.227.15.16 Use a reasonable IP. eg. one the sending cluster acutally uses. +DMARC Support +-------------------------------------------------------------- + +DMARC combines feedback from SPF, DKIM, and header From: in order +to attempt to provide better indicators of the authenticity of an +email. This document does not explain the fundamentals, you +should read and understand how it works by visiting the website at +http://www.dmarc.org/. + +DMARC support is added via the libopendmarc library. Visit: + + http://sourceforge.net/projects/opendmarc/ + +to obtain a copy, or find it in your favorite rpm package +repository. If building from source, this description assumes +that headers will be in /usr/local/include, and that the libraries +are in /usr/local/lib. + +1. To compile Exim with DMARC support, you must first enable SPF. +Please read the above section on enabling the EXPERIMENTAL_SPF +feature. You must also have DKIM support, so you cannot set the +DISABLE_DKIM feature. Once both of those conditions have been met +you can enable DMARC in Local/Makefile: + +EXPERIMENTAL_DMARC=yes +LDFLAGS += -lopendmarc +# CFLAGS += -I/usr/local/include +# LDFLAGS += -L/usr/local/lib + +The first line sets the feature to include the correct code, and +the second line says to link the libopendmarc libraries into the +exim binary. The commented out lines should be uncommented if you +built opendmarc from source and installed in the default location. +Adjust the paths if you installed them elsewhere, but you do not +need to uncomment them if an rpm (or you) installed them in the +package controlled locations (/usr/include and /usr/lib). + + +2. Use the following global settings to configure DMARC: + +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/. + +Optional: +dmarc_history_file Defines the location of a file to log results + of dmarc verification on inbound emails. The + contents are importable by the opendmarc tools + which will manage the data, send out DMARC + reports, and expire the data. Make sure the + directory of this file is writable by the user + exim runs as. + +dmarc_forensic_sender The email address to use when sending a + forensic report detailing alignment failures + if a sender domain's dmarc record specifies it + and you have configured Exim to send them. + Default: do-not-reply@$default_hostname + + +3. By default, the DMARC processing will run for any remote, +non-authenticated user. It makes sense to only verify DMARC +status of messages coming from remote, untrusted sources. You can +use standard conditions such as hosts, senders, etc, to decide that +DMARC verification should *not* be performed for them and disable +DMARC with a control setting: + + control = dmarc_verify_disable + +A DMARC record can also specify a "forensic address", which gives +exim an email address to submit reports about failed alignment. +Exim does not do this by default because in certain conditions it +results in unintended information leakage (what lists a user might +be subscribed to, etc). You must configure exim to submit forensic +reports to the owner of the domain. If the DMARC record contains a +forensic address and you specify the control statement below, then +exim will send these forensic emails. It's also advised that you +configure a dmarc_forensic_sender because the default sender address +construction might be inadequate. + + control = dmarc_forensic_enable + +(AGAIN: You can choose not to send these forensic reports by simply +not putting the dmarc_forensic_enable control line at any point in +your exim config. If you don't tell it to send them, it will not +send them.) + +There are no options to either control. Both must appear before +the DATA acl. + + +4. You can now run DMARC checks in incoming SMTP by using the +"dmarc_status" ACL condition in the DATA ACL. You are required to +call the spf condition first in the ACLs, then the "dmarc_status" +condition. Putting this condition in the ACLs is required in order +for a DMARC check to actually occur. All of the variables are set +up before the DATA ACL, but there is no actual DMARC check that +occurs until a "dmarc_status" condition is encountered in the ACLs. + +The dmarc_status condition takes a list of strings on its +right-hand side. These strings describe recommended action based +on the DMARC check. To understand what the policy recommendations +mean, refer to the DMARC website above. Valid strings are: + + o accept The DMARC check passed and the library recommends + accepting the email. + o reject The DMARC check failed and the library recommends + rejecting the email. + o quarantine The DMARC check failed and the library recommends + keeping it for further inspection. + o norecord No policy section in the DMARC record for this + sender domain. + o nofrom Unable to determine the domain of the sender. + o none There is no DMARC record for this sender domain. + o error Library error or dns error. + +You can prefix each string with an exclamation mark to invert its +meaning, for example "!accept" will match all results but +"accept". The string list is evaluated left-to-right in a +short-circuit fashion. When a string matches the outcome of the +DMARC check, the condition succeeds. If none of the listed +strings matches the outcome of the DMARC check, the condition +fails. + +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; + +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: + + o $dmarc_status + This is a one word status indicating what the DMARC library + thinks of the email. + + o $dmarc_status_text + This is a slightly longer, human readable status. + + o $dmarc_used_domain + This is the domain which DMARC used to look up the DMARC + policy record. + + o $dmarc_ar_header + This is the entire Authentication-Results header which you can + add using an add_header modifier. + + +5. How to enable DMARC advanced operation: +By default, Exim's DMARC configuration is intended to be +non-intrusive and conservative. To facilitate this, Exim will not +create any type of logging files without explicit configuration by +you, the admin. Nor will Exim send out any emails/reports about +DMARC issues without explicit configuration by you, the admin (other +than typical bounce messages that may come about due to ACL +processing or failure delivery issues). + +In order to log statistics suitable to be imported by the opendmarc +tools, you need to: +a. Configure the global setting dmarc_history_file. +b. Configure cron jobs to call the appropriate opendmarc history + import scripts and truncating the dmarc_history_file. + +In order to send forensic reports, you need to: +a. Configure the global setting dmarc_forensic_sender. +b. Configure, somewhere before the DATA ACL, the control option to + enable sending DMARC forensic reports. + + +6. Example usage: +(RCPT ACL) + warn domains = +local_domains + hosts = +local_hosts + control = dmarc_verify_disable + + warn !domains = +screwed_up_dmarc_records + control = dmarc_enable_forensic + +(DATA ACL) + 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 = * + log_message = DMARC DEBUG: '$dmarc_status' for $dmarc_used_domain + + warn dmarc_status = quarantine + !authenticated = * + set $acl_m_quarantine = 1 + # Do something in a transport with this flag variable + + deny dmarc_status = reject + !authenticated = * + message = Message from $domain_used_domain failed sender's DMARC policy, REJECT + + + + -------------------------------------------------------------- End of file -------------------------------------------------------------- diff --git a/src/LICENSE.opendmarc b/src/LICENSE.opendmarc new file mode 100644 index 000000000..e2ba06b04 --- /dev/null +++ b/src/LICENSE.opendmarc @@ -0,0 +1,29 @@ +Copyright (c) 2009, 2010, 2012, The Trusted Domain Project. +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + * Neither the name of The Trusted Domain Project nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +Portions of this project are also covered by the Sendmail Open Source +License, available in this distribution in the file "LICENSE.Sendmail". +See the copyright notice(s) in each file to determine whether or not it is +covered by both licenses. + +THIS SOFTWARE IS PROVIDED BY THE OPENDKIM PROJECT ''AS IS'' AND ANY +EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE OPENDKIM PROJECT BE LIABLE FOR ANY +DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -- 2.30.2