gs.dmarc Documentation

Author:Michael JasonSmith
Contact:Michael JasonSmith <mpj17@onlinegroups.net>
Date:2015-06-25
Organization:GroupServer.org
Copyright:This document is licensed under a Creative Commons Attribution-Share Alike 4.0 International License by OnlineGroups.net.

This product allows systems look up and report on the DMARC (RFC 7489: Domain-based Message Authentication, Reporting and Conformance) status of a domain. DMARC allows the owner of a domain to publish a key that is used to verify if an email message actually originated from the domain, and to publish what to do if the verification fails. It is an extension of DKIM (DomainKeys Identified Mail, RFC 6376) and SPF (Sender Policy Framework, RFC 4408).

Specifically this product supplies ReceiverPolicy for enumerating the different DMARC policies, and the receiver_policy() function for querying the policy for a given domain.

Contents:

gs.dmarc API Reference

Currently only querying the DMARC receiver policy is supported.

Receiver Policy

A DMARC receiver policy is published in a DNS TXT record, in a domain that starts with _dmarc. It is possible to use the host program to look up a DMARC record.

$ host -t TXT _dmarc.yahoo.com
_dmarc.yahoo.com descriptive text "v=DMARC1\; p=reject\; sp=none\; pct=100\; rua=mailto:dmarc-yahoo-rua@yahoo-inc.com, mailto:dmarc_y_rua@yahoo.com\;"

The receiver_policy() function performs the DNS query, parses the results, and returns the policy for the host. The different policies are listed by the ReceiverPolicy enumeration.

gs.dmarc.receiver_policy(host)[source]

Get the DMARC receiver policy for a host.

Parameters:host (str) – The host to lookup.
Returns:The DMARC reciever policy for the host.
Return type:A member of the gs.dmarc.ReceiverPolicy enumeration.

The receiver_policy() function looks up the DMARC reciever polciy for host. If the host does not have a pubished policy the organizational domain is determined. The DMARC policy for the organizational domain is queried, and the subdomain policy is reuturned (if specified) or the overall policy for the domain is returned. Internally the gs.dmarc.lookup.lookup_receiver_policy() is used to perform the query.

class gs.dmarc.ReceiverPolicy[source]

An enumeration of the different receiver policies in DMARC.

noDmarc = <ReceiverPolicy.noDmarc: 0>

No published DMARC receiver-policy could be found. Often interpreted the same way as gs.dmarc.ReceiverPolicy.none.

none = <ReceiverPolicy.none: 1>

The published policy is none. Recieving parties are supposed to skip the verification of the DMARC signature.

quarantine = <ReceiverPolicy.quarantine: 2>

Generally causes the message to be marked as spam if verification fails.

reject = <ReceiverPolicy.reject: 3>

Causes the system that is receiving the message to reject the message if the verification fails.

Example

Get the host from an email address, and get the receiver policy.

addr = email.utils.parseaddr('mpj17@onlinegroups.net')
host = addr[1].split('@')[1]
policy = receiver_policy(host)

if (policy in (ReceiverPolicy.quarintine, ReceiverPolicy.reject)):
    # Rewrite the From header

See also

publicsuffixlist
The organizational domain is determined by the publicsuffixlist product.
dnspython
The dnspython product is used to perform the DNS query.
enum34
The enum34 product is used to provide enumeration support in versions of Python prior to 3.4.

Internal

Internally the lookup.lookup_receiver_policy() function is used to make a DNS query, parse the arguments, and return a member from the ReceiverPolicy enumeration.

gs.dmarc.lookup.lookup_receiver_policy(host, policyTag=u'p')[source]

Lookup the reciever policy for a host. Returns a ReceiverPolicy.

Parameters:
  • host (str) – The host to query. The actual host that is queried has _dmarc. prepended to it.
  • policyTag (str) – The tag that holds the receiver policy. Must be p (the default) or sp (for the subdomain policy). See RFC 7489#section-6.3.
Returns:

The DMARC receiver policy for the host. If there is no published policy then gs.dmarc.ReceiverPolicy.noDmarc is returned.

Return type:

A member of the gs.dmarc.ReceiverPolicy enumeration.

Changelog

2.1.9 (2016-12-16)

  • Falling back to the either the overall subdomain-policy or overall domain-policy if a subdomain lacks a specific published DMARC record — with thanks to Igor Colombi for pointing out the issue

2.1.8 (2016-10-18)

  • Adding PEP 484 type hints
  • Updating the public-suffix list
  • Using setuptools to return the public-suffix list

2.1.7 (2016-04-11)

  • Testing with Python 3.5
  • Switching to dictionary-comprehensions

2.1.6 (2016-03-24)

  • Updating the suffix list from Mozilla, thanks to Baran Kaynak

2.1.5 (2015-09-01)

2.1.4 (2015-06-25)

2.1.3 (2014-10-20)

  • Handling domains with invalid DMARC policies, closing Bug 4135

2.1.2 (2014-09-26)

  • Switching to GitHub as the primary code repository.

2.1.1 (2014-07-09)

  • Coping when the host-name passed to lookup_receiver_policy for hosts that start with _dmarc already
  • Rejecting all answers that do not start with v=DMARC1, as per Section 7.1 (number 5) of the draft DMARC specification

2.1.0 (2014-05-07)

  • Adding gs.dmarc.receiver_policy, which looks up the organisational domain
  • Updating the Sphinx documentation

2.0.0 (2014-04-29)

  • Adding gs.dmarc.ReceiverPolicy.noDmarc, and returning it from gs.dmarc.lookup_receiver_policy
  • Adding Sphinx documentation

1.0.0 (2014-04-24)

Initial release.

Indices and tables