1Mail::SPF::Server(3) User Contributed Perl Documentation Mail::SPF::Server(3)
2
6 Mail::SPF::Server - Server class for processing SPF requests
7
9 use Mail::SPF;
10 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 my $result = $spf_server->process($request);
18
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 Constructor
26 The following constructor is provided:
27 new(%options): returns Mail::SPF::Server
29 Creates a new server object for processing SPF requests.
30 %options is a list of key/value pairs representing any of the
32 following options:
33 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 'Please see http://www.openspf.org/Why?s=%{_scope};id=%{S};ip=%{C};r=%{R}'
40 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 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 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 query_rr_types
61 For which RR types to query when looking up and selecting SPF
62 records. The following values are supported:
63 Mail::SPF::Server->query_rr_type_all (default)
65 Both "SPF" and "TXT" type RRs.
66 Mail::SPF::Server->query_rr_type_spf
68 "SPF" type RRs only.
69 Mail::SPF::Server->query_rr_type_txt
71 "TXT" type RRs only.
72 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 See RFC 4408, 3.1.1, for a discussion of the topic, as well as
82 the description of the "select_record" method.
83 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 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 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 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 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 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 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 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 Class methods
136 The following class methods are provided:
137 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 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 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 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 Instance methods
162 The following instance methods are provided:
163 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 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 More precisely, the following algorithm is performed:
181 1. Determine the authority domain, the set of acceptable SPF
183 record versions, and the identity scope from the given request
184 object.
185 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 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 If still no acceptable SPF records could be found, throw a
196 Mail::SPF::ENoAcceptableRecord exception.
197 3. Discard all records but those of the highest acceptable version
199 found.
200 If exactly one record remains, return it. Otherwise, throw a
202 Mail::SPF::ERedundantAcceptableRecords exception.
203 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 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 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 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 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 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 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 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 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 hostname: returns string
265 Returns the local system's host name. See the description of the
266 "new" constructor's "hostname" option.
267 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 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 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
286 Mail::SPF, Mail::SPF::Request, Mail::SPF::Result
287 <http://www.ietf.org/rfc/rfc4408.txt>
289 For availability, support, and license information, see the README file
291 included with Mail::SPF.
292
294 Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>
295perl v5.12.2 2010-12-06 Mail::SPF::Server(3)