unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

Mail::SPF::Server(3pm)User Contributed Perl DocumentatioMail::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 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 fol-
           lowing 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 explana-
               tion 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.

           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 addi-
               tional 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 pro-
               cessing 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" mecha-
               nisms 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.

       Instance methods

       The following instance methods are provided:

       process($request): returns Mail::SPF::Result
           Processes the given Mail::SPF::Request object, queries the authori-
           tative 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 evalua-
           tion.  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::ERe-
       dundantAcceptableRecords, Mail::SPF::ESyntaxError
           Queries the authority domain of the given Mail::SPF::Request object
           for SPF sender policy records and, if multiple records are avail-
           able, 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 ver-
               sion 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 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 inaccept-
           able 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::EProcessingLim-
       itExceeded
           Increments by one the count of DNS-interactive mechanisms and modi-
           fiers 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::EProcessingLimitEx-
       ceeded
           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 exam-
           ple 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_author-
           ity_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 <julianATmehnle.net>, Shevek <cpanATanarres.org>



perl v5.8.8                       2007-10-07            Mail::SPF::Server(3pm)