xref: /freebsd/contrib/unbound/iterator/iterator.h (revision 8d20be1e22095c27faf8fe8b2f0d089739cc742e)
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 LIMITED
25  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
26  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
27  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
28  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
32  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33  * POSSIBILITY OF SUCH DAMAGE.
34  */
35 
36 /**
37  * \file
38  *
39  * This file contains a module that performs recusive 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 
55 /** max number of query restarts. Determines max number of CNAME chain. */
56 #define MAX_RESTART_COUNT       8
57 /** max number of referrals. Makes sure resolver does not run away */
58 #define MAX_REFERRAL_COUNT	130
59 /** max number of queries-sent-out.  Make sure large NS set does not loop */
60 #define MAX_SENT_COUNT		16
61 /** at what query-sent-count to stop target fetch policy */
62 #define TARGET_FETCH_STOP	3
63 /** how nice is a server without further information, in msec
64  * Equals rtt initial timeout value.
65  */
66 #define UNKNOWN_SERVER_NICENESS 376
67 /** maximum timeout before a host is deemed unsuitable, in msec.
68  * After host_ttl this will be timed out and the host will be tried again.
69  * Equals RTT_MAX_TIMEOUT
70  */
71 #define USEFUL_SERVER_TOP_TIMEOUT	120000
72 /** Number of lost messages in a row that get a host blacklisted.
73  * With 16, a couple different queries have to time out and no working
74  * queries are happening */
75 #define USEFUL_SERVER_MAX_LOST	16
76 /** number of retries on outgoing queries */
77 #define OUTBOUND_MSG_RETRY 5
78 /** RTT band, within this amount from the best, servers are chosen randomly.
79  * Chosen so that the UNKNOWN_SERVER_NICENESS falls within the band of a
80  * fast server, this causes server exploration as a side benefit. msec. */
81 #define RTT_BAND 400
82 /** Start value for blacklisting a host, 2*USEFUL_SERVER_TOP_TIMEOUT in sec */
83 #define INFRA_BACKOFF_INITIAL 240
84 
85 /**
86  * Global state for the iterator.
87  */
88 struct iter_env {
89 	/** A flag to indicate whether or not we have an IPv6 route */
90 	int supports_ipv6;
91 
92 	/** A flag to indicate whether or not we have an IPv4 route */
93 	int supports_ipv4;
94 
95 	/** A set of inetaddrs that should never be queried. */
96 	struct iter_donotq* donotq;
97 
98 	/** private address space and private domains */
99 	struct iter_priv* priv;
100 
101 	/** The maximum dependency depth that this resolver will pursue. */
102 	int max_dependency_depth;
103 
104 	/**
105 	 * The target fetch policy for each dependency level. This is
106 	 * described as a simple number (per dependency level):
107 	 *	negative numbers (usually just -1) mean fetch-all,
108 	 *	0 means only fetch on demand, and
109 	 *	positive numbers mean to fetch at most that many targets.
110 	 * array of max_dependency_depth+1 size.
111 	 */
112 	int* target_fetch_policy;
113 };
114 
115 /**
116  * State of the iterator for a query.
117  */
118 enum iter_state {
119 	/**
120 	 * Externally generated queries start at this state. Query restarts are
121 	 * reset to this state.
122 	 */
123 	INIT_REQUEST_STATE = 0,
124 
125 	/**
126 	 * Root priming events reactivate here, most other events pass
127 	 * through this naturally as the 2nd part of the INIT_REQUEST_STATE.
128 	 */
129 	INIT_REQUEST_2_STATE,
130 
131 	/**
132 	 * Stub priming events reactivate here, most other events pass
133 	 * through this naturally as the 3rd part of the INIT_REQUEST_STATE.
134 	 */
135 	INIT_REQUEST_3_STATE,
136 
137 	/**
138 	 * Each time a delegation point changes for a given query or a
139 	 * query times out and/or wakes up, this state is (re)visited.
140 	 * This state is reponsible for iterating through a list of
141 	 * nameserver targets.
142 	 */
143 	QUERYTARGETS_STATE,
144 
145 	/**
146 	 * Responses to queries start at this state. This state handles
147 	 * the decision tree associated with handling responses.
148 	 */
149 	QUERY_RESP_STATE,
150 
151 	/** Responses to priming queries finish at this state. */
152 	PRIME_RESP_STATE,
153 
154 	/** Collecting query class information, for qclass=ANY, when
155 	 * it spawns off queries for every class, it returns here. */
156 	COLLECT_CLASS_STATE,
157 
158 	/** Find NS record to resolve DS record from, walking to the right
159 	 * NS spot until we find it */
160 	DSNS_FIND_STATE,
161 
162 	/** Responses that are to be returned upstream end at this state.
163 	 * As well as responses to target queries. */
164 	FINISHED_STATE
165 };
166 
167 /**
168  * Per query state for the iterator module.
169  */
170 struct iter_qstate {
171 	/**
172 	 * State of the iterator module.
173 	 * This is the state that event is in or should sent to -- all
174 	 * requests should start with the INIT_REQUEST_STATE. All
175 	 * responses should start with QUERY_RESP_STATE. Subsequent
176 	 * processing of the event will change this state.
177 	 */
178 	enum iter_state state;
179 
180 	/**
181 	 * Final state for the iterator module.
182 	 * This is the state that responses should be routed to once the
183 	 * response is final. For externally initiated queries, this
184 	 * will be FINISHED_STATE, locally initiated queries will have
185 	 * different final states.
186 	 */
187 	enum iter_state final_state;
188 
189 	/**
190 	 * The depth of this query, this means the depth of recursion.
191 	 * This address is needed for another query, which is an address
192 	 * needed for another query, etc. Original client query has depth 0.
193 	 */
194 	int depth;
195 
196 	/**
197 	 * The response
198 	 */
199 	struct dns_msg* response;
200 
201 	/**
202 	 * This is a list of RRsets that must be prepended to the
203 	 * ANSWER section of a response before being sent upstream.
204 	 */
205 	struct iter_prep_list* an_prepend_list;
206 	/** Last element of the prepend list */
207 	struct iter_prep_list* an_prepend_last;
208 
209 	/**
210 	 * This is the list of RRsets that must be prepended to the
211 	 * AUTHORITY section of the response before being sent upstream.
212 	 */
213 	struct iter_prep_list* ns_prepend_list;
214 	/** Last element of the authority prepend list */
215 	struct iter_prep_list* ns_prepend_last;
216 
217 	/** query name used for chasing the results. Initially the same as
218 	 * the state qinfo, but after CNAMEs this will be different.
219 	 * The query info used to elicit the results needed. */
220 	struct query_info qchase;
221 	/** query flags to use when chasing the answer (i.e. RD flag) */
222 	uint16_t chase_flags;
223 	/** true if we set RD bit because of last resort recursion lame query*/
224 	int chase_to_rd;
225 
226 	/**
227 	 * This is the current delegation point for an in-progress query. This
228 	 * object retains state as to which delegation targets need to be
229 	 * (sub)queried for vs which ones have already been visited.
230 	 */
231 	struct delegpt* dp;
232 
233 	/** state for 0x20 fallback when capsfail happens, 0 not a fallback */
234 	int caps_fallback;
235 	/** state for capsfail: current server number to try */
236 	size_t caps_server;
237 	/** state for capsfail: stored query for comparisons */
238 	struct reply_info* caps_reply;
239 
240 	/** Current delegation message - returned for non-RD queries */
241 	struct dns_msg* deleg_msg;
242 
243 	/** number of outstanding target sub queries */
244 	int num_target_queries;
245 
246 	/** outstanding direct queries */
247 	int num_current_queries;
248 
249 	/** the number of times this query has been restarted. */
250 	int query_restart_count;
251 
252 	/** the number of times this query as followed a referral. */
253 	int referral_count;
254 
255 	/** number of queries fired off */
256 	int sent_count;
257 
258 	/**
259 	 * The query must store NS records from referrals as parentside RRs
260 	 * Enabled once it hits resolution problems, to throttle retries.
261 	 * If enabled it is the pointer to the old delegation point with
262 	 * the old retry counts for bad-nameserver-addresses.
263 	 */
264 	struct delegpt* store_parent_NS;
265 
266 	/**
267 	 * The query is for parent-side glue(A or AAAA) for a nameserver.
268 	 * If the item is seen as glue in a referral, and pside_glue is NULL,
269 	 * then it is stored in pside_glue for later.
270 	 * If it was never seen, at the end, then a negative caching element
271 	 * must be created.
272 	 * The (data or negative) RR cache element then throttles retries.
273 	 */
274 	int query_for_pside_glue;
275 	/** the parent-side-glue element (NULL if none, its first match) */
276 	struct ub_packed_rrset_key* pside_glue;
277 
278 	/** If nonNULL we are walking upwards from DS query to find NS */
279 	uint8_t* dsns_point;
280 	/** length of the dname in dsns_point */
281 	size_t dsns_point_len;
282 
283 	/**
284 	 * expected dnssec information for this iteration step.
285 	 * If dnssec rrsigs are expected and not given, the server is marked
286 	 * lame (dnssec-lame).
287 	 */
288 	int dnssec_expected;
289 
290 	/**
291 	 * We are expecting dnssec information, but we also know the server
292 	 * is DNSSEC lame.  The response need not be marked dnssec-lame again.
293 	 */
294 	int dnssec_lame_query;
295 
296 	/**
297 	 * This is flag that, if true, means that this event is
298 	 * waiting for a stub priming query.
299 	 */
300 	int wait_priming_stub;
301 
302 	/**
303 	 * This is a flag that, if true, means that this query is
304 	 * for (re)fetching glue from a zone. Since the address should
305 	 * have been glue, query again to the servers that should have
306 	 * been returning it as glue.
307 	 * The delegation point must be set to the one that should *not*
308 	 * be used when creating the state. A higher one will be attempted.
309 	 */
310 	int refetch_glue;
311 
312 	/** list of pending queries to authoritative servers. */
313 	struct outbound_list outlist;
314 };
315 
316 /**
317  * List of prepend items
318  */
319 struct iter_prep_list {
320 	/** next in list */
321 	struct iter_prep_list* next;
322 	/** rrset */
323 	struct ub_packed_rrset_key* rrset;
324 };
325 
326 /**
327  * Get the iterator function block.
328  * @return: function block with function pointers to iterator methods.
329  */
330 struct module_func_block* iter_get_funcblock(void);
331 
332 /**
333  * Get iterator state as a string
334  * @param state: to convert
335  * @return constant string that is printable.
336  */
337 const char* iter_state_to_string(enum iter_state state);
338 
339 /**
340  * See if iterator state is a response state
341  * @param s: to inspect
342  * @return true if response state.
343  */
344 int iter_state_is_responsestate(enum iter_state s);
345 
346 /** iterator init */
347 int iter_init(struct module_env* env, int id);
348 
349 /** iterator deinit */
350 void iter_deinit(struct module_env* env, int id);
351 
352 /** iterator operate on a query */
353 void iter_operate(struct module_qstate* qstate, enum module_ev event, int id,
354 	struct outbound_entry* outbound);
355 
356 /**
357  * Return priming query results to interestes super querystates.
358  *
359  * Sets the delegation point and delegation message (not nonRD queries).
360  * This is a callback from walk_supers.
361  *
362  * @param qstate: query state that finished.
363  * @param id: module id.
364  * @param super: the qstate to inform.
365  */
366 void iter_inform_super(struct module_qstate* qstate, int id,
367 	struct module_qstate* super);
368 
369 /** iterator cleanup query state */
370 void iter_clear(struct module_qstate* qstate, int id);
371 
372 /** iterator alloc size routine */
373 size_t iter_get_mem(struct module_env* env, int id);
374 
375 #endif /* ITERATOR_ITERATOR_H */
376