Provided by: libmail-dmarc-perl_1.20230215-1_all 
NAME
Mail::DMARC::Policy - a DMARC policy in object format
VERSION
version 1.20230215
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.
apply_defaults
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>
• Marc Bradshaw <marc@marcbradshaw.net>
COPYRIGHT AND LICENSE
This software is copyright (c) 2023 by Matt Simerson.
This is free software; you can redistribute it and/or modify it under the same terms as
the Perl 5 programming language system itself.