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

SEE ALSO

286       Mail::SPF, Mail::SPF::Request, Mail::SPF::Result
287
288       <http://www.ietf.org/rfc/rfc4408.txt>
289
290       For availability, support, and license information, see the README file
291       included with Mail::SPF.
292

AUTHORS

294       Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>
295
296
297
298perl v5.12.2                      2010-12-06              Mail::SPF::Server(3)
Impressum