👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

CentOS 7.0 - man page for mail::spf::server (centos section 3)

Mail::SPF::Server(3)	       User Contributed Perl Documentation	     Mail::SPF::Server(3)

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:

	   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.net/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 RR types to query when looking up and selecting SPF records.  The
	       following values are supported:

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

	       Mail::SPF::Server->query_rr_type_spf
		   "SPF" type RRs only.

	       Mail::SPF::Server->query_rr_type_txt
		   "TXT" type RRs only.

	       Some (few) name servers suffer from serious brain damage with regard to the
	       handling of queries for RR types that are unknown to them, such as the "SPF" RR
	       type, so some (few) Mail::SPF users have expressed the desire for a way to disable
	       the retrieval of "SPF" type RRs.  It is, however, a better idea to pressure the
	       manufacturers of such broken name servers into fixing their products.

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

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

perl v5.16.3				    2014-06-10			     Mail::SPF::Server(3)


All times are GMT -4. The time now is 10:03 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password