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
65 Both "TXT" and "SPF" type RRs.
66 Mail::SPF::Server->query_rr_type_txt (default)
68 "TXT" type RRs only.
69 Mail::SPF::Server->query_rr_type_spf
71 "SPF" type RRs only.
72 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 See RFC 4408, 3.1.1, for a discussion of the topic, as well as
83 the description of the "select_record" method.
84 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 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 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 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 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 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 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 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 Class methods
137 The following class methods are provided:
138 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 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 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 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 Instance methods
163 The following instance methods are provided:
164 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 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 More precisely, the following algorithm is performed (assuming that
182 both "TXT" and "SPF" RR types are being queried):
183 1. Determine the authority domain, the set of acceptable SPF
185 record versions, and the identity scope from the given request
186 object.
187 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 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 If still no acceptable SPF records could be found, throw a
198 Mail::SPF::ENoAcceptableRecord exception.
199 3. Discard all records but those of the highest acceptable version
201 found.
202 If exactly one record remains, return it. Otherwise, throw a
204 Mail::SPF::ERedundantAcceptableRecords exception.
205 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 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 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 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 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 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 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 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 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 hostname: returns string
267 Returns the local system's host name. See the description of the
268 "new" constructor's "hostname" option.
269 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 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 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
288 Mail::SPF, Mail::SPF::Request, Mail::SPF::Result
289 <http://tools.ietf.org/html/rfc4408>
291 For availability, support, and license information, see the README file
293 included with Mail::SPF.
294
296 Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>
297perl v5.36.0 2023-01-20 Mail::SPF::Server(3)