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:

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:

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>