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