SPF/Record.pm

filter: Statementstmt 21.9% 31 / 141 Branchbran 0.0% 0 / 54 Conditioncond 0.0% 0 / 4 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 40.0% 10 / 25 Podpod 61.5% 8 / 13 totaltotal 20.5% 49 / 239 CC 33 SCAR 41.1
CC
33
Cov
16%
__ANON__
182.0
parse_term
90.0
new
30.0
CRAP 60.8
« SPF/Util.pm ↑ Summary SPF/v1/Record.pm »
1 #
2 # Mail::SPF::Record
3 # Abstract base class for SPF records.
4 #
5 # (C) 2005-2012 Julian Mehnle <julian@mehnle.net>
6 # 2005 Shevek <cpan@anarres.org>
7 # $Id: Record.pm 57 2012-01-30 08:15:31Z julian $
8 #
9 ##############################################################################
10  
11 package Mail::SPF::Record;
12  
13 =head1 NAME
14  
15 Mail::SPF::Record - Abstract base class for SPF records
16  
17 =head1 VERSION
18  
19 version 3.20260331
20  
21 =cut
22  
23 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
24 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
25  
26 3 ▶use utf8; # Hack to keep Perl 5.6 from whining about /[\p{}]/.
Subroutine BEGIN: called CC=1 SCAR=0.0
27  
28 3 ▶use base 'Mail::SPF::Base';
Subroutine BEGIN: called CC=1 SCAR=0.0
29  
30 use overload
31 3 ▶ '""' => 'stringify',
Subroutine BEGIN: called CC=1 SCAR=0.0
32 3 fallback => 1;
33  
34 3 ▶use Error ':try';
Subroutine BEGIN: called CC=1 SCAR=0.0
35  
36 3 ▶use constant TRUE => (0 == 0);
Subroutine BEGIN: called CC=1 SCAR=0.0
37 3 ▶use constant FALSE => not TRUE;
Subroutine BEGIN: called CC=1 SCAR=0.0
38  
39 3 ▶use constant default_qualifier => '+';
Subroutine BEGIN: called CC=1 SCAR=0.0
40  
41 3 ▶use constant results_by_qualifier => {
Subroutine BEGIN: called CC=1 SCAR=0.0
42 '' => 'pass',
43 '+' => 'pass',
44 '-' => 'fail',
45 '~' => 'softfail',
46 '?' => 'neutral'
47 3 };
48  
49 # Interface:
50 ##############################################################################
51  
52 =head1 SYNOPSIS
53  
54 =head2 Creating a record from a string
55  
56 use Mail::SPF::v1::Record;
57  
58 my $record = Mail::SPF::v1::Record->new_from_string("v=spf1 a mx -all");
59  
60 =head2 Creating a record synthetically
61  
62 use Mail::SPF::v2::Record;
63  
64 my $record = Mail::SPF::v2::Record->new(
65 scopes => ['mfrom', 'pra'],
66 terms => [
67 Mail::SPF::Mech::A->new(),
68 Mail::SPF::Mech::MX->new(),
69 Mail::SPF::Mech::All->new(qualifier => '-')
70 ],
71 global_mods => [
72 Mail::SPF::Mod::Exp->new(domain_spec => 'spf-exp.example.com')
73 ]
74 );
75  
76 =cut
77  
78 # Implementation:
79 ##############################################################################
80  
81 =head1 DESCRIPTION
82  
83 B<Mail::SPF::Record> is an abstract base class for SPF records. It cannot be
84 instantiated directly. Create an instance of a concrete sub-class instead.
85  
86 =head2 Constructor
87  
88 The following constructors are provided:
89  
90 =over
91  
92 =item B<new(%options)>: returns I<Mail::SPF::Record>
93  
94 Creates a new SPF record object.
95  
96 %options is a list of key/value pairs representing any of the following
97 options:
98  
99 =over
100  
101 =item B<text>
102  
103 A I<string> denoting the unparsed text of the record.
104  
105 =item B<scopes>
106  
107 A reference to an I<array> of I<string>s denoting the scopes that are covered
108 by the record (see the description of the C<scope> option of
109 L<Mail::SPF::Request's C<new> constructor|Mail::SPF::Request/new>).
110  
111 =item B<terms>
112  
113 A reference to an I<array> of I<Mail::SPF::Term> (i.e. I<Mail::SPF::Mech> or
114 I<Mail::SPF::Mod>) objects that make up the record. I<Mail::SPF::GlobalMod>
115 objects must not be included here, but should be specified using the
116 C<global_mods> option instead.
117  
118 =item B<global_mods>
119  
120 A reference to an I<array> of I<Mail::SPF::GlobalMod> objects that are global
121 modifiers of the record.
122  
123 =back
124  
125 =cut
126  
127 0 ▶sub new {
Subroutine new: not called CC=5 SCAR=34.0
Pod documented
128 0 my ($self, %options) = @_;
129 0 ▶ $self->class ne __PACKAGE__
Branch: 1 branch
BranchTrueFalseTotal
$self->class ne __PACKAGE__ or "Mail::SPF::EAbstractClass"->throw 0 0 0
130 or throw Mail::SPF::EAbstractClass;
131 0 $self = $self->SUPER::new(%options);
132 0 ▶ $self->{parse_text} = $self->{text} if not defined($self->{parse_text});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"parse_text"} 0 0 0
133 0 ▶ $self->{terms} ||= [];
Condition0%0/2
$self->{"terms"} ||= []
l!l
00
MC/DC0%0/1
$self->{"terms"} ||= []
$self->{"terms"}
Truth table0%0/2
A
A= $self->{"terms"}
Aresult
11
00
134 0 ▶ $self->{global_mods} ||= {};
Condition0%0/2
$self->{"global_mods"} ||= {}
l!l
00
MC/DC0%0/1
$self->{"global_mods"} ||= {}
$self->{"global_mods"}
Truth table0%0/2
A
A= $self->{"global_mods"}
Aresult
11
00
135 0 return $self;
136 }
137  
138 =item B<new_from_string($text, %options)>: returns I<Mail::SPF::Record>;
139 throws I<Mail::SPF::ENothingToParse>, I<Mail::SPF::EInvalidRecordVersion>,
140 I<Mail::SPF::ESyntaxError>
141  
142 Creates a new SPF record object by parsing the string and any options given.
143  
144 =cut
145  
146 0 ▶sub new_from_string {
Subroutine new_from_string: not called CC=1 SCAR=6.9
Pod documented
147 0 my ($self, $text, %options) = @_;
148 0 $self = $self->new(%options, text => $text);
149 0 $self->parse();
150 0 return $self;
151 }
152  
153 =back
154  
155 =head2 Class methods
156  
157 The following class methods are provided:
158  
159 =over
160  
161 =item B<version_tag_pattern>: returns I<Regexp>
162  
163 I<Abstract>. Returns a regular expression that matches a legal version tag.
164  
165 This method is abstract and must be implemented by sub-classes of
166 Mail::SPF::Record.
167  
168 =item B<default_qualifier>: returns I<string>
169  
170 Returns the default qualifier, i.e. B<'+'>.
171  
172 =item B<results_by_qualifier>: returns I<hash> of I<string>
173  
174 Returns a reference to a hash that maps qualifiers to result codes as follows:
175  
176 Qualifier | Result code
177 -----------+-------------
178 + | pass
179 - | fail
180 ~ | softfail
181 ? | neutral
182  
183 =back
184  
185 =head2 Instance methods
186  
187 The following instance methods are provided:
188  
189 =over
190  
191 =cut
192  
193 0 ▶sub parse {
Subroutine parse: not called CC=3 SCAR=24.8
Pod undocumented
194 0 my ($self) = @_;
195 defined($self->{parse_text})
196 0 ▶ or throw Mail::SPF::ENothingToParse('Nothing to parse for record');
Branch: 1 branch
BranchTrueFalseTotal
defined $self->{"parse_text"} or "Mail::SPF::ENothingToParse"->throw("Nothing to parse for record") 0 0 0
197 0 $self->parse_version_tag();
198 0 ▶ $self->parse_term() while length($self->{parse_text});
Branch: 1 branch
BranchTrueFalseTotal
length $self->{"parse_text"} and do { $self->parse_term } 0 0 0
199 0 $self->parse_end();
200 0 return;
201 }
202  
203 0 ▶sub parse_version_tag {
Subroutine parse_version_tag: not called CC=2 SCAR=17.9
Pod undocumented
204 0 my ($self) = @_;
205 0 ▶ if (not $self->{parse_text} =~ s/^${\$self->version_tag_pattern}(?:\x20+|$)//) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $self->{"parse_text"} =~ s/^${\$self->version_tag_pattern;}(?:\x20+|$)//) 0 0 0
206 0 throw Mail::SPF::EInvalidRecordVersion(
207 "Not a '" . $self->version_tag . "' record: '" . $self->text . "'");
208 }
209 }
210  
211 0 ▶sub parse_term {
Subroutine parse_term: not called CC=9 SCAR=45.0
Pod undocumented
212 0 my ($self) = @_;
213  
214 0 eval {
215 0 require Mail::SPF::Mech;
216 };
217 0 ▶ if($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 0 0
218 0 throw Mail::SPF::ENothingToParse('Cannot load Mail::SPF::Mech class');
219 }
220 0 ▶ if (
Branch: 2 branches
BranchTrueFalseTotal
if ($self->{'parse_text'} =~ s/ ^ ( ${\'Mail::SPF::Mech'->qualifier_pattern;}? (${\'Mail::SPF::Mech'->name_pattern;}) [^\x20]* ) (?: \x20+ | $ ) //x) { } 0 0 0
elsif ($self->{'parse_text'} =~ s/ ^ ( (${\'Mail::SPF::Mod'->name_pattern;}) = [^\x20]* ) (?: \x20+ | $ ) //x) { } 0 0 0
221 $self->{parse_text} =~ s/
222 ^
223 (
224 0 ${\Mail::SPF::Mech->qualifier_pattern}?
225 0 (${\Mail::SPF::Mech->name_pattern})
226 [^\x20]*
227 )
228 (?: \x20+ | $ )
229 //x
230 ) {
231 # Looks like a mechanism:
232 0 my ($mech_text, $mech_name) = ($1, lc($2));
233 0 my $mech_class = $self->mech_classes->{$mech_name};
234 0 ▶ throw Mail::SPF::EInvalidMech("Unknown mechanism type '$mech_name' in '" . $self->version_tag . "' record")
Branch: 1 branch
BranchTrueFalseTotal
unless defined $mech_class 0 0 0
235 if not defined($mech_class);
236 0 my $mech = $mech_class->new_from_string($mech_text);
237 0 push(@{$self->{terms}}, $mech);
238 }
239 elsif (
240 $self->{parse_text} =~ s/
241 ^
242 (
243 0 (${\Mail::SPF::Mod->name_pattern}) =
244 [^\x20]*
245 )
246 (?: \x20+ | $ )
247 //x
248 ) {
249 # Looks like a modifier:
250 0 my ($mod_text, $mod_name) = ($1, lc($2));
251 0 my $mod_class = $self->mod_classes->{$mod_name};
252 0 ▶ if (defined($mod_class)) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $mod_class) { } 0 0 0
253 # Known modifier.
254 0 my $mod = $mod_class->new_from_string($mod_text);
255 0 ▶ if ($mod->isa('Mail::SPF::GlobalMod')) {
Branch: 2 branches
BranchTrueFalseTotal
if ($mod->isa('Mail::SPF::GlobalMod')) { } 0 0 0
elsif ($mod->isa('Mail::SPF::PositionalMod')) { } 0 0 0
256 # Global modifier.
257 0 ▶ not defined($self->{global_mods}->{$mod_name}) or
Branch: 1 branch
BranchTrueFalseTotal
defined $self->{"global_mods"}{$mod_name} and "Mail::SPF::EDuplicateGlobalMod"->throw("Duplicate global modifier '${mod_name}' encountered") 0 0 0
258 throw Mail::SPF::EDuplicateGlobalMod("Duplicate global modifier '$mod_name' encountered");
259 0 $self->{global_mods}->{$mod_name} = $mod;
260 }
261 elsif ($mod->isa('Mail::SPF::PositionalMod')) {
262 # Positional modifier, queue normally:
263 0 push(@{$self->{terms}}, $mod);
264 }
265 else {
266 # Huh? This should not happen.
267 }
268 }
269 else {
270 # Unknown modifier.
271 0 my $mod = Mail::SPF::UnknownMod->new_from_string($mod_text);
272 0 push(@{$self->{terms}}, $mod);
273 }
274 }
275 else {
276 0 throw Mail::SPF::EJunkInRecord("Junk encountered in record '" . $self->text . "'");
277 }
278 0 return;
279 }
280  
281 0 ▶sub parse_end {
Subroutine parse_end: not called CC=2 SCAR=17.9
Pod undocumented
282 0 my ($self) = @_;
283 throw Mail::SPF::EJunkInRecord("Junk encountered in record '" . $self->text . "'")
284 0 ▶ if $self->{parse_text} ne '';
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"parse_text"} ne "" 0 0 0
285 0 delete($self->{parse_text});
286 0 return;
287 }
288  
289 =item B<text>: returns I<string>; throws I<Mail::SPF::ENoUnparsedText>
290  
291 Returns the unparsed text of the record. Throws a I<Mail::SPF::ENoUnparsedText>
292 exception if the record was created synthetically instead of being parsed, and
293 no text was provided.
294  
295 =cut
296  
297 0 ▶sub text {
Subroutine text: not called CC=2 SCAR=17.9
Pod documented
298 0 my ($self) = @_;
299 defined($self->{text})
300 0 ▶ or throw Mail::SPF::ENoUnparsedText;
Branch: 1 branch
BranchTrueFalseTotal
defined $self->{"text"} or "Mail::SPF::ENoUnparsedText"->throw 0 0 0
301 0 return $self->{text};
302 }
303  
304 =item B<version_tag>: returns I<string>
305  
306 I<Abstract>. Returns the version tag of the record.
307  
308 This method is abstract and must be implemented by sub-classes of
309 Mail::SPF::Record.
310  
311 =item B<scopes>: returns I<list> of I<string>
312  
313 Returns a list of the scopes that are covered by the record. See the
314 description of the L</new> constructor's C<scopes> option.
315  
316 =cut
317  
318 0 ▶sub scopes {
Subroutine scopes: not called CC=1 SCAR=6.9
Pod documented
319 0 my ($self) = @_;
320 0 return @{$self->{scopes}};
321 }
322  
323 =item B<terms>: returns I<list> of I<Mail::SPF::Term>
324  
325 Returns a list of the terms that make up the record, excluding any global
326 modifiers, which are returned by the C<global_mods> method. See the
327 description of the L</new> constructor's C<terms> option.
328  
329 =cut
330  
331 0 ▶sub terms {
Subroutine terms: not called CC=1 SCAR=6.9
Pod documented
332 0 my ($self) = @_;
333 0 return @{$self->{terms}};
334 }
335  
336 =item B<global_mods>: returns I<list> of I<Mail::SPF::GlobalMod>
337  
338 Returns a list of the global modifiers of the record, ordered ascending by
339 modifier precedence. See the description of the L</new> constructor's
340 C<global_mods> option.
341  
342 =cut
343  
344 0 ▶sub global_mods {
Subroutine global_mods: not called CC=1 SCAR=6.9
Pod documented
345 0 my ($self) = @_;
346 0 return sort { $a->precedence <=> $b->precedence } values(%{$self->{global_mods}});
347 }
348  
349 =item B<global_mod($mod_name)>: returns I<Mail::SPF::GlobalMod>
350  
351 Returns the global modifier of the given name if it is present in the record.
352 Returns B<undef> otherwise. Use this method if you wish to retrieve a specific
353 global modifier as opposed to getting all of them.
354  
355 =cut
356  
357 0 ▶sub global_mod {
Subroutine global_mod: not called CC=1 SCAR=6.9
Pod documented
358 0 my ($self, $mod_name) = @_;
359 0 return $self->{global_mods}->{$mod_name};
360 }
361  
362 =item B<stringify>: returns I<string>
363  
364 Returns the record's version tag and terms (including the global modifiers)
365 formatted as a string. You can simply use a Mail::SPF::Record object as a
366 string for the same effect, see L<"OVERLOADING">.
367  
368 =cut
369  
370 0 ▶sub stringify {
Subroutine stringify: not called CC=1 SCAR=6.9
Pod undocumented
371 0 my ($self) = @_;
372 0 return join(' ', $self->version_tag, $self->terms, $self->global_mods);
373 }
374  
375 =item B<eval($server, $request)>: throws I<Mail::SPF::Result>
376  
377 Evaluates the SPF record in the context of the request parameters represented
378 by the given I<Mail::SPF::Request> object. The given I<Mail::SPF::Server>
379 object is used for performing DNS look-ups. Throws a I<Mail::SPF::Result>
380 object matching the outcome of the evaluation; see L<Mail::SPF::Result>. See
381 RFC 4408, 4.6 and 4.7, for the exact algorithm used.
382  
383 =cut
384  
385 0 ▶sub eval {
Subroutine eval: not called CC=3 SCAR=24.8
Pod documented
386 0 my ($self, $server, $request) = @_;
387  
388 0 ▶ defined($server)
Branch: 1 branch
BranchTrueFalseTotal
defined $server or "Mail::SPF::EOptionRequired"->throw("Mail::SPF server object required for record evaluation") 0 0 0
389 or throw Mail::SPF::EOptionRequired('Mail::SPF server object required for record evaluation');
390 0 ▶ defined($request)
Branch: 1 branch
BranchTrueFalseTotal
defined $request or "Mail::SPF::EOptionRequired"->throw("Request object required for record evaluation") 0 0 0
391 or throw Mail::SPF::EOptionRequired('Request object required for record evaluation');
392  
393 0 ▶ try {
Subroutine __ANON__: not called CC=13 SCAR=52.0
394 0 my @include_domains;
395 my %inc_domain_cname;
396 0 foreach my $term ($self->terms) {
397 0 ▶ if ($term->isa('Mail::SPF::Mech')) {
Branch: 3 branches
BranchTrueFalseTotal
if ($term->isa('Mail::SPF::Mech')) { } 0 0 0
elsif ($term->isa('Mail::SPF::PositionalMod')) { } 0 0 0
elsif ($term->isa('Mail::SPF::UnknownMod')) { } 0 0 0
398 # Term is a mechanism.
399 0 my $mech = $term;
400 0 ▶ if($term->name eq "include") {
Branch: 1 branch
BranchTrueFalseTotal
if ($term->name eq "include") 0 0 0
401 0 ▶ if($term->{domain_spec}->{text} =~ /%/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($term->{'domain_spec'}{'text'} =~ /%/) { } 0 0 0
402 my $macrostring = Mail::SPF::MacroString->new(
403 text => $term->{domain_spec}->{text} ,
404 0 server => $server,
405 request => $request
406 );
407 0 my $expanded = $macrostring->expand;
408 0 push(@include_domains, $expanded);
409 } else {
410 0 push(@include_domains, $term->{domain_spec}->{text});
411 }
412 0 ▶ if(scalar @include_domains > 1) {
Branch: 1 branch
BranchTrueFalseTotal
if (scalar @include_domains > 1) 0 0 0
413 0 foreach my $dom ( @include_domains ) {
414 0 my $packet;
415 0 ▶ if(not exists $inc_domain_cname{$dom}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $inc_domain_cname{$dom}) 0 0 0
416 0 $packet = $server->dns_lookup($dom, 'CNAME');
417 0 $inc_domain_cname{$dom} = $packet->{answer}[0]->{cname}->{name};
418 }
419 0 ▶ if(defined $inc_domain_cname{$dom}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $inc_domain_cname{$dom}) 0 0 0
420 0 ▶ if(grep /^$inc_domain_cname{$dom}$/, @include_domains) {
Branch: 1 branch
BranchTrueFalseTotal
if (grep /^$inc_domain_cname{$dom}$/, @include_domains) 0 0 0
421 0 $server->throw_result('fail', $request,
422 'referencing the same TXT record through multiple CNAME aliases is not permitted');
423 }
424 }
425 }
426 }
427 }
428 0 ▶ if ($mech->match($server, $request)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($mech->match($server, $request)) 0 0 0
429 0 my $result_name = $self->results_by_qualifier->{$mech->qualifier};
430 0 my $result_class = $server->result_class($result_name);
431 0 my $result = $result_class->new($server, $request, "Mechanism '$term' matched");
432 0 $mech->explain($server, $request, $result);
433 0 $result->throw();
434 }
435 }
436 elsif ($term->isa('Mail::SPF::PositionalMod')) {
437 # Term is a positional modifier.
438 0 my $mod = $term;
439 0 $mod->process($server, $request);
440 }
441 elsif ($term->isa('Mail::SPF::UnknownMod')) {
442 # Term is an unknown modifier. Ignore it (RFC 4408, 6/3).
443 }
444 else {
445 # Invalid term object encountered:
446 0 throw Mail::SPF::EUnexpectedTermObject(
447 "Unexpected term object '$term' encountered");
448 }
449 }
450 0 undef @include_domains;
451 0 undef %inc_domain_cname;
452  
453 # Default result when "falling off" the end of the record (RFC 4408, 4.7/1):
454 0 $server->throw_result('neutral-by-default', $request,
455 'Default neutral result due to no mechanism matches');
456 }
457 0 ▶ catch Mail::SPF::Result with {
Subroutine __ANON__: not called CC=2 SCAR=17.9
458 0 my ($result) = @_;
459  
460 # Process global modifiers in ascending order of precedence:
461 0 foreach my $global_mod ($self->global_mods) {
462 0 $global_mod->process($server, $request, $result);
463 }
464  
465 0 $result->throw();
466 0 };
467 }
468  
469 =back
470  
471 =head1 OVERLOADING
472  
473 If a Mail::SPF::Record object is used as a I<string>, the C<stringify> method
474 is used to convert the object into a string.
475  
476 =head1 SEE ALSO
477  
478 L<Mail::SPF>, L<Mail::SPF::v1::Record>, L<Mail::SPF::v2::Record>,
479 L<Mail::SPF::Term>, L<Mail::SPF::Mech>, L<Mail::SPF::Mod>
480  
481 L<http://tools.ietf.org/html/rfc4408>
482  
483 For availability, support, and license information, see the README file
484 included with Mail::SPF.
485  
486 =head1 AUTHORS
487  
488 Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>
489  
490 =cut
491  
492 3 TRUE;
« SPF/Util.pm ↑ Summary SPF/v1/Record.pm »