The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Mail-SPF-2.004
River stage one • 2 direct dependents • 5 total dependents
2 ++
/ Mail::SPF::Server

NAME

Mail::SPF::Server - Server class for processing SPF requests

SYNOPSIS

    use Mail::SPF;
    
    my $spf_server  = Mail::SPF::Server->new(
        # Optional default for the authority explanation:
        default_authority_explanation =>
            'See http://www.%{d}/why/s=%{S};i=%{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.org/Why?id=%{S}&ip=%{I}&receiver=%{R}'
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.

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.

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::ERecordSelectionError, Mail::SPF::EDNSError, 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.

Mail::SPF::EDNSError exceptions due to DNS look-ups and Mail::SPF::ESyntaxError exceptions due to an invalid acceptable record 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.

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.

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

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://www.ietf.org/rfc/rfc4408.txt

For availability, support, and license information, see the README file included with Mail::SPF.

AUTHORS

Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>