xref: /freebsd/contrib/unbound/iterator/iterator.h (revision c66ec88fed842fbaad62c30d510644ceb7bd2d71)
1 /*
2  * iterator/iterator.h - iterative resolver DNS query response module
3  *
4  * Copyright (c) 2007, NLnet Labs. All rights reserved.
5  *
6  * This software is open source.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * Redistributions of source code must retain the above copyright notice,
13  * this list of conditions and the following disclaimer.
14  *
15  * Redistributions in binary form must reproduce the above copyright notice,
16  * this list of conditions and the following disclaimer in the documentation
17  * and/or other materials provided with the distribution.
18  *
19  * Neither the name of the NLNET LABS nor the names of its contributors may
20  * be used to endorse or promote products derived from this software without
21  * specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
26  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
27  * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
28  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
29  * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
30  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
31  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
32  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
33  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34  */
35 
36 /**
37  * \file
38  *
39  * This file contains a module that performs recursive iterative DNS query
40  * processing.
41  */
42 
43 #ifndef ITERATOR_ITERATOR_H
44 #define ITERATOR_ITERATOR_H
45 #include "services/outbound_list.h"
46 #include "util/data/msgreply.h"
47 #include "util/module.h"
48 struct delegpt;
49 struct iter_hints;
50 struct iter_forwards;
51 struct iter_donotq;
52 struct iter_prep_list;
53 struct iter_priv;
54 struct rbtree_type;
55 
56 /** max number of targets spawned for a query and its subqueries */
57 #define MAX_TARGET_COUNT	64
58 /** max number of target lookups per qstate, per delegation point */
59 #define MAX_DP_TARGET_COUNT	16
60 /** max number of nxdomains allowed for target lookups for a query and
61  * its subqueries */
62 #define MAX_TARGET_NX		5
63 /** max number of query restarts. Determines max number of CNAME chain. */
64 #define MAX_RESTART_COUNT       8
65 /** max number of referrals. Makes sure resolver does not run away */
66 #define MAX_REFERRAL_COUNT	130
67 /** max number of queries-sent-out.  Make sure large NS set does not loop */
68 #define MAX_SENT_COUNT		32
69 /** max number of queries for which to perform dnsseclameness detection,
70  * (rrsigs missing detection) after that, just pick up that response */
71 #define DNSSEC_LAME_DETECT_COUNT 4
72 /**
73  * max number of QNAME minimisation iterations. Limits number of queries for
74  * QNAMEs with a lot of labels.
75 */
76 #define MAX_MINIMISE_COUNT	10
77 /* max number of time-outs for minimised query. Prevents resolving failures
78  * when the QNAME minimisation QTYPE is blocked. */
79 #define MAX_MINIMISE_TIMEOUT_COUNT 3
80 /**
81  * number of labels from QNAME that are always send individually when using
82  * QNAME minimisation, even when the number of labels of the QNAME is bigger
83  * tham MAX_MINIMISE_COUNT */
84 #define MINIMISE_ONE_LAB	4
85 #define MINIMISE_MULTIPLE_LABS	(MAX_MINIMISE_COUNT - MINIMISE_ONE_LAB)
86 /** at what query-sent-count to stop target fetch policy */
87 #define TARGET_FETCH_STOP	3
88 /** how nice is a server without further information, in msec
89  * Equals rtt initial timeout value.
90  */
91 extern int UNKNOWN_SERVER_NICENESS;
92 /** maximum timeout before a host is deemed unsuitable, in msec.
93  * After host_ttl this will be timed out and the host will be tried again.
94  * Equals RTT_MAX_TIMEOUT
95  */
96 #define USEFUL_SERVER_TOP_TIMEOUT	120000
97 /** number of retries on outgoing queries */
98 #define OUTBOUND_MSG_RETRY 5
99 /** RTT band, within this amount from the best, servers are chosen randomly.
100  * Chosen so that the UNKNOWN_SERVER_NICENESS falls within the band of a
101  * fast server, this causes server exploration as a side benefit. msec. */
102 #define RTT_BAND 400
103 /** Start value for blacklisting a host, 2*USEFUL_SERVER_TOP_TIMEOUT in sec */
104 #define INFRA_BACKOFF_INITIAL 240
105 
106 /**
107  * Global state for the iterator.
108  */
109 struct iter_env {
110 	/** A flag to indicate whether or not we have an IPv6 route */
111 	int supports_ipv6;
112 
113 	/** A flag to indicate whether or not we have an IPv4 route */
114 	int supports_ipv4;
115 
116 	/** A set of inetaddrs that should never be queried. */
117 	struct iter_donotq* donotq;
118 
119 	/** private address space and private domains */
120 	struct iter_priv* priv;
121 
122 	/** whitelist for capsforid names */
123 	struct rbtree_type* caps_white;
124 
125 	/** The maximum dependency depth that this resolver will pursue. */
126 	int max_dependency_depth;
127 
128 	/**
129 	 * The target fetch policy for each dependency level. This is
130 	 * described as a simple number (per dependency level):
131 	 *	negative numbers (usually just -1) mean fetch-all,
132 	 *	0 means only fetch on demand, and
133 	 *	positive numbers mean to fetch at most that many targets.
134 	 * array of max_dependency_depth+1 size.
135 	 */
136 	int* target_fetch_policy;
137 
138 	/** lock on ratelimit counter */
139 	lock_basic_type queries_ratelimit_lock;
140 	/** number of queries that have been ratelimited */
141 	size_t num_queries_ratelimited;
142 };
143 
144 /**
145  * QNAME minimisation state
146  */
147 enum minimisation_state {
148 	/**
149 	 * (Re)start minimisation. Outgoing QNAME should be set to dp->name.
150 	 * State entered on new query or after following referral or CNAME.
151 	 */
152 	INIT_MINIMISE_STATE = 0,
153 	/**
154 	 * QNAME minimisation ongoing. Increase QNAME on every iteration.
155 	 */
156 	MINIMISE_STATE,
157 	/**
158 	 * Don't increment QNAME this iteration
159 	 */
160 	SKIP_MINIMISE_STATE,
161 	/**
162 	 * Send out full QNAME + original QTYPE
163 	 */
164 	DONOT_MINIMISE_STATE,
165 };
166 
167 /**
168  * State of the iterator for a query.
169  */
170 enum iter_state {
171 	/**
172 	 * Externally generated queries start at this state. Query restarts are
173 	 * reset to this state.
174 	 */
175 	INIT_REQUEST_STATE = 0,
176 
177 	/**
178 	 * Root priming events reactivate here, most other events pass
179 	 * through this naturally as the 2nd part of the INIT_REQUEST_STATE.
180 	 */
181 	INIT_REQUEST_2_STATE,
182 
183 	/**
184 	 * Stub priming events reactivate here, most other events pass
185 	 * through this naturally as the 3rd part of the INIT_REQUEST_STATE.
186 	 */
187 	INIT_REQUEST_3_STATE,
188 
189 	/**
190 	 * Each time a delegation point changes for a given query or a
191 	 * query times out and/or wakes up, this state is (re)visited.
192 	 * This state is responsible for iterating through a list of
193 	 * nameserver targets.
194 	 */
195 	QUERYTARGETS_STATE,
196 
197 	/**
198 	 * Responses to queries start at this state. This state handles
199 	 * the decision tree associated with handling responses.
200 	 */
201 	QUERY_RESP_STATE,
202 
203 	/** Responses to priming queries finish at this state. */
204 	PRIME_RESP_STATE,
205 
206 	/** Collecting query class information, for qclass=ANY, when
207 	 * it spawns off queries for every class, it returns here. */
208 	COLLECT_CLASS_STATE,
209 
210 	/** Find NS record to resolve DS record from, walking to the right
211 	 * NS spot until we find it */
212 	DSNS_FIND_STATE,
213 
214 	/** Responses that are to be returned upstream end at this state.
215 	 * As well as responses to target queries. */
216 	FINISHED_STATE
217 };
218 
219 /**
220  * Per query state for the iterator module.
221  */
222 struct iter_qstate {
223 	/**
224 	 * State of the iterator module.
225 	 * This is the state that event is in or should sent to -- all
226 	 * requests should start with the INIT_REQUEST_STATE. All
227 	 * responses should start with QUERY_RESP_STATE. Subsequent
228 	 * processing of the event will change this state.
229 	 */
230 	enum iter_state state;
231 
232 	/**
233 	 * Final state for the iterator module.
234 	 * This is the state that responses should be routed to once the
235 	 * response is final. For externally initiated queries, this
236 	 * will be FINISHED_STATE, locally initiated queries will have
237 	 * different final states.
238 	 */
239 	enum iter_state final_state;
240 
241 	/**
242 	 * The depth of this query, this means the depth of recursion.
243 	 * This address is needed for another query, which is an address
244 	 * needed for another query, etc. Original client query has depth 0.
245 	 */
246 	int depth;
247 
248 	/**
249 	 * The response
250 	 */
251 	struct dns_msg* response;
252 
253 	/**
254 	 * This is a list of RRsets that must be prepended to the
255 	 * ANSWER section of a response before being sent upstream.
256 	 */
257 	struct iter_prep_list* an_prepend_list;
258 	/** Last element of the prepend list */
259 	struct iter_prep_list* an_prepend_last;
260 
261 	/**
262 	 * This is the list of RRsets that must be prepended to the
263 	 * AUTHORITY section of the response before being sent upstream.
264 	 */
265 	struct iter_prep_list* ns_prepend_list;
266 	/** Last element of the authority prepend list */
267 	struct iter_prep_list* ns_prepend_last;
268 
269 	/** query name used for chasing the results. Initially the same as
270 	 * the state qinfo, but after CNAMEs this will be different.
271 	 * The query info used to elicit the results needed. */
272 	struct query_info qchase;
273 	/** query flags to use when chasing the answer (i.e. RD flag) */
274 	uint16_t chase_flags;
275 	/** true if we set RD bit because of last resort recursion lame query*/
276 	int chase_to_rd;
277 
278 	/**
279 	 * This is the current delegation point for an in-progress query. This
280 	 * object retains state as to which delegation targets need to be
281 	 * (sub)queried for vs which ones have already been visited.
282 	 */
283 	struct delegpt* dp;
284 
285 	/** state for 0x20 fallback when capsfail happens, 0 not a fallback */
286 	int caps_fallback;
287 	/** state for capsfail: current server number to try */
288 	size_t caps_server;
289 	/** state for capsfail: stored query for comparisons. Can be NULL if
290 	 * no response had been seen prior to starting the fallback. */
291 	struct reply_info* caps_reply;
292 	struct dns_msg* caps_response;
293 
294 	/** Current delegation message - returned for non-RD queries */
295 	struct dns_msg* deleg_msg;
296 
297 	/** number of outstanding target sub queries */
298 	int num_target_queries;
299 
300 	/** outstanding direct queries */
301 	int num_current_queries;
302 
303 	/** the number of times this query has been restarted. */
304 	int query_restart_count;
305 
306 	/** the number of times this query as followed a referral. */
307 	int referral_count;
308 
309 	/** number of queries fired off */
310 	int sent_count;
311 
312 	/** number of target queries spawned in [1], for this query and its
313 	 * subqueries, the malloced-array is shared, [0] refcount.
314 	 * in [2] the number of nxdomains is counted. */
315 	int* target_count;
316 
317 	/** number of target lookups per delegation point. Reset to 0 after
318 	 * receiving referral answer. Not shared with subqueries. */
319 	int dp_target_count;
320 
321 	/** if true, already tested for ratelimiting and passed the test */
322 	int ratelimit_ok;
323 
324 	/**
325 	 * The query must store NS records from referrals as parentside RRs
326 	 * Enabled once it hits resolution problems, to throttle retries.
327 	 * If enabled it is the pointer to the old delegation point with
328 	 * the old retry counts for bad-nameserver-addresses.
329 	 */
330 	struct delegpt* store_parent_NS;
331 
332 	/**
333 	 * The query is for parent-side glue(A or AAAA) for a nameserver.
334 	 * If the item is seen as glue in a referral, and pside_glue is NULL,
335 	 * then it is stored in pside_glue for later.
336 	 * If it was never seen, at the end, then a negative caching element
337 	 * must be created.
338 	 * The (data or negative) RR cache element then throttles retries.
339 	 */
340 	int query_for_pside_glue;
341 	/** the parent-side-glue element (NULL if none, its first match) */
342 	struct ub_packed_rrset_key* pside_glue;
343 
344 	/** If nonNULL we are walking upwards from DS query to find NS */
345 	uint8_t* dsns_point;
346 	/** length of the dname in dsns_point */
347 	size_t dsns_point_len;
348 
349 	/**
350 	 * expected dnssec information for this iteration step.
351 	 * If dnssec rrsigs are expected and not given, the server is marked
352 	 * lame (dnssec-lame).
353 	 */
354 	int dnssec_expected;
355 
356 	/**
357 	 * We are expecting dnssec information, but we also know the server
358 	 * is DNSSEC lame.  The response need not be marked dnssec-lame again.
359 	 */
360 	int dnssec_lame_query;
361 
362 	/**
363 	 * This is flag that, if true, means that this event is
364 	 * waiting for a stub priming query.
365 	 */
366 	int wait_priming_stub;
367 
368 	/**
369 	 * This is a flag that, if true, means that this query is
370 	 * for (re)fetching glue from a zone. Since the address should
371 	 * have been glue, query again to the servers that should have
372 	 * been returning it as glue.
373 	 * The delegation point must be set to the one that should *not*
374 	 * be used when creating the state. A higher one will be attempted.
375 	 */
376 	int refetch_glue;
377 
378 	/** list of pending queries to authoritative servers. */
379 	struct outbound_list outlist;
380 
381 	/** QNAME minimisation state, RFC7816 */
382 	enum minimisation_state minimisation_state;
383 
384 	/** State for capsfail: QNAME minimisation state for comparisons. */
385 	enum minimisation_state caps_minimisation_state;
386 
387 	/**
388 	 * The query info that is sent upstream. Will be a subset of qchase
389 	 * when qname minimisation is enabled.
390 	 */
391 	struct query_info qinfo_out;
392 
393 	/**
394 	 * Count number of QNAME minimisation iterations. Used to limit number of
395 	 * outgoing queries when QNAME minimisation is enabled.
396 	 */
397 	int minimise_count;
398 
399 	/**
400 	 * Count number of time-outs. Used to prevent resolving failures when
401 	 * the QNAME minimisation QTYPE is blocked. Used to determine if
402 	 * capsforid fallback should be started.*/
403 	int timeout_count;
404 
405 	/** True if the current response is from auth_zone */
406 	int auth_zone_response;
407 	/** True if the auth_zones should not be consulted for the query */
408 	int auth_zone_avoid;
409 };
410 
411 /**
412  * List of prepend items
413  */
414 struct iter_prep_list {
415 	/** next in list */
416 	struct iter_prep_list* next;
417 	/** rrset */
418 	struct ub_packed_rrset_key* rrset;
419 };
420 
421 /**
422  * Get the iterator function block.
423  * @return: function block with function pointers to iterator methods.
424  */
425 struct module_func_block* iter_get_funcblock(void);
426 
427 /**
428  * Get iterator state as a string
429  * @param state: to convert
430  * @return constant string that is printable.
431  */
432 const char* iter_state_to_string(enum iter_state state);
433 
434 /**
435  * See if iterator state is a response state
436  * @param s: to inspect
437  * @return true if response state.
438  */
439 int iter_state_is_responsestate(enum iter_state s);
440 
441 /** iterator init */
442 int iter_init(struct module_env* env, int id);
443 
444 /** iterator deinit */
445 void iter_deinit(struct module_env* env, int id);
446 
447 /** iterator operate on a query */
448 void iter_operate(struct module_qstate* qstate, enum module_ev event, int id,
449 	struct outbound_entry* outbound);
450 
451 /**
452  * Return priming query results to interested super querystates.
453  *
454  * Sets the delegation point and delegation message (not nonRD queries).
455  * This is a callback from walk_supers.
456  *
457  * @param qstate: query state that finished.
458  * @param id: module id.
459  * @param super: the qstate to inform.
460  */
461 void iter_inform_super(struct module_qstate* qstate, int id,
462 	struct module_qstate* super);
463 
464 /** iterator cleanup query state */
465 void iter_clear(struct module_qstate* qstate, int id);
466 
467 /** iterator alloc size routine */
468 size_t iter_get_mem(struct module_env* env, int id);
469 
470 #endif /* ITERATOR_ITERATOR_H */
471