SPF/Mech.pm

filter: Statementstmt 93.3% 113 / 121 Branchbran 52.0% 25 / 48 Conditioncond 44.4% 4 / 9 MC/DCmcdc 0.0% 0 / 6 Subroutinesub 90.6% 29 / 32 Podpod 50.0% 6 / 12 totaltotal 77.6% 177 / 228 CC 29 SCAR 15.8
CC
29
Cov
80%
match_in_domain
16.4
parse_params
6.0
new
5.9
CRAP 4.9
« SPF/Term.pm ↑ Summary SPF/Server.pm »
1 #
2 # Mail::SPF::Mech
3 # SPF record mechanism class.
4 #
5 # (C) 2005-2012 Julian Mehnle <julian@mehnle.net>
6 # 2005 Shevek <cpan@anarres.org>
7 # $Id: Mech.pm 57 2012-01-30 08:15:31Z julian $
8 #
9 ##############################################################################
10  
11 package Mail::SPF::Mech;
12  
13 =head1 NAME
14  
15 Mail::SPF::Mech - SPF record mechanism base class
16  
17 =head1 VERSION
18  
19 version 3.20261105
20  
21 =cut
22  
23 6 our $VERSION = '3.20261105'; # VERSION
24  
25 6 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
26 6 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
27  
28 6 ▶use utf8; # Hack to keep Perl 5.6 from whining about /[\p{}]/.
Subroutine BEGIN: called CC=1 SCAR=0.0
29  
30 6 ▶use base 'Mail::SPF::Term';
Subroutine BEGIN: called CC=1 SCAR=0.0
31  
32 6 ▶use Error ':try';
Subroutine BEGIN: called CC=1 SCAR=0.0
33 6 ▶use NetAddr::IP;
Subroutine BEGIN: called CC=1 SCAR=0.0
34  
35 6 ▶use Mail::SPF::Record;
Subroutine BEGIN: called CC=1 SCAR=0.0
36 6 ▶use Mail::SPF::MacroString;
Subroutine BEGIN: called CC=1 SCAR=0.0
37 6 ▶use Mail::SPF::Util;
Subroutine BEGIN: called CC=1 SCAR=0.0
38  
39 6 ▶use constant TRUE => (0 == 0);
Subroutine BEGIN: called CC=1 SCAR=0.0
40 6 ▶use constant FALSE => not TRUE;
Subroutine BEGIN: called CC=1 SCAR=0.0
41  
42 6 ▶use constant default_qualifier => Mail::SPF::Record->default_qualifier;
Subroutine BEGIN: called CC=1 SCAR=0.0
43 6 ▶use constant default_ipv4_prefix_length => 32;
Subroutine BEGIN: called CC=1 SCAR=0.0
44 6 ▶use constant default_ipv6_prefix_length => 128;
Subroutine BEGIN: called CC=1 SCAR=0.0
45  
46 6 ▶use constant qualifier_pattern => qr/[+\-~?]/;
Subroutine BEGIN: called CC=1 SCAR=0.0
47 6 ▶use constant name_pattern => qr/ ${\__PACKAGE__->SUPER::name_pattern} (?= [:\/\x20] | $ ) /x;
Subroutine BEGIN: called CC=1 SCAR=0.0
48  
49 6 ▶use constant explanation_templates_by_result_code => {
Subroutine BEGIN: called CC=1 SCAR=0.0
50 pass => "Sender is authorized to use '%{s}' in '%{_scope}' identity",
51 fail => "Sender is not authorized to use '%{s}' in '%{_scope}' identity",
52 softfail => "Sender is not authorized to use '%{s}' in '%{_scope}' identity, however domain is not currently prepared for false failures",
53 neutral => "Domain does not state whether sender is authorized to use '%{s}' in '%{_scope}' identity"
54 6 };
55  
56 =head1 DESCRIPTION
57  
58 An object of class B<Mail::SPF::Mech> represents a mechanism within an SPF
59 record. Mail::SPF::Mech cannot be instantiated directly. Create an instance
60 of a concrete sub-class instead.
61  
62 =head2 Constructors
63  
64 The following constructors are provided:
65  
66 =over
67  
68 =item B<new(%options)>: returns I<Mail::SPF::Mech>
69  
70 I<Abstract>. Creates a new SPF record mechanism object.
71  
72 %options is a list of key/value pairs representing any of the following
73 options:
74  
75 =over
76  
77 =item B<text>
78  
79 A I<string> denoting the unparsed text of the mechanism.
80  
81 =item B<qualifier>
82  
83 A single-character I<string> denoting the qualifier of the mechanism. Any of
84 the following may be specified: B<'+'> (C<Pass>), B<'-'> (C<Fail>),
85 B<'~'> (C<SoftFail>), B<'?'> (C<Neutral>). See RFC 4408, 4.6.2 and 2.5, for
86 their meanings. Defaults to B<'+'>.
87  
88 =item B<name>
89  
90 A I<string> denoting the name of the mechanism. I<Required> if a generic
91 I<Mail::SPF::Mech> object (as opposed to a specific sub-class) is being
92 constructed.
93  
94 =item B<ip_network>
95  
96 A I<NetAddr::IP> object denoting an optional IP address network parameter of
97 the mechanism. Can be either an IPv4 or an IPv6 address, with an optional
98 network prefix length. IPv4-mapped IPv6 addresses (e.g. '::ffff:192.168.0.1')
99 must I<not> be specified directly, but as plain IPv4 addresses.
100  
101 =item B<domain_spec>
102  
103 Either a plain I<string> or a I<Mail::SPF::MacroString> object denoting an
104 optional C<domain-spec> parameter of the mechanism.
105  
106 =item B<ipv4_prefix_length>
107  
108 =item B<ipv6_prefix_length>
109  
110 A I<string> denoting an optional IPv4 or IPv6 network prefix length for the
111 C<domain_spec> of the mechanism. Note that these options do not apply to the
112 C<ip_network> option, which already includes an optional network prefix
113 length.
114  
115 =back
116  
117 Other options may be specified by sub-classes of Mail::SPF::Mech.
118  
119 =cut
120  
121 56 ▶sub new {
Subroutine new: called CC=5 SCAR=17.8
Pod documented
122 56 my ($self, %options) = @_;
123 56 ▶ $self->class ne __PACKAGE__
Branch: 1 branch
BranchTrueFalseTotal
$self->class ne __PACKAGE__ or "Mail::SPF::EAbstractClass"->throw 56 0 56
124 or throw Mail::SPF::EAbstractClass;
125 56 $self = $self->SUPER::new(%options);
126 56 ▶ $self->{parse_text} = $self->{text} if not defined($self->{parse_text});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"parse_text"} 56 0 56
127 $self->{domain_spec} = Mail::SPF::MacroString->new(text => $self->{domain_spec})
128 if defined($self->{domain_spec})
129 56 ▶ and not UNIVERSAL::isa($self->{domain_spec}, 'Mail::SPF::MacroString');
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->{"domain_spec"} and not UNIVERSAL::isa($self->{"domain_spec"}, "Mail::SPF::MacroString") 0 56 56
Condition33%1/3
defined $self->{"domain_spec"} and not UNIVERSAL::isa($self->{"domain_spec"}, "Mail::SPF::MacroString")
!ll&&!rl&&r
5600
MC/DC0%0/2
defined $self->{"domain_spec"} and not UNIVERSAL::isa($self->{"domain_spec"}, "Mail::SPF::MacroString")
defined $self->{"domain_spec"} not UNIVERSAL::isa($self->{"domain_spec"}, "Mail::SPF::MacroString")
Truth table33%1/3
A and not(B)
A= defined $self->{"domain_spec"}B= not UNIVERSAL::isa($self->{"domain_spec"}, "Mail::SPF::MacroString")
ABresult
0X0
100
111
130 56 return $self;
131 }
132  
133 =item B<new_from_string($text, %options)>: returns I<Mail::SPF::Mech>;
134 throws I<Mail::SPF::ENothingToParse>, I<Mail::SPF::EInvalidMech>
135  
136 I<Abstract>. Creates a new SPF record mechanism object by parsing the string and
137 any options given.
138  
139 =back
140  
141 =head2 Class methods
142  
143 The following class methods are provided:
144  
145 =over
146  
147 =item B<default_qualifier>: returns I<string>
148  
149 Returns the default qualifier, i.e. B<'+'>.
150  
151 =item B<default_ipv4_prefix_length>: returns I<integer>
152  
153 Returns the default IPv4 network prefix length, i.e. B<32>.
154  
155 =item B<default_ipv6_prefix_length>: returns I<integer>
156  
157 Returns the default IPv6 network prefix length, i.e. B<128>.
158  
159 =item B<qualifier_pattern>: returns I<Regexp>
160  
161 Returns a regular expression that matches any legal mechanism qualifier, i.e. B<'+'>,
162 B<'-'>, B<'~'>, or B<'?'>.
163  
164 =item B<name>: returns I<string>
165  
166 I<Abstract>. Returns the name of the mechanism.
167  
168 This method is abstract and must be implemented by sub-classes of
169 Mail::SPF::Mech.
170  
171 =item B<name_pattern>: returns I<Regexp>
172  
173 Returns a regular expression that matches any legal mechanism name.
174  
175 =back
176  
177 =head2 Instance methods
178  
179 The following instance methods are provided:
180  
181 =over
182  
183 =cut
184  
185 56 ▶sub parse {
Subroutine parse: called CC=2 SCAR=7.0
Pod undocumented
186 56 my ($self) = @_;
187 defined($self->{parse_text})
188 56 ▶ or throw Mail::SPF::ENothingToParse('Nothing to parse for mechanism');
Branch: 1 branch
BranchTrueFalseTotal
defined $self->{"parse_text"} or "Mail::SPF::ENothingToParse"->throw("Nothing to parse for mechanism") 56 0 56
189 56 $self->parse_qualifier();
190 56 $self->parse_name();
191 56 $self->parse_params();
192 56 $self->parse_end();
193 56 return;
194 }
195  
196 56 ▶sub parse_qualifier {
Subroutine parse_qualifier: called CC=3 SCAR=11.6
Pod undocumented
197 56 my ($self) = @_;
198 56 ▶ if ($self->{parse_text} =~ s/^(${\$self->qualifier_pattern})?//) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{'parse_text'} =~ s/^(${\$self->qualifier_pattern;})?//) { } 56 0 56
199 56 ▶ $self->{qualifier} = $1 || $self->default_qualifier;
Condition66%2/3
$1 || $self->default_qualifier
l!l&&r!l&&!r
32240
MC/DC0%0/2
$1 || $self->default_qualifier
$1 $self->default_qualifier
Truth table66%2/3
A || B
A= $1B= $self->default_qualifier
ABresult
1X1
011
000
200 }
201 else {
202 0 throw Mail::SPF::EInvalidMechQualifier(
203 "Invalid qualifier encountered in '" . $self->text . "'");
204 }
205 56 return;
206 }
207  
208 56 ▶sub parse_name {
Subroutine parse_name: called CC=2 SCAR=7.2
Pod undocumented
209 56 my ($self) = @_;
210 56 ▶ if ($self->{parse_text} =~ s/^ (${\$self->name_pattern}) (?: : (?=.) )? //x) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{'parse_text'} =~ s/^ (${\$self->name_pattern;}) (?: : (?=.) )? //x) { } 56 0 56
211 56 $self->{name} = $1;
212 }
213 else {
214 0 throw Mail::SPF::EInvalidMech(
215 "Unexpected mechanism name encountered in '" . $self->text . "'");
216 }
217 56 return;
218 }
219  
220 0 ▶sub parse_params {
Subroutine parse_params: not called CC=2 SCAR=17.9
Pod undocumented
221 0 my ($self) = @_;
222 # Parse generic string of parameters text (should be overridden in sub-classes):
223 0 ▶ if ($self->{parse_text} =~ s/^(.*)//) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"parse_text"} =~ s/^(.*)//) 0 0 0
224 0 $self->{params_text} = $1;
225 }
226 0 return;
227 }
228  
229 56 ▶sub parse_end {
Subroutine parse_end: called CC=2 SCAR=7.0
Pod undocumented
230 56 my ($self) = @_;
231 56 ▶ $self->{parse_text} eq ''
Branch: 1 branch
BranchTrueFalseTotal
$self->{"parse_text"} eq "" or "Mail::SPF::EJunkInTerm"->throw(q[Junk encountered in mechanism '] . $self->text . q[']) 56 0 56
232 or throw Mail::SPF::EJunkInTerm("Junk encountered in mechanism '" . $self->text . "'");
233 56 delete($self->{parse_text});
234 56 return;
235 }
236  
237 =item B<text>: returns I<string>; throws I<Mail::SPF::ENoUnparsedText>
238  
239 Returns the unparsed text of the mechanism. Throws a
240 I<Mail::SPF::ENoUnparsedText> exception if the mechanism was created
241 synthetically instead of being parsed, and no text was provided.
242  
243 =item B<qualifier>: returns I<string>
244  
245 Returns the qualifier of the mechanism. See the description of the C<new>
246 constructor's C<qualifier> option.
247  
248 =cut
249  
250 72 ▶sub qualifier {
Subroutine qualifier: called CC=2 SCAR=8.1
Pod documented
251 72 my ($self) = @_;
252 # Read-only!
253 72 ▶ return $self->{qualifier} || $self->default_qualifier;
Condition33%1/3
$self->{'qualifier'} || $self->default_qualifier
l!l&&r!l&&!r
7200
MC/DC0%0/2
$self->{'qualifier'} || $self->default_qualifier
$self->{'qualifier'} $self->default_qualifier
Truth table33%1/3
A || B
A= $self->{'qualifier'}B= $self->default_qualifier
ABresult
1X1
011
000
254 }
255  
256 =item B<params>: returns I<string>
257  
258 I<Abstract>. Returns the mechanism's parameters formatted as a string.
259  
260 A sub-class of Mail::SPF::Mech does not have to implement this method if it
261 supports no parameters.
262  
263 =item B<stringify>: returns I<string>
264  
265 Formats the mechanism's qualifier, name, and parameters as a string and returns
266 it. (A qualifier that matches the default of B<'+'> is omitted.) You can
267 simply use a Mail::SPF::Mech object as a string for the same effect, see
268 L<"OVERLOADING">.
269  
270 =cut
271  
272 26 ▶sub stringify {
Subroutine stringify: called CC=4 SCAR=13.9
Pod undocumented
273 26 my ($self) = @_;
274 26 ▶ my $params = $self->can('params') ? $self->params : undef;
Branch: 1 branch
BranchTrueFalseTotal
$self->can('params') ? : 6 20 26
275 26 ▶ return sprintf(
Branch: 2 branches
BranchTrueFalseTotal
$self->qualifier eq $self->default_qualifier ? : 6 20 26
defined $params ? : 4 22 26
276 '%s%s%s',
277 $self->qualifier eq $self->default_qualifier ? '' : $self->qualifier,
278 $self->name,
279 defined($params) ? $params : ''
280 );
281 }
282  
283 =item B<domain($server, $request)>: returns I<string>
284  
285 Returns the target domain of the mechanism. Depending on whether the mechanism
286 does have an explicit C<domain_spec> parameter, this is either the
287 macro-expanded C<domain_spec> parameter, or the request's authority domain
288 (see L<Mail::SPF::Request/authority_domain>) otherwise. Both a
289 I<Mail::SPF::Server> and a I<Mail::SPF::Request> object are required for
290 resolving the target domain.
291  
292 =cut
293  
294 18 ▶sub domain {
Subroutine domain: called CC=4 SCAR=14.1
Pod documented
295 18 my ($self, $server, $request) = @_;
296 18 ▶ defined($server)
Branch: 1 branch
BranchTrueFalseTotal
defined $server or "Mail::SPF::EOptionRequired"->throw("Mail::SPF server object required for target domain resolution") 18 0 18
297 or throw Mail::SPF::EOptionRequired('Mail::SPF server object required for target domain resolution');
298 18 ▶ defined($request)
Branch: 1 branch
BranchTrueFalseTotal
defined $request or "Mail::SPF::EOptionRequired"->throw("Request object required for target domain resolution") 18 0 18
299 or throw Mail::SPF::EOptionRequired('Request object required for target domain resolution');
300 return $self->{domain_spec}->new(server => $server, request => $request)
301 18 ▶ if defined($self->{domain_spec});
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->{"domain_spec"} 13 5 18
302 5 return $request->authority_domain;
303 }
304  
305 =item B<match($server, $request)>: returns I<boolean>; throws I<Mail::SPF::Result::Error>
306  
307 I<Abstract>. Checks whether the mechanism matches the parameters of the given
308 request (see L<Mail::SPF::Request>) and returns B<true> if it does, or B<false>
309 otherwise. In any case, takes both a I<Mail::SPF::Server> and a
310 I<Mail::SPF::Request> object.
311  
312 This method is abstract and must be implemented by sub-classes of
313 Mail::SPF::Mech.
314  
315 =item B<match_in_domain($server, $request)>: returns I<boolean>;
316 throws I<Mail::SPF::Result::Error>
317  
318 =item B<match_in_domain($server, $request, $domain)>: returns I<boolean>;
319 throws I<Mail::SPF::Result::Error>
320  
321 Checks whether the mechanism's target domain name (that is, any of its DNS C<A>
322 or C<AAAA> records) matches the given request's IP address (see
323 L<Mail::SPF::Request/ip_address>), and returns B<true> if it does, or B<false>
324 otherwise. If an explicit domain is specified, it is used instead of the
325 mechanism's target domain. The mechanism's IP network prefix lengths are
326 respected when matching DNS address records against the request's IP address.
327 See RFC 4408, 5, for the exact algorithm used.
328  
329 This method exists mainly for the convenience of sub-classes of
330 Mail::SPF::Mech.
331  
332 =cut
333  
334 6 ▶sub match_in_domain {
Subroutine match_in_domain: called CC=10 SCAR=28.0
Pod documented
335 6 my ($self, $server, $request, $domain) = @_;
336  
337 6 ▶ $domain = $self->domain($server, $request)
Branch: 1 branch
BranchTrueFalseTotal
unless defined $domain 6 0 6
338 if not defined($domain);
339  
340 6 my $ipv4_prefix_length = $self->ipv4_prefix_length;
341 6 my $ipv6_prefix_length = $self->ipv6_prefix_length;
342 6 ▶ my $addr_rr_type = $request->ip_address->version == 4 ? 'A' : 'AAAA';
Branch: 1 branch
BranchTrueFalseTotal
$request->ip_address->version == 4 ? : 6 0 6
343  
344 6 my $packet = $server->dns_lookup($domain, $addr_rr_type);
345 5 ▶ my @rrs = $packet->answer
Branch: 1 branch
BranchTrueFalseTotal
my(@rrs) = $packet->answer or $server->count_void_dns_lookup($request) 5 0 5
346 or $server->count_void_dns_lookup($request);
347  
348 5 foreach my $rr (@rrs) {
349 5 ▶ if ($rr->type eq 'A') {
Branch: 3 branches
BranchTrueFalseTotal
if ($rr->type eq 'A') { } 5 0 5
elsif ($rr->type eq 'AAAA') { } 0 0 0
elsif ($rr->type eq 'CNAME') { } 0 0 0
350 5 my $network = NetAddr::IP->new($rr->address, $ipv4_prefix_length);
351 5 ▶ return TRUE
Branch: 1 branch
BranchTrueFalseTotal
if $network->contains($request->ip_address) 2 3 5
352 if $network->contains($request->ip_address);
353 }
354 elsif ($rr->type eq 'AAAA') {
355 0 my $network = NetAddr::IP->new($rr->address, $ipv6_prefix_length);
356 0 ▶ return TRUE
Branch: 1 branch
BranchTrueFalseTotal
if $network->contains($request->ip_address_v6) 0 0 0
357 if $network->contains($request->ip_address_v6);
358 }
359 elsif ($rr->type eq 'CNAME') {
360 # Ignore -- we should have gotten the A/AAAA records anyway.
361 }
362 else {
363 # Unexpected RR type.
364 # TODO Generate debug info or ignore silently.
365 }
366 }
367 3 return FALSE;
368 }
369  
370 =item B<explain($server, $request, $result)>
371  
372 Locally generates an explanation for why the mechanism caused the given result,
373 and stores it in the given request object's state.
374  
375 There is no need to override this method in sub-classes. See the
376 L</explanation_template> method.
377  
378 =cut
379  
380 26 ▶sub explain {
Subroutine explain: called CC=2 SCAR=7.0
Pod documented
381 26 my ($self, $server, $request, $result) = @_;
382 26 my $explanation_template = $self->explanation_template($server, $request, $result);
383 return
384 26 ▶ if not defined($explanation_template);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $explanation_template 0 26 26
385 26 ▶ try {
Subroutine __ANON__: called CC=1 SCAR=0.0
386 26 my $explanation = Mail::SPF::MacroString->new(
387 text => $explanation_template,
388 server => $server,
389 request => $request,
390 is_explanation => TRUE
391 );
392 26 $request->state('local_explanation', $explanation);
393 }
394 0 ▶ catch Mail::SPF::Exception with {}
Subroutine __ANON__: not called CC=1 SCAR=0.0
395 26 ▶ catch Mail::SPF::Result with {};
Subroutine __ANON__: not called CC=1 SCAR=0.0
396 26 return;
397 }
398  
399 =item B<explanation_template($server, $request, $result)>: returns I<string>
400  
401 Returns a macro string template for a locally generated explanation for why the
402 mechanism caused the given result object.
403  
404 Sub-classes should either define an C<explanation_templates_by_result_code>
405 hash constant with their own templates, or override this method.
406  
407 =cut
408  
409 26 ▶sub explanation_template {
Subroutine explanation_template: called CC=2 SCAR=7.1
Pod documented
410 26 my ($self, $server, $request, $result) = @_;
411 return undef
412 26 ▶ if not $self->can('explanation_templates_by_result_code');
Branch: 1 branch
BranchTrueFalseTotal
unless $self->can("explanation_templates_by_result_code") 0 26 26
413 26 return $self->explanation_templates_by_result_code->{$result->code};
414 }
415  
416 =back
417  
418 =head1 OVERLOADING
419  
420 If a Mail::SPF::Mech object is used as a I<string>, the C<stringify> method is
421 used to convert the object into a string.
422  
423 =head1 SEE ALSO
424  
425 L<Mail::SPF::Mech::All>,
426 L<Mail::SPF::Mech::IP4>,
427 L<Mail::SPF::Mech::IP6>,
428 L<Mail::SPF::Mech::A>,
429 L<Mail::SPF::Mech::MX>,
430 L<Mail::SPF::Mech::PTR>,
431 L<Mail::SPF::Mech::Exists>,
432 L<Mail::SPF::Mech::Include>
433  
434 L<Mail::SPF>, L<Mail::SPF::Record>, L<Mail::SPF::Term>
435  
436 L<http://tools.ietf.org/html/rfc4408>
437  
438 For availability, support, and license information, see the README file
439 included with Mail::SPF.
440  
441 =head1 AUTHORS
442  
443 Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>
444  
445 =cut
446  
447 6 TRUE;
« SPF/Term.pm ↑ Summary SPF/Server.pm »