| 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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
Condition33%1/3
defined $self->{"domain_spec"} and not UNIVERSAL::isa($self->{"domain_spec"}, "Mail::SPF::MacroString")
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")
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 199 | 56 | ▶ | $self->{qualifier} = $1 || $self->default_qualifier; | ||||||||||||||||||||||||||
|
Condition66%2/3
$1 || $self->default_qualifier
MC/DC0%0/2
$1 || $self->default_qualifier
$1
$self->default_qualifier
Truth table66%2/3
A || B
A= $1B= $self->default_qualifier
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 275 | 26 | ▶ | return sprintf( | ||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 297 | or throw Mail::SPF::EOptionRequired('Mail::SPF server object required for target domain resolution'); | ||||||||||||||||||||||||||||
| 298 | 18 | ▶ | defined($request) | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 343 | |||||||||||||||||||||||||||||
| 344 | 6 | my $packet = $server->dns_lookup($domain, $addr_rr_type); | |||||||||||||||||||||||||||
| 345 | 5 | ▶ | my @rrs = $packet->answer | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 350 | 5 | my $network = NetAddr::IP->new($rr->address, $ipv4_prefix_length); | |||||||||||||||||||||||||||
| 351 | 5 | ▶ | return TRUE | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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; | |||||||||||||||||||||||||||