Mail::SPF::Server(3) User Contributed Perl Documentation Mail::SPF::Server(3)NAME
Mail::SPF::Server - Server class for processing SPF requests
SYNOPSIS
use Mail::SPF;
my $spf_server = Mail::SPF::Server->new(
# Optional custom default for authority explanation:
default_authority_explanation =>
'See http://www.%{d}/why/id=%{S};ip=%{I};r=%{R}'
);
my $result = $spf_server->process($request);
DESCRIPTION
Mail::SPF::Server is a server class for processing SPF requests. Each
server instance can be configured with specific processing parameters.
Also, the default Net::DNS::Resolver DNS resolver used for making DNS
look-ups can be overridden with a custom resolver object.
Constructor
The following constructor is provided:
new(%options): returns Mail::SPF::Server
Creates a new server object for processing SPF requests.
%options is a list of key/value pairs representing any of the
following options:
default_authority_explanation
A string denoting the default (not macro-expanded) authority
explanation string to use if the authority domain does not
specify an explanation string of its own. Defaults to:
'Please see http://www.openspf.net/Why?s=%{_scope};id=%{S};ip=%{C};r=%{R}'
As can be seen from the default, a non-standard "_scope" pseudo
macro is supported that expands to the name of the identity's
scope. (Note: Do not use any non-standard macros in
explanation strings published in DNS.)
hostname
A string denoting the local system's fully qualified host name
that should be used for expanding the "r" macro in explanation
strings. Defaults to the system's configured host name.
dns_resolver
An optional DNS resolver object. If none is specified, a new
Net::DNS::Resolver object is used. The resolver object may be
of a different class, but it must provide an interface similar
to Net::DNS::Resolver -- at least the "send" and "errorstring"
methods must be supported, and the "send" method must return
either an object of class Net::DNS::Packet, or, in the case of
an error, undef.
query_rr_types
For which RR types to query when looking up and selecting SPF
records. The following values are supported:
Mail::SPF::Server->query_rr_type_all (default)
Both "SPF" and "TXT" type RRs.
Mail::SPF::Server->query_rr_type_spf
"SPF" type RRs only.
Mail::SPF::Server->query_rr_type_txt
"TXT" type RRs only.
Some (few) name servers suffer from serious brain damage with
regard to the handling of queries for RR types that are unknown
to them, such as the "SPF" RR type, so some (few) Mail::SPF
users have expressed the desire for a way to disable the
retrieval of "SPF" type RRs. It is, however, a better idea to
pressure the manufacturers of such broken name servers into
fixing their products.
See RFC 4408, 3.1.1, for a discussion of the topic, as well as
the description of the "select_record" method.
max_dns_interactive_terms
An integer denoting the maximum number of terms (mechanisms and
modifiers) per SPF check that perform DNS look-ups, as defined
in RFC 4408, 10.1, paragraph 6. If undef is specified, there
is no limit on the number of such terms. Defaults to 10, which
is the value defined in RFC 4408.
A value above the default is strongly discouraged for security
reasons. A value below the default has implications with
regard to the predictability of SPF results. Only deviate from
the default if you know what you are doing!
max_name_lookups_per_term
An integer denoting the maximum number of DNS name look-ups per
term (mechanism or modifier), as defined in RFC 4408, 10.1,
paragraph 7. If undef is specified, there is no limit on the
number of look-ups performed. Defaults to 10, which is the
value defined in RFC 4408.
A value above the default is strongly discouraged for security
reasons. A value below the default has implications with
regard to the predictability of SPF results. Only deviate from
the default if you know what you are doing!
max_name_lookups_per_mx_mech
max_name_lookups_per_ptr_mech
An integer denoting the maximum number of DNS name look-ups per
mx or ptr mechanism, respectively. Defaults to the value of
the "max_name_lookups_per_term" option. See there for
additional information and security notes.
max_void_dns_lookups
An integer denoting the maximum number of "void" DNS look-ups
per SPF check, i.e. the number of DNS look-ups that were caused
by DNS-interactive terms and macros (as defined in RFC 4408,
10.1, paragraphs 6 and 7) and that are allowed to return an
empty answer with RCODE 0 or RCODE 3 ("NXDOMAIN") before
processing is aborted with a "permerror" result. If undef is
specified, there is no stricter limit on the number of void DNS
look-ups beyond the usual processing limits. Defaults to 2.
Specifically, the DNS look-ups that are subject to this limit
are those caused by the "a", "mx", "ptr", and "exists"
mechanisms and the "p" macro.
A value of 2 is likely to prevent effective DoS attacks against
third-party victim domains. However, a definite limit may
cause "permerror" results even with certain (overly complex)
innocent sender policies where useful results would normally be
returned.
Class methods
The following class methods are provided:
result_class: returns class
result_class($name): returns class
Returns a Mail::SPF::Result descendent class determined from the
given result name via the server's inherent result base class, or
returns the server's inherent result base class if no result name
is given. This method may also be used as an instance method.
Note: Do not write code invoking class methods on literal result
class names as this would ignore any derivative result classes
provided by Mail::SPF extension modules.
throw_result($name, $request): throws Mail::SPF::Result
throw_result($name, $request, $text): throws Mail::SPF::Result
Throws a Mail::SPF::Result descendant determined from the given
result name via the server's inherent result base class, passing an
optional result text and associating the given Mail::SPF::Request
object with the result object. This method may also be used as an
instance method.
Note: Do not write code invoking "throw" on literal result class
names as this would ignore any derivative result classes provided
by Mail::SPF extension modules.
Instance methods
The following instance methods are provided:
process($request): returns Mail::SPF::Result
Processes the given Mail::SPF::Request object, queries the
authoritative domain for an SPF sender policy (see the description
of the "select_record" method), evaluates the policy with regard to
the given identity and other request parameters, and returns a
Mail::SPF::Result object denoting the result of the policy
evaluation. See RFC 4408, 4, and RFC 4406, 4, for details.
select_record($request): returns Mail::SPF::Record; throws
Mail::SPF::EDNSError, Mail::SPF::ENoAcceptableRecord,
Mail::SPF::ERedundantAcceptableRecords, Mail::SPF::ESyntaxError
Queries the authority domain of the given Mail::SPF::Request object
for SPF sender policy records and, if multiple records are
available, selects the record of the highest acceptable record
version that covers the requested scope.
More precisely, the following algorithm is performed:
1. Determine the authority domain, the set of acceptable SPF
record versions, and the identity scope from the given request
object.
2. Query the authority domain for SPF records of the "SPF" DNS RR
type, discarding any records that are of an inacceptable
version or do not cover the desired scope.
If this yields no SPF records, query the authority domain for
SPF records of the "TXT" DNS RR type, discarding any records
that are of an inacceptable version or do not cover the desired
scope.
If still no acceptable SPF records could be found, throw a
Mail::SPF::ENoAcceptableRecord exception.
3. Discard all records but those of the highest acceptable version
found.
If exactly one record remains, return it. Otherwise, throw a
Mail::SPF::ERedundantAcceptableRecords exception.
If the querying of either RR type has been disabled via the "new"
constructor's "query_rr_types" option, the respective part in step
2 will be skipped.
Mail::SPF::EDNSError exceptions due to DNS look-ups and
Mail::SPF::ESyntaxError exceptions due to invalid acceptable
records may also be thrown.
get_acceptable_records_from_packet($packet, $rr_type, \@versions,
$scope, $domain): returns list of Mail::SPF::Record
Filters from the given Net::DNS::Packet object all resource records
of the given RR type and for the given domain name, discarding any
records that are not SPF records at all, that are of an
inacceptable SPF record version, or that do not cover the given
scope. Returns a list of acceptable records.
dns_lookup($domain, $rr_type): returns Net::DNS::Packet; throws
Mail::SPF::EDNSTimeout, Mail::SPF::EDNSError
Queries the DNS using the configured resolver for resource records
of the desired type at the specified domain and returns a
Net::DNS::Packet object if an answer packet was received. Throws a
Mail::SPF::EDNSTimeout exception if a DNS time-out occurred.
Throws a Mail::SPF::EDNSError exception if an error (other than
RCODE 3 AKA "NXDOMAIN") occurred.
count_dns_interactive_term($request): throws
Mail::SPF::EProcessingLimitExceeded
Increments by one the count of DNS-interactive mechanisms and
modifiers that have been processed so far during the evaluation of
the given Mail::SPF::Request object. If this exceeds the
configured limit (see the "new" constructor's
"max_dns_interactive_terms" option), throws a
Mail::SPF::EProcessingLimitExceeded exception.
This method is supposed to be called by the "match" and "process"
methods of Mail::SPF::Mech and Mail::SPF::Mod sub-classes before
(and only if) they do any DNS look-ups.
count_void_dns_lookup($request): throws
Mail::SPF::EProcessingLimitExceeded
Increments by one the count of "void" DNS look-ups that have
occurred so far during the evaluation of the given
Mail::SPF::Request object. If this exceeds the configured limit
(see the "new" constructor's "max_void_dns_lookups" option), throws
a Mail::SPF::EProcessingLimitExceeded exception.
This method is supposed to be called by any code after any calls to
the "dns_lookup" method whenever (i) no answer records were
returned, and (ii) this fact is a possible indication of a DoS
attack against a third-party victim domain, and (iii) the number of
"void" look-ups is not already constrained otherwise (as for
example is the case with the "include" mechanism and the "redirect"
modifier). Specifically, this applies to look-ups performed by the
"a", "mx", "ptr", and "exists" mechanisms and the "p" macro.
default_authority_explanation: returns Mail::SPF::MacroString
Returns the default authority explanation as a MacroString object.
See the description of the "new" constructor's
"default_authority_explanation" option.
hostname: returns string
Returns the local system's host name. See the description of the
"new" constructor's "hostname" option.
dns_resolver: returns Net::DNS::Resolver or compatible object
Returns the DNS resolver object of the server object. See the
description of the "new" constructor's "dns_resolver" option.
query_rr_types: returns integer
Returns a value denoting the RR types for which to query when
looking up and selecting SPF records. See the description of the
"new" constructor's "query_rr_types" option.
max_dns_interactive_terms: returns integer
max_name_lookups_per_term: returns integer
max_name_lookups_per_mx_mech: returns integer
max_name_lookups_per_ptr_mech: returns integer
max_void_dns_lookups: returns integer
Return the limit values of the server object. See the description
of the "new" constructor's corresponding options.
SEE ALSO
Mail::SPF, Mail::SPF::Request, Mail::SPF::Result
<http://tools.ietf.org/html/rfc4408>
For availability, support, and license information, see the README file
included with Mail::SPF.
AUTHORS
Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>
perl v5.16.2 2013-08-25 Mail::SPF::Server(3)
