NAME

Mail::DMARC::Policy - a DMARC policy in object format

VERSION

version 1.20190308

SYNOPSIS

 my $pol = Mail::DMARC::Policy->new(
    'v=DMARC1; p=none; rua=mailto:dmarc@example.com'
    );

 print "not a valid DMARC version!"    if $pol->v ne 'DMARC1';
 print "take no action"                if $pol->p eq 'none';
 print "reject that unaligned message" if $pol->p eq 'reject';
 print "do not send aggregate reports" if ! $pol->rua;
 print "do not send forensic reports"  if ! $pol->ruf;

EXAMPLES

A DMARC record in DNS format looks like this:

    v=DMARC1; p=reject; adkim=s; aspf=s; rua=mailto:dmarc@example.com; pct=100;

DMARC records are stored in TXT resource records in the DNS, at _dmarc.example.com. To retrieve a DMARC record for a domain:

dig

    dig +short _dmarc.example.com TXT

perlishly

    print $_->txtdata."\n"
      for Net::DNS::Resolver->new(dnsrch=>0)->send('_dmarc.example.com','TXT')->answer;

dmarc_lookup

    dmarc_lookup example.com

METHODS

All methods validate their input against the 2013 DMARC specification. Attempts to set invalid values will throw exceptions.

new

Create a new empty policy:

 my $pol = Mail::DMARC::Policy->new;

Create a new policy from named arguments:

 my $pol = Mail::DMARC::Policy->new(
         v   => 'DMARC1',
         p   => 'none',
         pct => 50,
         );

Create a new policy from a DMARC DNS resource record:

 my $pol = Mail::DMARC::Policy->new(
         'v=DMARC1; p=reject; rua=mailto:dmarc@example.com; pct=50;'
         );

If a policy is passed in (the latter two examples), the resulting policy object will be an exact representation of the record as returned from DNS.

Several of the DMARC tags (adkim,aspf,fo,ri,rf) have default values when not specified in the published DNS record. Calling apply_defaults will apply those default values to the DMARC tags that were not specified in the DNS record. The resulting Policy object will be a perfect representation of the DMARC policy that is/was applied.

parse

Accepts a string containing a DMARC Resource Record, as it would be retrieved via DNS.

    my $pol = Mail::DMARC::Policy->new;
    $pol->parse( 'v=DMARC1; p=none; rua=mailto:dmarc@example.com' );
    $pol->parse( 'v=DMARC1' );       # external reporting record

Record Tags

Tag Overview

 v=DMARC1;    (version)
 p=none;      (disposition policy : reject, quarantine, none (monitor))
 sp=reject;   (subdomain policy: same as p)
 adkim=s;     (dkim alignment: s=strict, r=relaxed)
 aspf=r;      (spf  alignment: s=strict, r=relaxed)
 rua=mailto:dmarc-feedback@example.com; (aggregate reports)
 ruf=mailto:dmarc-feedback@example.com; (forensic reports)
 rf=afrf;     (report format: afrf, iodef)
 ri=8400;     (report interval)
 pct=50;      (percent of messages to filter)

Tags in Detail

The descriptions of each DMARC record tag and its corresponding values is from the March 31, 2013 draft of the DMARC spec:

https://datatracker.ietf.org/doc/draft-kucherawy-dmarc-base/?include_text=1

Each tag has a mutator that's a setter and getter. To set any of the tag values, pass in the new value. Examples:

  $pol->p('none');                         set policy action to none
  print "do nothing" if $pol->p eq 'none'; get policy action

v

Version (plain-text; REQUIRED). Identifies the record retrieved as a DMARC record. It MUST have the value of "DMARC1". The value of this tag MUST match precisely; if it does not or it is absent, the entire retrieved record MUST be ignored. It MUST be the first tag in the list.

p

Requested Mail Receiver policy (plain-text; REQUIRED for policy records). Indicates the policy to be enacted by the Receiver at the request of the Domain Owner. Policy applies to the domain queried and to sub-domains unless sub-domain policy is explicitly described using the "sp" tag. This tag is mandatory for policy records only, but not for third-party reporting records (see Section 8.2).

sp

{R6} Requested Mail Receiver policy for subdomains (plain-text; OPTIONAL). Indicates the policy to be enacted by the Receiver at the request of the Domain Owner. It applies only to subdomains of the domain queried and not to the domain itself. Its syntax is identical to that of the "p" tag defined above. If absent, the policy specified by the "p" tag MUST be applied for subdomains.

adkim

(plain-text; OPTIONAL, default is "r".) Indicates whether or not strict DKIM identifier alignment is required by the Domain Owner. If and only if the value of the string is "s", strict mode is in use. See Section 4.3.1 for details.

aspf

(plain-text; OPTIONAL, default is "r".) Indicates whether or not strict SPF identifier alignment is required by the Domain Owner. If and only if the value of the string is "s", strict mode is in use. See Section 4.3.2 for details.

fo

Failure reporting options (plain-text; OPTIONAL, default "0")) Provides requested options for generation of failure reports. Report generators MAY choose to adhere to the requested options. This tag's content MUST be ignored if a "ruf" tag (below) is not also specified. The value of this tag is a colon-separated list of characters that indicate failure reporting options as follows:

  0: Generate a DMARC failure report if all underlying
     authentication mechanisms failed to produce an aligned "pass"
     result.

  1: Generate a DMARC failure report if any underlying
     authentication mechanism failed to produce an aligned "pass"
     result.

  d: Generate a DKIM failure report if the message had a signature
     that failed evaluation, regardless of its alignment.  DKIM-
     specific reporting is described in [AFRF-DKIM].

  s: Generate an SPF failure report if the message failed SPF
     evaluation, regardless of its alignment. SPF-specific
     reporting is described in [AFRF-SPF].

rua

Addresses to which aggregate feedback is to be sent (comma- separated plain-text list of DMARC URIs; OPTIONAL). {R11} A comma or exclamation point that is part of such a DMARC URI MUST be encoded per Section 2.1 of [URI] so as to distinguish it from the list delimiter or an OPTIONAL size limit. Section 8.2 discusses considerations that apply when the domain name of a URI differs from that of the domain advertising the policy. See Section 15.6 for additional considerations. Any valid URI can be specified. A Mail Receiver MUST implement support for a "mailto:" URI, i.e. the ability to send a DMARC report via electronic mail. If not provided, Mail Receivers MUST NOT generate aggregate feedback reports. URIs not supported by Mail Receivers MUST be ignored. The aggregate feedback report format is described in Section 8.3.

ruf

Addresses to which message-specific failure information is to be reported (comma-separated plain-text list of DMARC URIs; OPTIONAL). {R11} If present, the Domain Owner is requesting Mail Receivers to send detailed failure reports about messages that fail the DMARC evaluation in specific ways (see the "fo" tag above). The format of the message to be generated MUST follow that specified in the "rf" tag. Section 8.2 discusses considerations that apply when the domain name of a URI differs from that of the domain advertising the policy. A Mail Receiver MUST implement support for a "mailto:" URI, i.e. the ability to send a DMARC report via electronic mail. If not provided, Mail Receivers MUST NOT generate failure reports. See Section 15.6 for additional considerations.

rf

Format to be used for message-specific failure reports (comma- separated plain-text list of values; OPTIONAL; default "afrf"). The value of this tag is a list of one or more report formats as requested by the Domain Owner to be used when a message fails both [SPF] and [DKIM] tests to report details of the individual failure. The values MUST be present in the registry of reporting formats defined in Section 14; a Mail Receiver observing a different value SHOULD ignore it, or MAY ignore the entire DMARC record. Initial default values are "afrf" (defined in [AFRF]) and "iodef" (defined in [IODEF]). See Section 8.4 for details.

ri

Interval requested between aggregate reports (plain-text, 32-bit unsigned integer; OPTIONAL; default 86400). {R14} Indicates a request to Receivers to generate aggregate reports separated by no more than the requested number of seconds. DMARC implementations MUST be able to provide daily reports and SHOULD be able to provide hourly reports when requested. However, anything other than a daily report is understood to be accommodated on a best- effort basis.

pct

(plain-text integer between 0 and 100, inclusive; OPTIONAL; default is 100). {R8} Percentage of messages from the DNS domain's mail stream to which the DMARC mechanism is to be applied. However, this MUST NOT be applied to the DMARC-generated reports, all of which must be sent and received unhindered. The purpose of the "pct" tag is to allow Domain Owners to enact a slow rollout enforcement of the DMARC mechanism. The prospect of "all or nothing" is recognized as preventing many organizations from experimenting with strong authentication-based mechanisms. See Section 7.1 for details.

AUTHORS

Matt Simerson <msimerson@cpan.org>
Davide Migliavacca <shari@cpan.org>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.