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:
Creates a new server object for processing SPF requests.
%options is a list of key/value pairs representing any of the following options:
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.)
r macro in explanation strings. Defaults to the
system's configured host name.
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.
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!
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_term
option. See there for additional information and security notes.
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 limit on the number of void DNS look-ups. Defaults to undef.
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 instance methods are provided:
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.
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:
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.
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.
Mail::SPF::EDNSError exceptions due to DNS look-ups and Mail::SPF::ESyntaxError exceptions due to invalid acceptable records may also be thrown.
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.
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.
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.
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
option.
hostname option.
dns_resolver option.
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://www.ietf.org/rfc/rfc4408.txt
For availability, support, and license information, see the README file included with Mail::SPF.
Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>