lib/Mail/DMARC.pm

filter: Statementstmt 96.8% 155 / 160 Branchbran 88.7% 71 / 80 Conditioncond 100% 12 / 12 MC/DCmcdc 100% 8 / 8 Subroutinesub 100% 26 / 26 Podpod 50.0% 9 / 18 totaltotal 92.4% 281 / 304 CC 60 SCAR 16.2
CC
60
Cov
94%
get_report_window
10.0
sender
7.9
dkim
7.0
CRAP 5.1
« blib/lib/Mail/DMARC/Report/Aggregate/Metadata.pm ↑ Summary lib/Mail/DMARC/Report/Aggregate/Record/Auth_Results/SPF.pm »
1 package Mail::DMARC;
2 11 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 11 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 11 ▶use feature 'signatures';
Subroutine BEGIN: called CC=1 SCAR=0.0
5 11 ▶no warnings 'experimental::args_array_with_signatures'; ## no critic (ProhibitNoWarnings)
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 11 our $VERSION = '2.20260827';
8  
9 11 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 11 our $psl_loads = 0;
11  
12 11 ▶use parent 'Mail::DMARC::Base';
Subroutine BEGIN: called CC=1 SCAR=0.0
13 11 require Mail::DMARC::Policy;
14 11 require Mail::DMARC::Result;
15 11 require Mail::DMARC::Report::Aggregate::Record;
16 11 require Mail::DMARC::Report::Aggregate::Record::Auth_Results::SPF;
17 11 require Mail::DMARC::Report::Aggregate::Record::Auth_Results::DKIM;
18  
19 68 ▶sub new( $class, @args ) {
Subroutine new: called CC=6 SCAR=17.9
Pod documented
20 68 ▶ croak "invalid args" if @args % 2;
Branch: 1 branch
BranchTrueFalseTotal
if @args % 2 0 68 68
21 68 my %args = @args;
22 68 my $self = bless { config_file => 'mail-dmarc.ini', }, $class;
23  
24 my @keys = sort {
25 68 ▶ $a eq 'config_file' ? -1
Branch: 2 branches
BranchTrueFalseTotal
$a eq 'config_file' ? : 19 130 149
$b eq 'config_file' ? : 13 117 130
26 : $b eq 'config_file' ? 1
27 : ( $a cmp $b )
28 } keys %args;
29  
30 68 foreach my $key (@keys) {
31 85 ▶ if ( $self->can($key) ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can($key)) { } 72 13 85
32 72 $self->$key( $args{$key} );
33 }
34 else {
35 13 $self->{$key} = $args{$key};
36 }
37 }
38 68 return $self;
39 }
40  
41 67 ▶sub source_ip( $self, $val = undef ) {
Subroutine source_ip: called CC=4 SCAR=13.9
Pod documented
42 67 ▶ return $self->{source_ip} if @_ == 1;
Branch: 1 branch
BranchTrueFalseTotal
if @_ == 1 34 33 67
43 33 ▶ croak "invalid source_ip" if !$self->is_valid_ip($val);
Branch: 1 branch
BranchTrueFalseTotal
unless $self->is_valid_ip($val) 3 30 33
44 30 return $self->{source_ip} = $val;
45 }
46  
47 38 ▶sub envelope_to( $self, $val = undef ) {
Subroutine envelope_to: called CC=4 SCAR=13.9
Pod documented
48 38 ▶ return $self->{envelope_to} if @_ == 1;
Branch: 1 branch
BranchTrueFalseTotal
if @_ == 1 11 27 38
49 27 ▶ croak "invalid envelope_to" if !$self->is_valid_domain( lc $val );
Branch: 1 branch
BranchTrueFalseTotal
unless $self->is_valid_domain(lc $val) 1 26 27
50 26 return $self->{envelope_to} = $val;
51 }
52  
53 36 ▶sub envelope_from( $self, $val = undef ) {
Subroutine envelope_from: called CC=4 SCAR=13.9
Pod documented
54 36 ▶ return $self->{envelope_from} if @_ == 1;
Branch: 1 branch
BranchTrueFalseTotal
if @_ == 1 11 25 36
55 25 ▶ croak "invalid envelope_from" if !$self->is_valid_domain( lc $val );
Branch: 1 branch
BranchTrueFalseTotal
unless $self->is_valid_domain(lc $val) 0 25 25
56 25 return $self->{envelope_from} = $val;
57 }
58  
59 379 ▶sub header_from( $self, $val = undef ) {
Subroutine header_from: called CC=4 SCAR=13.9
Pod documented
60 379 ▶ return $self->{header_from} if @_ == 1;
Branch: 1 branch
BranchTrueFalseTotal
if @_ == 1 302 77 379
61 77 ▶ croak "invalid header_from" if !$self->is_valid_domain( lc $val );
Branch: 1 branch
BranchTrueFalseTotal
unless $self->is_valid_domain(lc $val) 4 73 77
62 73 return $self->{header_from} = lc $val;
63 }
64  
65 21 ▶sub header_from_raw( $self, $val = undef ) {
Subroutine header_from_raw: called CC=3 SCAR=11.0
Pod documented
66 21 ▶ return $self->{header_from_raw} if @_ == 1;
Branch: 1 branch
BranchTrueFalseTotal
if @_ == 1 11 10 21
67  
68 #croak "invalid header_from_raw: $val" if 'from:' ne lc substr($val, 0, 5);
69 10 return $self->{header_from_raw} = lc $val;
70 }
71  
72 1 ▶sub sender( $self, $val = undef ) {
Subroutine sender: called CC=4 SCAR=20.7
Pod undocumented
73 1 ▶ return $self->{sender} if @_ == 1;
Branch: 1 branch
BranchTrueFalseTotal
if @_ == 1 1 0 1
74 0 ▶ croak "invalid sender" if !$self->is_valid_domain( lc $val );
Branch: 1 branch
BranchTrueFalseTotal
unless $self->is_valid_domain(lc $val) 0 0 0
75 0 return $self->{sender} = lc $val;
76 }
77  
78 4 ▶sub local_policy( $self, $val = undef ) {
Subroutine local_policy: called CC=3 SCAR=11.0
Pod undocumented
79 4 ▶ return $self->{local_policy} if @_ == 1;
Branch: 1 branch
BranchTrueFalseTotal
if @_ == 1 2 2 4
80  
81 # TODO: document this, when and why it would be used
82 2 return $self->{local_policy} = $val;
83 }
84  
85 153 ▶sub dkim( $self, @args ) {
Subroutine dkim: called CC=7 SCAR=19.5
Pod documented
86 153 ▶ if ( !@args ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@args) 97 56 153
87 97 $self->_unwrap('dkim');
88 97 return $self->{dkim};
89 }
90  
91 # one shot
92 56 ▶ if ( @args == 1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@args == 1) 52 4 56
93  
94 # warn "one argument\n";
95 52 ▶ if ( ref $args[0] eq 'CODE' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $args[0] eq "CODE") 1 51 52
96 1 return $self->{dkim} = $args[0];
97 }
98  
99 51 ▶ if ( ref $args[0] eq 'ARRAY' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $args[0] eq "ARRAY") 39 12 51
100 39 foreach my $d ( @{ $args[0] } ) {
101 30 push @{ $self->{dkim} },
102 Mail::DMARC::Report::Aggregate::Record::Auth_Results::DKIM
103 ->new($d);
104 }
105 39 return $self->{dkim};
106 }
107  
108 12 ▶ if ( ref $args[0] eq 'Mail::DKIM::Verifier' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $args[0] eq "Mail::DKIM::Verifier") 1 11 12
109 1 $self->_from_mail_dkim( $args[0] );
110 1 return $self->{dkim};
111 }
112 }
113  
114 #warn "iterative\n";
115 15 push @{ $self->{dkim} },
116 Mail::DMARC::Report::Aggregate::Record::Auth_Results::DKIM->new(@args);
117  
118 13 return $self->{dkim};
119 }
120  
121 1 ▶sub _from_mail_dkim( $self, $dkim ) {
Subroutine _from_mail_dkim: called CC=5 SCAR=17.6
122 1 my $signatures = 0;
123  
124 # A DKIM verifier will have result and signature methods.
125 1 foreach my $s ( $dkim->signatures ) {
126 1 ▶ next if ref $s eq 'Mail::DKIM::DkSignature';
Branch: 1 branch
BranchTrueFalseTotal
if ref $s eq "Mail::DKIM::DkSignature" 0 1 1
127 1 $signatures++;
128  
129 1 my $result = $s->result;
130  
131 1 ▶ if ( $result eq 'invalid' ) { # See GH Issue #21
Branch: 1 branch
BranchTrueFalseTotal
if ($result eq "invalid") 0 1 1
132 0 $result = 'temperror';
133 }
134  
135 1 push @{ $self->{dkim} },
136 Mail::DMARC::Report::Aggregate::Record::Auth_Results::DKIM->new(
137 domain => $s->domain,
138 selector => $s->selector,
139 result => $result,
140 human_result => $s->result_detail,
141 );
142 }
143  
144 1 ▶ if ( $signatures < 1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($signatures < 1) 0 1 1
145 0 push @{ $self->{dkim} },
146 Mail::DMARC::Report::Aggregate::Record::Auth_Results::DKIM->new(
147 domain => '',
148 result => 'none',
149 );
150 }
151  
152 1 return;
153 }
154  
155 212 ▶sub _unwrap( $self, $key ) {
Subroutine _unwrap: called CC=3 SCAR=11.0
156 212 ▶ if ( $self->{$key} and ref $self->{$key} eq 'CODE' ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{$key} and ref $self->{$key} eq "CODE") 2 210 212
Condition100%3/3
$self->{$key} and ref $self->{$key} eq "CODE"
!ll&&!rl&&r
171932
MC/DC100%2/2
$self->{$key} and ref $self->{$key} eq "CODE"
$self->{$key} ref $self->{$key} eq "CODE"
Truth table100%3/3
A and B
A= $self->{$key}B= ref $self->{$key} eq "CODE"
ABresult
0X0
100
111
157 2 my $code = delete $self->{$key};
158 2 $self->$key( $self->$code );
159 }
160 212 return;
161 }
162  
163 169 ▶sub spf( $self, @args ) {
Subroutine spf: called CC=7 SCAR=19.5
Pod documented
164 169 ▶ if ( !@args ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@args) 115 54 169
165 115 $self->_unwrap('spf');
166 115 return $self->{spf};
167 }
168  
169 54 ▶ if ( @args == 1 && ref $args[0] eq 'CODE' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@args == 1 and ref $args[0] eq "CODE") 1 53 54
Condition100%3/3
@args == 1 and ref $args[0] eq "CODE"
!ll&&!rl&&r
5481
MC/DC100%2/2
@args == 1 and ref $args[0] eq "CODE"
@args == 1 ref $args[0] eq "CODE"
Truth table100%3/3
A and B
A= @args == 1B= ref $args[0] eq "CODE"
ABresult
0X0
100
111
170 1 return $self->{spf} = $args[0];
171 }
172  
173 53 ▶ if ( @args == 1 && ref $args[0] eq 'ARRAY' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@args == 1 and ref $args[0] eq "ARRAY") 31 22 53
Condition100%3/3
@args == 1 and ref $args[0] eq "ARRAY"
!ll&&!rl&&r
51731
MC/DC100%2/2
@args == 1 and ref $args[0] eq "ARRAY"
@args == 1 ref $args[0] eq "ARRAY"
Truth table100%3/3
A and B
A= @args == 1B= ref $args[0] eq "ARRAY"
ABresult
0X0
100
111
174  
175 # warn "SPF one shot";
176 31 foreach my $d ( @{ $args[0] } ) {
177 39 push @{ $self->{spf} },
178 Mail::DMARC::Report::Aggregate::Record::Auth_Results::SPF->new($d);
179 }
180 31 return $self->{spf};
181 }
182  
183 #warn "SPF iterative";
184 22 push @{ $self->{spf} },
185 Mail::DMARC::Report::Aggregate::Record::Auth_Results::SPF->new(@args);
186  
187 21 return $self->{spf};
188 }
189  
190 210 ▶sub policy( $self, @args ) {
Subroutine policy: called CC=3 SCAR=11.0
Pod undocumented
191 210 ▶ return $self->{policy} if ref $self->{policy} && !@args;
Branch: 1 branch
BranchTrueFalseTotal
if ref $self->{"policy"} and not @args 122 88 210
Condition100%3/3
ref $self->{"policy"} and not @args
!ll&&!rl&&r
5830122
MC/DC100%2/2
ref $self->{"policy"} and not @args
ref $self->{"policy"} not @args
Truth table100%3/3
A and not(B)
A= ref $self->{"policy"}B= not @args
ABresult
0X0
100
111
192 88 return $self->{policy} = Mail::DMARC::Policy->new(@args);
193 }
194  
195 98 ▶sub report($self) {
Subroutine report: called CC=2 SCAR=6.9
Pod undocumented
196 98 ▶ return $self->{report} if ref $self->{report};
Branch: 1 branch
BranchTrueFalseTotal
if ref $self->{"report"} 48 50 98
197 50 require Mail::DMARC::Report;
198 50 return $self->{report} = Mail::DMARC::Report->new();
199 }
200  
201 784 ▶sub result($self) {
Subroutine result: called CC=2 SCAR=6.9
Pod documented
202 784 ▶ return $self->{result} if ref $self->{result};
Branch: 1 branch
BranchTrueFalseTotal
if ref $self->{"result"} 731 53 784
203 53 return $self->{result} = Mail::DMARC::Result->new();
204 }
205  
206 159 ▶sub is_subdomain( $self, $val = undef ) {
Subroutine is_subdomain: called CC=4 SCAR=13.9
Pod undocumented
207 159 ▶ return $self->{is_subdomain} if @_ == 1;
Branch: 1 branch
BranchTrueFalseTotal
if @_ == 1 32 127 159
208 127 ▶ croak "invalid boolean" if 0 == grep {/^$val$/ix} qw/ 0 1/;
Branch: 1 branch
BranchTrueFalseTotal
if 0 == grep({/^$val$/xi;} 0, 1) 0 127 127
209 127 return $self->{is_subdomain} = $val;
210 }
211  
212 26 ▶sub get_report_window( $self, $interval = undef, $now = undef ) {
Subroutine get_report_window: called CC=10 SCAR=23.0
Pod undocumented
213 26 my $min_interval = $self->config->{'report_sending'}{'min_interval'};
214 26 my $max_interval = $self->config->{'report_sending'}{'max_interval'};
215  
216 26 ▶ $interval = 86400 if !$interval; # Default to 1 day
Branch: 1 branch
BranchTrueFalseTotal
unless $interval 11 15 26
217 26 ▶ if ($min_interval) {
Branch: 1 branch
BranchTrueFalseTotal
if ($min_interval) 5 21 26
218 5 ▶ $interval = $min_interval if $interval < $min_interval;
Branch: 1 branch
BranchTrueFalseTotal
if $interval < $min_interval 1 4 5
219 }
220 26 ▶ if ($max_interval) {
Branch: 1 branch
BranchTrueFalseTotal
if ($max_interval) 5 21 26
221 5 ▶ $interval = $max_interval if $interval > $max_interval;
Branch: 1 branch
BranchTrueFalseTotal
if $interval > $max_interval 1 4 5
222 }
223  
224 26 ▶ if ( ( 86400 % $interval ) != 0 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (86400 % $interval != 0) 2 24 26
225  
226 # Interval does not fit into a day nicely,
227 # So don't work out a window, just run with it.
228 2 return ( $now, $now + $interval - 1 );
229 }
230  
231 24 my $begin = $self->get_start_of_zulu_day($now);
232 24 my $end = $begin + $interval - 1;
233  
234 24 ▶ while ( $end < $now ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($end < $now) 5 24 29
235 5 $begin = $begin + $interval;
236 5 $end = $begin + $interval - 1;
237 }
238  
239 24 return ( $begin, $end );
240 }
241  
242 28 ▶sub get_start_of_zulu_day( $self, $t ) {
Subroutine get_start_of_zulu_day: called CC=1 SCAR=0.0
Pod undocumented
243 28 my $start_of_zulu_day = $t - ( $t % 86400 );
244 28 return $start_of_zulu_day;
245 }
246  
247 11 ▶sub save_aggregate($self) {
Subroutine save_aggregate: called CC=2 SCAR=6.9
Pod undocumented
248 11 my $agg = $self->report->aggregate;
249  
250 # put config information in report metadata
251 11 foreach my $f (qw/ org_name email extra_contact_info report_id /) {
252 44 $agg->metadata->$f( $self->config->{organization}{$f} );
253 }
254  
255 11 my ( $begin, $end )
256 = $self->get_report_window( $self->result->published->ri, $self->time );
257  
258 11 $agg->metadata->begin($begin);
259 11 $agg->metadata->end($end);
260  
261 11 $agg->policy_published( $self->result->published );
262  
263 11 my $rec = Mail::DMARC::Report::Aggregate::Record->new();
264 11 $rec->row->source_ip( $self->source_ip );
265  
266 11 $rec->identifiers(
267 envelope_to => $self->envelope_to,
268 envelope_from => $self->envelope_from,
269 header_from => $self->header_from,
270 );
271  
272 11 $rec->auth_results->dkim( $self->dkim );
273 11 $rec->auth_results->spf( $self->spf );
274  
275 11 $rec->row->policy_evaluated(
276 disposition => $self->result->disposition,
277 dkim => $self->result->dkim,
278 spf => $self->result->spf,
279 reason => $self->result->reason,
280 );
281  
282 11 $agg->record($rec);
283 11 return $self->report->save_aggregate;
284 }
285  
286 5 ▶sub init($self) {
Subroutine init: called CC=1 SCAR=0.0
Pod undocumented
287  
288 # used for testing
289 5 map { delete $self->{$_} } qw/ spf spf_ar dkim dkim_ar /;
290 5 return;
291 }
292  
293 11 1;
294  
295 __END__
296  
297 =pod
298  
299 =head1 Status Badges
300  
301 =for markdown [![Build Status](https://github.com/msimerson/mail-dmarc/actions/workflows/ci.yml/badge.svg)](https://github.com/msimerson/mail-dmarc/actions/workflows/ci.yml)
302  
303 =for markdown [![Coverage Status](https://coveralls.io/repos/msimerson/mail-dmarc/badge.svg)](https://coveralls.io/r/msimerson/mail-dmarc)
304  
305 =head1 NAME
306  
307 Mail::DMARC - Perl implementation of DMARC
308  
309 =head1 VERSION
310  
311 version 2.20260827
312  
313 =head1 SYNOPSIS
314  
315 DMARC: Domain-based Message Authentication, Reporting and Conformance
316  
317 my $dmarc = Mail::DMARC::PurePerl->new(
318 ... # see the documentation for the "new" method for required args
319 );
320  
321 my $result = $dmarc->validate();
322  
323 if ( $result->result eq 'pass' ) {
324 ...continue normal processing...
325 return;
326 };
327  
328 # any result that did not pass is a fail. Now for disposition
329  
330 if ( $result->disposition eq 'reject' ) {
331 ...treat the sender to a 550 ...
332 };
333 if ( $result->disposition eq 'quarantine' ) {
334 ...assign a bunch of spam points...
335 };
336 if ( $result->disposition eq 'none' ) {
337 ...continue normal processing...
338 };
339  
340 =head1 DESCRIPTION
341  
342 This module is a suite of tools for implementing DMARC. It implements DMARCbis (L<RFC 9989|https://www.rfc-editor.org/rfc/rfc9989>) - including the DNS tree walk for Organizational Domain discovery and the C<np>, C<psd>, and C<t> policy tags - while remaining compatible with the original L<RFC 7489|https://www.rfc-editor.org/rfc/rfc7489>. It intends to implement every MUST and every SHOULD.
343  
344 This module can be used by...
345  
346 =over 4
347  
348 =item *
349  
350 MTAs and filtering tools like SpamAssassin to validate that incoming messages are aligned with the purported sender's policy.
351  
352 =item *
353  
354 email senders, to receive DMARC reports from other mail servers and display them via CLI and web interfaces.
355  
356 =item *
357  
358 MTA operators to send DMARC reports to DMARC author domains.
359  
360 =back
361  
362 When a message arrives via SMTP, the MTA or filtering application can pass in a small amount of metadata about the connection (envelope details, SPF and DKIM results) to Mail::DMARC. When the B<validate> method is called, Mail::DMARC will determine if:
363  
364 a. the header_from domain exists
365 b. the header_from domain publishes a DMARC policy
366 c. if a policy is published...
367 d. does the message conform to the published policy?
368 e. did the policy request reporting? If so, save details.
369  
370 The validation results are returned as a L<Mail::DMARC::Result> object. If the author domain requested a report, it was saved to the L<Report Store|Mail::DMARC::Report::Store>. The Store class includes a SQL implementation that is tested with SQLite, MySQL and PostgreSQL.
371  
372 There is more information available in the $result object. See L<Mail::DMARC::Result> for complete details.
373  
374 Reports are viewed with the L<dmarc_view_reports> program or with a web browser and the L<dmarc_httpd> program.
375  
376 Aggregate reports are sent to their requestors with the L<dmarc_send_reports> program.
377  
378 For aggregate reports that you have been sent, the L<dmarc_receive> program will parse the email messages (from IMAP, Mbox, or files) and save the report results into the L<Report Store|Mail::DMARC::Report::Store>.
379  
380 The report store can use the same database to store reports you have received as well as reports you will send. There are several ways to identify the difference, including:
381  
382 =over 4
383  
384 =item *
385  
386 received reports will have a null value for report_policy_published.rua
387  
388 =item *
389  
390 outgoing reports will have null values for report.uuid and report_record.count
391  
392 =back
393  
394 =head1 CLASSES
395  
396 L<Mail::DMARC> - the perl interface for DMARC
397  
398 L<Mail::DMARC::Policy> - a DMARC policy
399  
400 L<Mail::DMARC::PurePerl> - Pure Perl implementation of DMARC
401  
402 L<Mail::DMARC::Result> - the results of applying policy
403  
404 L<Mail::DMARC::Report> - Reporting: the R in DMARC
405  
406 =over 2
407  
408 L<Mail::DMARC::Report::Send> - send reports via SMTP & HTTP
409  
410 L<Mail::DMARC::Report::Receive> - receive and store reports from email, HTTP
411  
412 L<Mail::DMARC::Report::Store> - a persistent data store for aggregate reports
413  
414 L<Mail::DMARC::Report::View> - CLI and CGI methods for viewing reports
415  
416 =back
417  
418 L<Mail::DMARC::libopendmarc|https://metacpan.org/pod/Mail::DMARC::libopendmarc> - an XS implementation using libopendmarc
419  
420 =head1 METHODS
421  
422 =head2 new
423  
424 Create a DMARC object.
425  
426 my $dmarc = Mail::DMARC::PurePerl->new;
427  
428 Populate it.
429  
430 $dmarc->source_ip('192.0.1.1');
431 $dmarc->envelope_to('recipient.example.com');
432 $dmarc->envelope_from('sender.example.com');
433 $dmarc->header_from('sender.example.com');
434 $dmarc->dkim( $dkim_verifier );
435 $dmarc->spf([
436 { domain => 'example.com',
437 scope => 'mfrom',
438 result => 'pass',
439 },
440 {
441 scope => 'helo',
442 domain => 'mta.example.com',
443 result => 'fail',
444 },
445 ]);
446  
447 Run the request:
448  
449 my $result = $dmarc->validate();
450  
451 Alternatively, pass in all the required parameters in one shot:
452  
453 my $dmarc = Mail::DMARC::PurePerl->new(
454 source_ip => '192.0.1.1',
455 envelope_to => 'example.com',
456 envelope_from => 'cars4you.info',
457 header_from => 'yahoo.com',
458 dkim => $dkim_results, # same format
459 spf => $spf_results, # as previous example
460 );
461 my $result = $dmarc->validate();
462  
463 =head2 source_ip
464  
465 The remote IP that attempted sending the message. DMARC only uses this data for reporting to domains that request DMARC reports.
466  
467 =head2 envelope_to
468  
469 The domain portion of the RFC5321.RcptTo, (aka, the envelope recipient), and the bold portion in the following example:
470  
471 =over 8
472  
473 RCPT TO:&lt;user@B<example.com>>
474  
475 =back
476  
477 =head2 envelope_from
478  
479 The domain portion of the RFC5321.MailFrom, (aka, the envelope sender). That is the the bold portion in the following example:
480  
481 =over 8
482  
483 MAIL FROM:&lt;user@B<example.com>>
484  
485 =back
486  
487 =head2 header_from
488  
489 The domain portion of the RFC5322.From, aka, the From message header.
490  
491 =over 8
492  
493 From: Ultimate Vacation &lt;sweepstakes@B<example.com>>
494  
495 =back
496  
497 You can instead pass in the entire From: header with header_from_raw.
498  
499 =head2 header_from_raw
500  
501 Retrieve the header_from domain by parsing it from a raw From field/header. The domain portion is extracted by L<get_dom_from_header|Mail::DMARC::PurePerl#get_dom_from_header>, which is fast, generally effective, but also rather crude. It has limits, so read the description.
502  
503 =head2 dkim
504  
505 If Mail::DKIM::Verifier was used to validate the message, just pass in the Mail::DKIM::Verifier object that processed the message:
506  
507 $dmarc->dkim( $dkim_verifier );
508  
509 Otherwise, pass in an array reference. Each member of the DKIM array results represents a DKIM signature in the message and consists of the 4 keys shown in this example:
510  
511 $dmarc->dkim( [
512 {
513 domain => 'example.com',
514 selector => 'apr2013',
515 result => 'fail',
516 human_result=> 'fail (body has been altered)',
517 },
518 {
519 # 2nd signature, if present
520 },
521 ] );
522  
523 The dkim results can also be build iteratively by passing in key value pairs or hash references for each signature in the message:
524  
525 $dmarc->dkim( domain => 'sig1.com', result => 'fail' );
526 $dmarc->dkim( domain => 'sig2.com', result => 'pass' );
527 $dmarc->dkim( { domain => 'example.com', result => 'neutral' } );
528  
529 Each hash or hashref is appended to the dkim array.
530  
531 Finally, you can pass a coderef which won't be called until the dkim method is used to read the dkim results. It must return an array reference as described above.
532  
533 The dkim result is an array reference.
534  
535 =head3 domain
536  
537 The d= parameter in the DKIM signature
538  
539 =head3 selector
540  
541 The s= parameter in the DKIM signature
542  
543 =head3 result
544  
545 The validation results of this signature. One of: none, pass, fail, policy, neutral, temperror, or permerror
546  
547 =head3 human result
548  
549 Additional information about the DKIM result. This is comparable to Mail::DKIM::Verifier->result_detail.
550  
551 =head2 spf
552  
553 The spf method works exactly the same as dkim. It accepts named arguments, a hashref, an arrayref, or a coderef:
554  
555 $dmarc->spf(
556 domain => 'example.com',
557 scope => 'mfrom',
558 result => 'pass',
559 );
560  
561 The SPF domain and result are required for DMARC validation and the scope is used for reporting.
562  
563 =head3 domain
564  
565 The SPF checked domain
566  
567 =head3 scope
568  
569 The scope of the checked domain: mfrom, helo
570  
571 =head3 result
572  
573 The SPF result code: none, neutral, pass, fail, softfail, temperror, or permerror.
574  
575 =head1 DESIGN & GOALS
576  
577 =head2 Correct
578  
579 The DMARC spec is lengthy and evolving, making correctness a moving target. In cases where correctness is ambiguous, options are generally provided.
580  
581 =head2 Easy to use
582  
583 Providing an implementation of DMARC that SMTP utilities can utilize will aid DMARC adoption.
584  
585 The list of dependencies appears long because of reporting. If this module is used without reporting, the number of dependencies not included with perl is about 5.
586  
587 =head2 Maintainable
588  
589 Since DMARC is evolving, this implementation aims to be straight forward and easy to alter and extend. The programming style is primarily OO, which carries a small performance penalty but dividends in maintainability.
590  
591 When multiple options are available, such as when sending reports via SMTP or HTTP, calls should be made to the parent Send class to broker the request. When storing reports, calls are made to the Store class which dispatches to the SQL class. The idea is that if someone desired a data store other than those provided by perl's DBI class, they could easily implement their own. If you do, please fork it on GitHub and share.
592  
593 =head2 Fast
594  
595 If you deploy this in an environment where performance is insufficient, please profile the app and submit a report and preferably, patches.
596  
597 =head1 SEE ALSO
598  
599 L<Mail::DMARC on GitHub|https://github.com/msimerson/mail-dmarc>
600  
601 L<RFC 9989|https://www.rfc-editor.org/rfc/rfc9989> - DMARCbis, the current DMARC standard
602  
603 L<RFC 7489|https://www.rfc-editor.org/rfc/rfc7489> - the original (2015) DMARC specification
604  
605 =head1 HISTORY
606  
607 The daddy of this perl module was a L<DMARC module for the qpsmtpd MTA|https://github.com/smtpd/qpsmtpd/blob/master/plugins/dmarc>.
608  
609 =head1 AUTHORS
610  
611 =over 4
612  
613 =item *
614  
615 Matt Simerson <msimerson@cpan.org>
616  
617 =item *
618  
619 Davide Migliavacca <shari@cpan.org>
620  
621 =item *
622  
623 Marc Bradshaw <marc@marcbradshaw.net>
624  
625 =back
626  
627 =head1 CONTRIBUTORS
628  
629 =for stopwords Benny Pedersen Jean Paul Galea Marisa Clardy Priyadi Iman Nurcahyo Ricardo Signes
630  
631 =over 4
632  
633 =item *
634  
635 Benny Pedersen <me@junc.eu>
636  
637 =item *
638  
639 Jean Paul Galea <jeanpaul@yubico.com>
640  
641 =item *
642  
643 Marisa Clardy <marisa@clardy.eu>
644  
645 =item *
646  
647 Priyadi Iman Nurcahyo <priyadi@priyadi.net>
648  
649 =item *
650  
651 Ricardo Signes <rjbs@cpan.org>
652  
653 =back
654  
655 =head1 COPYRIGHT AND LICENSE
656  
657 This software is copyright (c) 2026 by Matt Simerson.
658  
659 This is free software; you can redistribute it and/or modify it under
660 the same terms as the Perl 5 programming language system itself.
661  
662 =cut
« blib/lib/Mail/DMARC/Report/Aggregate/Metadata.pm ↑ Summary lib/Mail/DMARC/Report/Aggregate/Record/Auth_Results/SPF.pm »