• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..03-May-2022-

SECURITY/H20-Dec-2021-184134

build-aux/H20-Dec-2021-74

contrib/H20-Dec-2021-1,010705

db/H20-Dec-2021-184149

libopendmarc/H20-Dec-2021-308,459305,872

m4/H20-Dec-2021-529458

opendmarc/H20-Dec-2021-12,7338,846

reports/H03-May-2022-3,1632,622

www/H03-May-2022-

.editorconfigH A D20-Dec-2021146 108

.gitattributesH A D20-Dec-202145 43

.gitignoreH A D20-Dec-2021305 2524

AutoBuild.shH A D20-Dec-2021607 5142

CONTRIBUTINGH A D20-Dec-20213.3 KiB7054

HowToReleaseH A D20-Dec-20211.7 KiB5237

INSTALLH A D20-Dec-20213.9 KiB11982

LICENSEH A D20-Dec-20212.2 KiB4435

LICENSE.SendmailH A D20-Dec-20214.3 KiB7866

Makefile.amH A D20-Dec-20211.8 KiB5639

PLATFORM_NOTESH A D20-Dec-2021539 108

READMEH A D20-Dec-20218.3 KiB213152

README.mdH A D20-Dec-20217.5 KiB14383

RELEASE_NOTESH A D20-Dec-202124.5 KiB530503

TESTSH A D20-Dec-2021660 2823

announcementH A D20-Dec-20211.1 KiB3221

conf_refcntH A D20-Dec-202112.5 KiB213212

configure.acH A D20-Dec-202114.4 KiB549488

copyright-checkH A D20-Dec-2021380 2215

README

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

README.md

1# README for OpenDMARC
2
3This directory has the latest open source DMARC software from The Trusted Domain Project.
4
5There is a web site at http://www.trusteddomain.org/opendmarc that is home for the latest updates.
6
7On GitHub, the "Master" branch follows the latest released version, while continued development happens on the "develop" branch.
8
9## Introduction
10
11The OpenDMARC project is a community effort to develop and maintain an open source package for providing DMARC report generation and policy enforcement services.  It includes a library for handling DMARC record parsing, a database schema and tools for aggregating and processing transaction history to produce DMARC reports, and a filter that ties it all together with an MTA using the milter protocol.
12
13In simple terms, DMARC takes the results of ARC, SPF and DKIM checks,
14done by either upstream filters, or SPF checks that opendmarc performs itself,
15and uses these to make a "pass or fail" decision.  A domain owner may put
16a record in the DNS to determine what should happen to a failing record:
17No negative action (typically for testing), message quarantining, or
18outright rejection at SMTP acceptance time.
19
20Additionally, records placed in the DNS allow a domain owner to
21receive reports back on when messages are received that fail DMARC,
22as well as specifying what percentage of messages should be evaluated.
23
24This README is not intended to be a full explanation of how the DMARC
25protocol works, but at the very least, some software that does DKIM
26checks should be available in your mail stream in order to use this
27software.
28
29The word "milter" is a portmanteau of "mail filter" and refers to a protocol and API for communicating mail traffic information between MTAs and mail filtering plug-in applications.  It was originally invented at Sendmail, Inc. but has also been adapted to other MTAs.
30
31##  Dependencies
32
33To compile and operate, this package requires the following:
34
35* sendmail v8.13.0 (or later), or Postfix 2.3, (or later) and libmilter. (These are only required if you are building the filter.)
36
37* glib (GLib) headers and libraries 2.48.2 (or greater)
38
39* Access to a working nameserver (required only for signature verification).
40
41* A perl interpreter (required for sending or receiving and  interpreting reports).
42
43* If you are interested in tinkering with the build and packaging structure, you may need to upgrade to these versions of GNU's "autotools" components:
44
45	* autoconf (GNU Autoconf) 2.61
46	* automake (GNU automake) 1.7 (or 1.9 to avoid warnings)
47	* ltmain.sh (GNU libtool) 2.2.6 (or 1.5.26 after make maintainer-clean)
48
49
50## Related Documentation
51
52The man page for opendmarc (the actual filter program) is present in the opendmarc directory of this source distribution.  There is additional information in the `INSTALL` and `FEATURES` files, and in the `README` file in the opendmarc directory.  Changes are documented in the `RELEASE_NOTES` file.
53
54HTML-style documentation for libopendmarc is available in libopendmarc/docs in this source distribution.
55
56General information about DMARC can be found at http://www.dmarc.org
57
58Mailing lists discussing and supporting the DMARC software found in this package are maintained via a list server at trusteddomain.org.  Visit http://www.trusteddomain.org to subscribe or browse archives.  The available lists are:
59
60* opendmarc-announce	(moderated) Release announcements.
61
62* opendmarc-users		General OpenDMARC user questions and answers.
63
64* opendmarc-dev		Chatter among OpenDMARC developers.
65
66* opendmarc-code		Automated source code change announcements.
67
68Bug tracking is done via the trackers on GitHub at:
69
70https://github.com/trusteddomainproject/OpenDMARC/issues
71
72You can enter new bug reports there, but please check first for older bugs  already open, or even already closed, before opening a new issue.
73
74Note that development is being moved away from SourceForge, Freshmeat, or other sites.
75
76## Directory Structure
77
78* `contrib`: A collection of user contributed scripts that may be useful.
79
80* `db`: Database schema and tools for generating DMARC reports based upon accumulated data.
81
82* `libopendmarc`:A library that implements the DMARC standard.
83
84* `libopendmarc/docs`: HTML documentation describing the API provided by libopendmarc.
85
86* `opendmarc`: A milter-based filter application which uses libopendmarc (and optionally libar) to provide DMARC service via an MTA using the milter protocol.
87
88## Runtime Issues
89
90### Missing symbols
91
92You may receive the warning: `WARNING: symbol 'X' not available`
93
94This indicates that the filter attempted to get some information from the MTA that the MTA did not provide.
95
96At various points in the interaction between the MTA and the filter, certain macros containing information about the job in progress or the connection being handled are passed from the MTA to the filter.
97
98In the case of sendmail, the names of the macros the MTA should pass to the filter are defined by the `Milter.macros` settings in sendmail.cf, e.g.`Milter.macros.connect`, `Milter.macros.envfrom`, etc.  This message indicates that the filter needed the contents of macro X, but that macro was not passed down from the MTA.
99
100Typically the values needed by this filter are passed from the MTA if the `sendmail.cf` was generated by the usual m4 method.  If you do not have those options defined in your `sendmail.cf`, make sure your M4 configuration files are current and rebuild your `sendmail.cf` to get appropriate lines added to your `sendmail.cf`, and then restart sendmail.
101
102### MTA timeouts
103
104By default, the MTA is configured to wait up to ten seconds for a response from a filter before giving up.  When querying remote nameservers for key and policy data, the DMARC filter may not get a response from the resolver within that time frame, and thus this MTA timeout will occur.
105
106This can cause messages to be rejected, temp-failed or delivered without verification, depending on the failure mode selected for the filter.
107
108When using the standard resolver library provided with your system, the DNS timeout cannot be adjusted.  If you encounter this problem, you must increase the time the MTA waits for replies.  See the documentation in the sendmail open source distribution (`libmilter/README` in particular) for instructions on changing these timeouts.
109
110When using the provided asynchronous resolver library, you can use the  `-T` command line option to change the timeout so that it is shorter than the MTA timeout.
111
112### Other OpenDMARC issues:
113
114Bug tracking is done via the trackers on GitHub at:
115
116https://github.com/trusteddomainproject/OpenDMARC/issues
117
118Please report them there, after checking for prior reports.
119
120## Further Reading
121
122As DMARC adoption becomes more common, any list of links placed in the README
123of a single implementation will invariably grow out of date.  Using your favorite
124search engine, or the mailing lists for your operating system or MTA is
125not an unreasonable path forward.
126
127As a start, however, the RFC's that define SPF, DKIM, and DMARC present a
128fairly comprehensive, if technical, understanding of the underlying protocols.
129Although there is not much information involving marrying them to a specific
130mail server.
131
132At the time of this writing, the following are the most recent RFC's for the
133protocols involved (although many other RFC's are referenced, of course).
134
135* https://tools.ietf.org/html/rfc6376 (DKIM)
136* https://tools.ietf.org/html/rfc7208 (SPF)
137* https://tools.ietf.org/html/rfc7489 (DMARC)
138* https://tools.ietf.org/html/rfc8617 (ARC)
139
140--
141Copyright (c) 2012, 2016, 2018, 2021, The Trusted Domain Project.
142  All rights reserved.
143