1 2This directory has the latest open source DMARC software from The Trusted 3Domain Project. 4 5There is a web site at http://www.trusteddomain.org/opendmarc that is home for 6the latest updates. 7 8+--------------+ 9| INTRODUCTION | 10+--------------+ 11 12The OpenDMARC project is a community effort to develop and maintain an open 13source package for providing DMARC report generation and policy enforcement 14services. 15 16In simple terms, DMARC takes the results of ARC, SPF and DKIM checks, 17done by either upstream filters, or SPF checks that opendmarc performs itself, 18and uses these to make a "pass or fail" decision. A domain owner may put 19a record in the DNS to determine what should happen to a failing record: 20No negative action (typically for testing), message quarantining, or 21outright rejection at SMTP acceptance time. 22 23Additionally, records placed in the DNS allow a domain owner to 24receive reports back on when messages are received that fail DMARC, 25as well as specifying what percentage of messages should be evaluated. 26 27This README is not intended to be a full explanation of how the DMARC 28protocol works, but at the very least, some software that does DKIM 29checks should be available in your mail stream in order to use this 30software. 31 32This package includes a library for handling DMARC record parsing, 33a database schema and tools for aggregating and processing transaction 34history to produce DMARC reports, and a filter that ties it all together 35with an MTA using the milter protocol. 36 37"milter" is a portmanteau of "mail filter" and refers to a protocol and API 38for communicating mail traffic information between MTAs and mail filtering 39plug-in applications. It was originally invented at Sendmail, Inc. but 40has also been adapted to other MTAs. 41 42Note that the implementation is called "OpenDMARC" but contains a program, 43called "opendmarc", all lower case. 44 45+--------------+ 46| DEPENDENCIES | 47+--------------+ 48 49To compile and operate, this package requires the following: 50 51o sendmail v8.13.0 (or later), or Postfix 2.3, (or later) and libmilter. 52 (These are only required if you are building the filter.) 53 54o glib (GLib) headers and libraries 2.48.2 (or greater) 55 56o some systems (Linux at least) do not natively have the strlcpy() 57 function. Under Arch Linux, this is provided by the "libbsd" package. 58 59o Access to a working nameserver (required only for signature verification). 60 61o A perl interpreter. 62 63o If you are interested in tinkering with the build and packaging structure, 64 you may need to upgrade to these versions of GNU's "autotools" components: 65 autoconf (GNU Autoconf) 2.61 66 automake (GNU automake) 1.7 (or 1.9 to avoid warnings) 67 ltmain.sh (GNU libtool) 2.2.6 (or 1.5.26 after make maintainer-clean) 68 69o LibSFF2 (https://www.libspf2.org) is optional, but can be used for improved 70 SPF parsing inside the opendmarc filter. Note that this will be a requirement 71 in a future version, if SPF checking is desired. 72 73Actual use requires a mail server that speaks the "milter" protocol, as well 74as some DKIM checking service that acts on messages before they reach the 75opendmarc milter (such as the Trusted Domain Project's "OpenDKIM"). A 76filter that performs SPF checking is optional, but OpenDMARC may be compiled 77to link against LibSPF2, and thus do SPF checks on its own. 78 79Some components (such as the report parser) can opeerate without being 80joined to a mail server, but using that portion alone is generally atypical. 81 82+-----------------------+ 83| RELATED DOCUMENTATION | 84+-----------------------+ 85 86The man page for opendmarc (the actual filter program) is present in the 87opendmarc directory of this source distribution. There is additional 88information in the INSTALL and FEATURES files, and in the README file in the 89opendmarc directory. Changes are documented in the RELEASE_NOTES file. 90 91HTML-style documentation for libopendmarc is available in libopendmarc/docs in 92this source distribution. 93 94General information about DMARC can be found at http://www.dmarc.org 95 96Mailing lists discussing and supporting the DMARC software found in this 97package are maintained via a list server at trusteddomain.org. Visit 98http://www.trusteddomain.org to subscribe or browse archives. The available 99lists are: 100 101 opendmarc-announce (moderated) Release announcements. 102 103 opendmarc-users General OpenDMARC user questions and answers. 104 105 opendmarc-dev Chatter among OpenDMARC developers. 106 107 opendmarc-code Automated source code change announcements. 108 109Bug tracking is done via the trackers on SourceForge at 110http://sourceforge.net/projects/opendmarc. You can enter new bug 111reports there, but please check first for older bugs already open, 112or even already closed, before opening a new issue. 113 114 115+---------------------+ 116| DIRECTORY STRUCTURE | 117+---------------------+ 118 119contrib A collection of user contributed scripts that may be useful. 120 121db Database schema and tools for generating DMARC reports based 122 upon accumulated data. 123 124docs A collection of RFCs and drafts related to opendmarc. 125 126libopendmarc A library that implements the proposed DMARC standard. 127 128libopendmarc/docs 129 HTML documentation describing the API provided by libopendmarc. 130 131opendmarc A milter-based filter application which uses libopendmarc (and 132 optionally libar) to provide DMARC service via an MTA using 133 the milter protocol. 134 135 136+----------------+ 137| RUNTIME ISSUES | 138+----------------+ 139 140WARNING: symbol 'X' not available 141 142 The filter attempted to get some information from the MTA that the MTA 143 did not provide. 144 145 At various points in the interaction between the MTA and the filter, certain 146 macros containing information about the job in progress or the connection 147 being handled are passed from the MTA to the filter. 148 149 In the case of sendmail, the names of the macros the MTA should pass to the 150 filter are defined by the "Milter.macros" settings in sendmail.cf, e.g. 151 "Milter.macros.connect", "Milter.macros.envfrom", etc. This message 152 indicates that the filter needed the contents of macro X, but that macro 153 was not passed down from the MTA. 154 155 Typically the values needed by this filter are passed from the MTA if the 156 sendmail.cf was generated by the usual m4 method. If you do not have 157 those options defined in your sendmail.cf, make sure your M4 configuration 158 files are current and rebuild your sendmail.cf to get appropriate lines 159 added to your sendmail.cf, and then restart sendmail. 160 161MTA timeouts 162 163 By default, the MTA is configured to wait up to ten seconds for a response 164 from a filter before giving up. When querying remote nameservers 165 for key and policy data, the DMARC filter may not get a response from the 166 resolver within that time frame, and thus this MTA timeout will occur. 167 This can cause messages to be rejected, temp-failed or delivered without 168 verification, depending on the failure mode selected for the filter. 169 170 When using the standard resolver library provided with your system, the 171 DNS timeout cannot be adjusted. If you encounter this problem, you must 172 increase the time the MTA waits for replies. See the documentation in 173 the sendmail open source distribution (libmilter/README in particular) 174 for instructions on changing these timeouts. 175 176 When using the provided asynchronous resolver library, you can use the 177 "-T" command line option to change the timeout so that it is shorter than 178 the MTA timeout. 179 180Other OpenDMARC issues: 181 182 Report any bugs to the email address opendmarc-users@trusteddomain.org or to 183 the SourceForge issue tracker accessible at: 184 185 http://sourceforge.net/p/opendmarc/tickets/ 186 187 188+-----------------+ 189| FURTHER READING | 190+-----------------+ 191 192As DMARC adoption becomes more common, any list of links placed in the README 193of a single implementation will invariably grow out of date. Using your favorite 194search engine, or the mailing lists for your operating system or MTA is 195not an unreasonable path forward. 196 197As a start, however, the RFC's that define SPF, DKIM, and DMARC present a 198fairly comprehensive, if technical, understanding of the underlying protocols. 199Although there is not much information involving marrying them to a specific 200mail server. 201 202At the time of this writing, the following are the most recent RFC's for the 203protocols involved (although many other RFC's are referenced, of course). 204 205https://tools.ietf.org/html/rfc6376 (DKIM) 206https://tools.ietf.org/html/rfc7208 (SPF) 207https://tools.ietf.org/html/rfc7489 (DMARC) 208https://tools.ietf.org/html/rfc8617 (ARC) 209 210-- 211Copyright (c) 2012, 2016, 2018, 2021, The Trusted Domain Project. 212 All rights reserved. 213