1Mail::SPF::Server(3)  User Contributed Perl Documentation Mail::SPF::Server(3)
2
3
4

NAME

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

SYNOPSIS

9           use Mail::SPF;
10
11           my $spf_server  = Mail::SPF::Server->new(
12               # Optional custom default for authority explanation:
13               default_authority_explanation =>
14                   'See http://www.%{d}/why/id=%{S};ip=%{I};r=%{R}'
15           );
16
17           my $result      = $spf_server->process($request);
18

DESCRIPTION

20       Mail::SPF::Server is a server class for processing SPF requests.  Each
21       server instance can be configured with specific processing parameters.
22       Also, the default Net::DNS::Resolver DNS resolver used for making DNS
23       look-ups can be overridden with a custom resolver object.
24
25   Constructor
26       The following constructor is provided:
27
28       new(%options): returns Mail::SPF::Server
29           Creates a new server object for processing SPF requests.
30
31           %options is a list of key/value pairs representing any of the
32           following options:
33
34           default_authority_explanation
35               A string denoting the default (not macro-expanded) authority
36               explanation string to use if the authority domain does not
37               specify an explanation string of its own.  Defaults to:
38
39                   'Please see http://www.openspf.org/Why?s=%{_scope};id=%{S};ip=%{C};r=%{R}'
40
41               As can be seen from the default, a non-standard "_scope" pseudo
42               macro is supported that expands to the name of the identity's
43               scope.  (Note: Do not use any non-standard macros in
44               explanation strings published in DNS.)
45
46           hostname
47               A string denoting the local system's fully qualified host name
48               that should be used for expanding the "r" macro in explanation
49               strings.  Defaults to the system's configured host name.
50
51           dns_resolver
52               An optional DNS resolver object.  If none is specified, a new
53               Net::DNS::Resolver object is used.  The resolver object may be
54               of a different class, but it must provide an interface similar
55               to Net::DNS::Resolver -- at least the "send" and "errorstring"
56               methods must be supported, and the "send" method must return
57               either an object of class Net::DNS::Packet, or, in the case of
58               an error, undef.
59
60           query_rr_types
61               For which RR types to query when looking up and selecting SPF
62               records.  The following values are supported:
63
64               Mail::SPF::Server->query_rr_type_all
65                   Both "TXT" and "SPF" type RRs.
66
67               Mail::SPF::Server->query_rr_type_txt (default)
68                   "TXT" type RRs only.
69
70               Mail::SPF::Server->query_rr_type_spf
71                   "SPF" type RRs only.
72
73               For years Mail::SPF has defaulted to looking up both "SPF" and
74               "TXT" type RRs as recommended by RFC 4408.  Experience has
75               shown, however, that a significant portion of name servers
76               suffer from serious brain damage with regard to the handling of
77               queries for RR types that are unknown to them, such as the
78               "SPF" RR type.  Consequently Mail::SPF now defaults to looking
79               up only "TXT" type RRs.  This may be overridden by setting the
80               query_rr_types option.
81
82               See RFC 4408, 3.1.1, for a discussion of the topic, as well as
83               the description of the "select_record" method.
84
85           max_dns_interactive_terms
86               An integer denoting the maximum number of terms (mechanisms and
87               modifiers) per SPF check that perform DNS look-ups, as defined
88               in RFC 4408, 10.1, paragraph 6.  If undef is specified, there
89               is no limit on the number of such terms.  Defaults to 10, which
90               is the value defined in RFC 4408.
91
92               A value above the default is strongly discouraged for security
93               reasons.  A value below the default has implications with
94               regard to the predictability of SPF results.  Only deviate from
95               the default if you know what you are doing!
96
97           max_name_lookups_per_term
98               An integer denoting the maximum number of DNS name look-ups per
99               term (mechanism or modifier), as defined in RFC 4408, 10.1,
100               paragraph 7.  If undef is specified, there is no limit on the
101               number of look-ups performed.  Defaults to 10, which is the
102               value defined in RFC 4408.
103
104               A value above the default is strongly discouraged for security
105               reasons.  A value below the default has implications with
106               regard to the predictability of SPF results.  Only deviate from
107               the default if you know what you are doing!
108
109           max_name_lookups_per_mx_mech
110           max_name_lookups_per_ptr_mech
111               An integer denoting the maximum number of DNS name look-ups per
112               mx or ptr mechanism, respectively.  Defaults to the value of
113               the "max_name_lookups_per_term" option.  See there for
114               additional information and security notes.
115
116           max_void_dns_lookups
117               An integer denoting the maximum number of "void" DNS look-ups
118               per SPF check, i.e. the number of DNS look-ups that were caused
119               by DNS-interactive terms and macros (as defined in RFC 4408,
120               10.1, paragraphs 6 and 7) and that are allowed to return an
121               empty answer with RCODE 0 or RCODE 3 ("NXDOMAIN") before
122               processing is aborted with a "permerror" result.  If undef is
123               specified, there is no stricter limit on the number of void DNS
124               look-ups beyond the usual processing limits.  Defaults to 2.
125
126               Specifically, the DNS look-ups that are subject to this limit
127               are those caused by the "a", "mx", "ptr", and "exists"
128               mechanisms and the "p" macro.
129
130               A value of 2 is likely to prevent effective DoS attacks against
131               third-party victim domains.  However, a definite limit may
132               cause "permerror" results even with certain (overly complex)
133               innocent sender policies where useful results would normally be
134               returned.
135
136   Class methods
137       The following class methods are provided:
138
139       result_class: returns class
140       result_class($name): returns class
141           Returns a Mail::SPF::Result descendent class determined from the
142           given result name via the server's inherent result base class, or
143           returns the server's inherent result base class if no result name
144           is given.  This method may also be used as an instance method.
145
146           Note:  Do not write code invoking class methods on literal result
147           class names as this would ignore any derivative result classes
148           provided by Mail::SPF extension modules.
149
150       throw_result($name, $request): throws Mail::SPF::Result
151       throw_result($name, $request, $text): throws Mail::SPF::Result
152           Throws a Mail::SPF::Result descendant determined from the given
153           result name via the server's inherent result base class, passing an
154           optional result text and associating the given Mail::SPF::Request
155           object with the result object.  This method may also be used as an
156           instance method.
157
158           Note:  Do not write code invoking "throw" on literal result class
159           names as this would ignore any derivative result classes provided
160           by Mail::SPF extension modules.
161
162   Instance methods
163       The following instance methods are provided:
164
165       process($request): returns Mail::SPF::Result
166           Processes the given Mail::SPF::Request object, queries the
167           authoritative domain for an SPF sender policy (see the description
168           of the "select_record" method), evaluates the policy with regard to
169           the given identity and other request parameters, and returns a
170           Mail::SPF::Result object denoting the result of the policy
171           evaluation.  See RFC 4408, 4, and RFC 4406, 4, for details.
172
173       select_record($request): returns Mail::SPF::Record; throws
174       Mail::SPF::EDNSError, Mail::SPF::ENoAcceptableRecord,
175       Mail::SPF::ERedundantAcceptableRecords, Mail::SPF::ESyntaxError
176           Queries the authority domain of the given Mail::SPF::Request object
177           for SPF sender policy records and, if multiple records are
178           available, selects the record of the highest acceptable record
179           version that covers the requested scope.
180
181           More precisely, the following algorithm is performed (assuming that
182           both "TXT" and "SPF" RR types are being queried):
183
184           1.  Determine the authority domain, the set of acceptable SPF
185               record versions, and the identity scope from the given request
186               object.
187
188           2.  Query the authority domain for SPF records of the "SPF" DNS RR
189               type, discarding any records that are of an inacceptable
190               version or do not cover the desired scope.
191
192               If this yields no SPF records, query the authority domain for
193               SPF records of the "TXT" DNS RR type, discarding any records
194               that are of an inacceptable version or do not cover the desired
195               scope.
196
197               If still no acceptable SPF records could be found, throw a
198               Mail::SPF::ENoAcceptableRecord exception.
199
200           3.  Discard all records but those of the highest acceptable version
201               found.
202
203               If exactly one record remains, return it.  Otherwise, throw a
204               Mail::SPF::ERedundantAcceptableRecords exception.
205
206           If the querying of either RR type has been disabled via the "new"
207           constructor's "query_rr_types" option, the respective part in step
208           2 will be skipped.
209
210           Mail::SPF::EDNSError exceptions due to DNS look-ups and
211           Mail::SPF::ESyntaxError exceptions due to invalid acceptable
212           records may also be thrown.
213
214       get_acceptable_records_from_packet($packet, $rr_type, \@versions,
215       $scope, $domain): returns list of Mail::SPF::Record
216           Filters from the given Net::DNS::Packet object all resource records
217           of the given RR type and for the given domain name, discarding any
218           records that are not SPF records at all, that are of an
219           inacceptable SPF record version, or that do not cover the given
220           scope.  Returns a list of acceptable records.
221
222       dns_lookup($domain, $rr_type): returns Net::DNS::Packet; throws
223       Mail::SPF::EDNSTimeout, Mail::SPF::EDNSError
224           Queries the DNS using the configured resolver for resource records
225           of the desired type at the specified domain and returns a
226           Net::DNS::Packet object if an answer packet was received.  Throws a
227           Mail::SPF::EDNSTimeout exception if a DNS time-out occurred.
228           Throws a Mail::SPF::EDNSError exception if an error (other than
229           RCODE 3 AKA "NXDOMAIN") occurred.
230
231       count_dns_interactive_term($request): throws
232       Mail::SPF::EProcessingLimitExceeded
233           Increments by one the count of DNS-interactive mechanisms and
234           modifiers that have been processed so far during the evaluation of
235           the given Mail::SPF::Request object.  If this exceeds the
236           configured limit (see the "new" constructor's
237           "max_dns_interactive_terms" option), throws a
238           Mail::SPF::EProcessingLimitExceeded exception.
239
240           This method is supposed to be called by the "match" and "process"
241           methods of Mail::SPF::Mech and Mail::SPF::Mod sub-classes before
242           (and only if) they do any DNS look-ups.
243
244       count_void_dns_lookup($request): throws
245       Mail::SPF::EProcessingLimitExceeded
246           Increments by one the count of "void" DNS look-ups that have
247           occurred so far during the evaluation of the given
248           Mail::SPF::Request object.  If this exceeds the configured limit
249           (see the "new" constructor's "max_void_dns_lookups" option), throws
250           a Mail::SPF::EProcessingLimitExceeded exception.
251
252           This method is supposed to be called by any code after any calls to
253           the "dns_lookup" method whenever (i) no answer records were
254           returned, and (ii) this fact is a possible indication of a DoS
255           attack against a third-party victim domain, and (iii) the number of
256           "void" look-ups is not already constrained otherwise (as for
257           example is the case with the "include" mechanism and the "redirect"
258           modifier).  Specifically, this applies to look-ups performed by the
259           "a", "mx", "ptr", and "exists" mechanisms and the "p" macro.
260
261       default_authority_explanation: returns Mail::SPF::MacroString
262           Returns the default authority explanation as a MacroString object.
263           See the description of the "new" constructor's
264           "default_authority_explanation" option.
265
266       hostname: returns string
267           Returns the local system's host name.  See the description of the
268           "new" constructor's "hostname" option.
269
270       dns_resolver: returns Net::DNS::Resolver or compatible object
271           Returns the DNS resolver object of the server object.  See the
272           description of the "new" constructor's "dns_resolver" option.
273
274       query_rr_types: returns integer
275           Returns a value denoting the RR types for which to query when
276           looking up and selecting SPF records.  See the description of the
277           "new" constructor's "query_rr_types" option.
278
279       max_dns_interactive_terms: returns integer
280       max_name_lookups_per_term: returns integer
281       max_name_lookups_per_mx_mech: returns integer
282       max_name_lookups_per_ptr_mech: returns integer
283       max_void_dns_lookups: returns integer
284           Return the limit values of the server object.  See the description
285           of the "new" constructor's corresponding options.
286

SEE ALSO

288       Mail::SPF, Mail::SPF::Request, Mail::SPF::Result
289
290       <http://tools.ietf.org/html/rfc4408>
291
292       For availability, support, and license information, see the README file
293       included with Mail::SPF.
294

AUTHORS

296       Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>
297
298
299
300perl v5.36.0                      2023-01-20              Mail::SPF::Server(3)
Impressum