Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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.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 RR 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 RR types that are unknown to	them, such as the
	       "SPF" RR	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 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	(assuming that
	   both	"TXT" and "SPF"	RR 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 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.32.0			  2020-08-16		  Mail::SPF::Server(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Mail::SPF::Server&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help