Mail::SPF::Server • man page

Mail::SPF::Server (3)

Leading comments

Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/Mail::SPF::Server.3pm".)

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 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 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

types to query when looking up and selecting

SPF

records. The following values are supported:

Mail::SPF::Server->query_rr_type_all: Both "TXT" and "SPF" type RRs.
Mail::SPF::Server->query_rr_type_txt (default): "TXT" type RRs only.
Mail::SPF::Server->query_rr_type_spf: "SPF" type RRs only.

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

types that are unknown to them, such as the "SPF"

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

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 (assuming that both "TXT" and "SPF"

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

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

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

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.

AUTHORS

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

Mail::SPF::Server • man page

Mail::SPF::Server • man page

Mail::SPF::Server (3)

Leading comments

NAME

SYNOPSIS

DESCRIPTION

Constructor

Class methods

Instance methods

SEE ALSO

AUTHORS

Man Section

extra • Version

extra • Source

extra • Book