SPF/Mech.pm

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