Mail::SPF::Server - Server class for processing SPF requests
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);
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.
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.org/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:
For years Mail::SPF has defaulted to looking up both
"SPF" and
"TXT" type RRs as recommended by RFC 4408.
Experience has shown, however, that a significant portion of 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. Consequently
Mail::SPF now defaults to looking up only
"TXT" type RRs. This may be overridden by
setting the query_rr_types option.
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.
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.
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 (assuming
that both "TXT" and
"SPF" RR types are being queried):
- 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.
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.
Julian Mehnle <julian@mehnle.net>, Shevek
<cpan@anarres.org>