From a696faf4490f2a2f698fe9d04d6cfecec52894b6 Mon Sep 17 00:00:00 2001 From: Vsevolod Stakhov Date: Sat, 5 Sep 2015 17:10:14 +0100 Subject: [PATCH] Add dmarc module documentation. --- doc/markdown/modules/dmarc.md | 44 +++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 doc/markdown/modules/dmarc.md diff --git a/doc/markdown/modules/dmarc.md b/doc/markdown/modules/dmarc.md new file mode 100644 index 000000000..191e1c216 --- /dev/null +++ b/doc/markdown/modules/dmarc.md @@ -0,0 +1,44 @@ +# DMARC module + +DMARC is a special technology that allows domains to define theirs `SPF` and `DKIM` policies. For example, a domain +might define that all messages sent must have valid DKIM signature and permissive SPF policies. That is useful for +domains that deal with payments or other confidential stuff (such as e-banking). Conjunction of SPF, DKIM and DMARC +allows to avoid or filter fraud for such domains. + +Moreover, DMARC allows to set a specific address to collect abused messages. This can be useful for fraud prevention as well. +DMARC is set using DNS `TXT` record, called `_dmarc.domain.com`. It's format is standartized and here is, for example a record +that specifies strict policy for SPF and DKIM: + + v=DMARC1; p=reject; rua=mailto:d@rua.agari.com; ruf=mailto:dk@bounce.paypal.com,mailto:d@ruf.agari.com + +This record also specifies email addresses for abuse reports (for realtime and archives). + +## DMARC in rspamd + +Rspamd supports DMARC policies and also can store information about mails that have violated policies for collecting statistics and sending reports. +Please mention, that rspamd itself cannot send reports, it merely stores sufficient data in `redis` that could be used for generating DMARC reports by an external tool (not shipped with rspamd now). + +DMARC configuration is very simple: + +~~~nginx +dmarc { + servers = "localhost:6390"; + key_prefix = "dmarc_"; # Keys would have format of dmarc_domain.com +} +~~~ + +When you have this module enabled, it also adds symbols: + +- `DMARC_POLICY_ALLOW`: SPF **and** DKIM policies are satisfied +- `DMARC_POLICY_REJECT`: SPF **or** DKIM policies are violated +- `DMARC_POLICY_QUARANTINE`: Message is suggested to be quarantined by DMARC policy +- `DMARC_POLICY_SOFTFAIL`: DNS or other temporary error + +When a message violates DMARC policy, rspamd adds the following information to `redis` server: + + unixtime:ip:spf_result:dkim_result + +where results are `true` or `false` meaning allow and reject values accordingly. +Unixtime and IP are inserted in text form. Keys are therefore `lists` in redis terminology. + +Keys are inserted to redis servers when a server is selected by hash value from sender's domain. \ No newline at end of file -- 2.39.5