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 nxdomains allowed for target lookups for a query and 64 * its subqueries when fallback has kicked in */ 65 #define MAX_TARGET_NX_FALLBACK (MAX_TARGET_NX*2) 66 /** max number of referrals. Makes sure resolver does not run away */ 67 #define MAX_REFERRAL_COUNT 130 68 /** max number of queries for which to perform dnsseclameness detection, 69 * (rrsigs missing detection) after that, just pick up that response */ 70 #define DNSSEC_LAME_DETECT_COUNT 4 71 /** 72 * max number of QNAME minimisation iterations. Limits number of queries for 73 * QNAMEs with a lot of labels. 74 */ 75 #define MAX_MINIMISE_COUNT 10 76 /* max number of time-outs for minimised query. Prevents resolving failures 77 * when the QNAME minimisation QTYPE is blocked. */ 78 #define MAX_MINIMISE_TIMEOUT_COUNT 3 79 /** 80 * number of labels from QNAME that are always send individually when using 81 * QNAME minimisation, even when the number of labels of the QNAME is bigger 82 * than MAX_MINIMISE_COUNT */ 83 #define MINIMISE_ONE_LAB 4 84 #define MINIMISE_MULTIPLE_LABS (MAX_MINIMISE_COUNT - MINIMISE_ONE_LAB) 85 /** at what query-sent-count to stop target fetch policy */ 86 #define TARGET_FETCH_STOP 3 87 /** how nice is a server without further information, in msec 88 * Equals rtt initial timeout value. 89 */ 90 extern int UNKNOWN_SERVER_NICENESS; 91 /** maximum timeout before a host is deemed unsuitable, in msec. 92 * After host_ttl this will be timed out and the host will be tried again. 93 * Equals RTT_MAX_TIMEOUT, and thus when RTT_MAX_TIMEOUT is overwritten by 94 * config infra_cache_max_rtt, it will be overwritten as well. */ 95 extern int USEFUL_SERVER_TOP_TIMEOUT; 96 /** penalty to validation failed blacklisted IPs 97 * Equals USEFUL_SERVER_TOP_TIMEOUT*4, and thus when RTT_MAX_TIMEOUT is 98 * overwritten by config infra_cache_max_rtt, it will be overwritten as well. */ 99 extern int BLACKLIST_PENALTY; 100 /** RTT band, within this amount from the best, servers are chosen randomly. 101 * Chosen so that the UNKNOWN_SERVER_NICENESS falls within the band of a 102 * fast server, this causes server exploration as a side benefit. msec. */ 103 #define RTT_BAND 400 104 105 /** 106 * Global state for the iterator. 107 */ 108 struct iter_env { 109 /** A flag to indicate whether or not we have an IPv6 route */ 110 int supports_ipv6; 111 112 /** A flag to indicate whether or not we have an IPv4 route */ 113 int supports_ipv4; 114 115 /** A set of inetaddrs that should never be queried. */ 116 struct iter_donotq* donotq; 117 118 /** private address space and private domains */ 119 struct iter_priv* priv; 120 121 /** whitelist for capsforid names */ 122 struct rbtree_type* caps_white; 123 124 /** The maximum dependency depth that this resolver will pursue. */ 125 int max_dependency_depth; 126 127 /** 128 * The target fetch policy for each dependency level. This is 129 * described as a simple number (per dependency level): 130 * negative numbers (usually just -1) mean fetch-all, 131 * 0 means only fetch on demand, and 132 * positive numbers mean to fetch at most that many targets. 133 * array of max_dependency_depth+1 size. 134 */ 135 int* target_fetch_policy; 136 137 /** lock on ratelimit counter */ 138 lock_basic_type queries_ratelimit_lock; 139 /** number of queries that have been ratelimited */ 140 size_t num_queries_ratelimited; 141 142 /** number of retries on outgoing queries */ 143 int outbound_msg_retry; 144 145 /** number of queries_sent */ 146 int max_sent_count; 147 148 /** max number of query restarts to limit length of CNAME chain */ 149 int max_query_restarts; 150 }; 151 152 /** 153 * QNAME minimisation state 154 */ 155 enum minimisation_state { 156 /** 157 * (Re)start minimisation. Outgoing QNAME should be set to dp->name. 158 * State entered on new query or after following referral or CNAME. 159 */ 160 INIT_MINIMISE_STATE = 0, 161 /** 162 * QNAME minimisation ongoing. Increase QNAME on every iteration. 163 */ 164 MINIMISE_STATE, 165 /** 166 * Don't increment QNAME this iteration 167 */ 168 SKIP_MINIMISE_STATE, 169 /** 170 * Send out full QNAME + original QTYPE 171 */ 172 DONOT_MINIMISE_STATE, 173 }; 174 175 /** 176 * State of the iterator for a query. 177 */ 178 enum iter_state { 179 /** 180 * Externally generated queries start at this state. Query restarts are 181 * reset to this state. 182 */ 183 INIT_REQUEST_STATE = 0, 184 185 /** 186 * Root priming events reactivate here, most other events pass 187 * through this naturally as the 2nd part of the INIT_REQUEST_STATE. 188 */ 189 INIT_REQUEST_2_STATE, 190 191 /** 192 * Stub priming events reactivate here, most other events pass 193 * through this naturally as the 3rd part of the INIT_REQUEST_STATE. 194 */ 195 INIT_REQUEST_3_STATE, 196 197 /** 198 * Each time a delegation point changes for a given query or a 199 * query times out and/or wakes up, this state is (re)visited. 200 * This state is responsible for iterating through a list of 201 * nameserver targets. 202 */ 203 QUERYTARGETS_STATE, 204 205 /** 206 * Responses to queries start at this state. This state handles 207 * the decision tree associated with handling responses. 208 */ 209 QUERY_RESP_STATE, 210 211 /** Responses to priming queries finish at this state. */ 212 PRIME_RESP_STATE, 213 214 /** Collecting query class information, for qclass=ANY, when 215 * it spawns off queries for every class, it returns here. */ 216 COLLECT_CLASS_STATE, 217 218 /** Find NS record to resolve DS record from, walking to the right 219 * NS spot until we find it */ 220 DSNS_FIND_STATE, 221 222 /** Responses that are to be returned upstream end at this state. 223 * As well as responses to target queries. */ 224 FINISHED_STATE 225 }; 226 227 /** 228 * Shared counters for queries. 229 */ 230 enum target_count_variables { 231 /** Reference count for the shared iter_qstate->target_count. */ 232 TARGET_COUNT_REF = 0, 233 /** Number of target queries spawned for the query and subqueries. */ 234 TARGET_COUNT_QUERIES, 235 /** Number of nxdomain responses encountered. */ 236 TARGET_COUNT_NX, 237 238 /** This should stay last here, it is used for the allocation */ 239 TARGET_COUNT_MAX, 240 }; 241 242 /** 243 * Per query state for the iterator module. 244 */ 245 struct iter_qstate { 246 /** 247 * State of the iterator module. 248 * This is the state that event is in or should sent to -- all 249 * requests should start with the INIT_REQUEST_STATE. All 250 * responses should start with QUERY_RESP_STATE. Subsequent 251 * processing of the event will change this state. 252 */ 253 enum iter_state state; 254 255 /** 256 * Final state for the iterator module. 257 * This is the state that responses should be routed to once the 258 * response is final. For externally initiated queries, this 259 * will be FINISHED_STATE, locally initiated queries will have 260 * different final states. 261 */ 262 enum iter_state final_state; 263 264 /** 265 * The depth of this query, this means the depth of recursion. 266 * This address is needed for another query, which is an address 267 * needed for another query, etc. Original client query has depth 0. 268 */ 269 int depth; 270 271 /** 272 * The response 273 */ 274 struct dns_msg* response; 275 276 /** 277 * This is a list of RRsets that must be prepended to the 278 * ANSWER section of a response before being sent upstream. 279 */ 280 struct iter_prep_list* an_prepend_list; 281 /** Last element of the prepend list */ 282 struct iter_prep_list* an_prepend_last; 283 284 /** 285 * This is the list of RRsets that must be prepended to the 286 * AUTHORITY section of the response before being sent upstream. 287 */ 288 struct iter_prep_list* ns_prepend_list; 289 /** Last element of the authority prepend list */ 290 struct iter_prep_list* ns_prepend_last; 291 292 /** query name used for chasing the results. Initially the same as 293 * the state qinfo, but after CNAMEs this will be different. 294 * The query info used to elicit the results needed. */ 295 struct query_info qchase; 296 /** query flags to use when chasing the answer (i.e. RD flag) */ 297 uint16_t chase_flags; 298 /** true if we set RD bit because of last resort recursion lame query*/ 299 int chase_to_rd; 300 301 /** 302 * This is the current delegation point for an in-progress query. This 303 * object retains state as to which delegation targets need to be 304 * (sub)queried for vs which ones have already been visited. 305 */ 306 struct delegpt* dp; 307 308 /** state for 0x20 fallback when capsfail happens, 0 not a fallback */ 309 int caps_fallback; 310 /** state for capsfail: current server number to try */ 311 size_t caps_server; 312 /** state for capsfail: stored query for comparisons. Can be NULL if 313 * no response had been seen prior to starting the fallback. */ 314 struct reply_info* caps_reply; 315 struct dns_msg* caps_response; 316 317 /** Current delegation message - returned for non-RD queries */ 318 struct dns_msg* deleg_msg; 319 320 /** number of outstanding target sub queries */ 321 int num_target_queries; 322 323 /** outstanding direct queries */ 324 int num_current_queries; 325 326 /** the number of times this query has been restarted. */ 327 int query_restart_count; 328 329 /** the number of times this query has followed a referral. */ 330 int referral_count; 331 332 /** number of queries fired off */ 333 int sent_count; 334 335 /** malloced-array shared with this query and its subqueries. It keeps 336 * track of the defined enum target_count_variables counters. */ 337 int* target_count; 338 339 /** number of target lookups per delegation point. Reset to 0 after 340 * receiving referral answer. Not shared with subqueries. */ 341 int dp_target_count; 342 343 /** Delegation point that triggered the NXNS fallback; shared with 344 * this query and its subqueries, count-referenced by the reference 345 * counter in target_count. 346 * This also marks the fallback activation. */ 347 uint8_t** nxns_dp; 348 349 /** if true, already tested for ratelimiting and passed the test */ 350 int ratelimit_ok; 351 352 /** 353 * The query must store NS records from referrals as parentside RRs 354 * Enabled once it hits resolution problems, to throttle retries. 355 * If enabled it is the pointer to the old delegation point with 356 * the old retry counts for bad-nameserver-addresses. 357 */ 358 struct delegpt* store_parent_NS; 359 360 /** 361 * The query is for parent-side glue(A or AAAA) for a nameserver. 362 * If the item is seen as glue in a referral, and pside_glue is NULL, 363 * then it is stored in pside_glue for later. 364 * If it was never seen, at the end, then a negative caching element 365 * must be created. 366 * The (data or negative) RR cache element then throttles retries. 367 */ 368 int query_for_pside_glue; 369 /** the parent-side-glue element (NULL if none, its first match) */ 370 struct ub_packed_rrset_key* pside_glue; 371 372 /** If nonNULL we are walking upwards from DS query to find NS */ 373 uint8_t* dsns_point; 374 /** length of the dname in dsns_point */ 375 size_t dsns_point_len; 376 377 /** 378 * expected dnssec information for this iteration step. 379 * If dnssec rrsigs are expected and not given, the server is marked 380 * lame (dnssec-lame). 381 */ 382 int dnssec_expected; 383 384 /** 385 * We are expecting dnssec information, but we also know the server 386 * is DNSSEC lame. The response need not be marked dnssec-lame again. 387 */ 388 int dnssec_lame_query; 389 390 /** 391 * This is flag that, if true, means that this event is 392 * waiting for a stub priming query. 393 */ 394 int wait_priming_stub; 395 396 /** 397 * This is a flag that, if true, means that this query is 398 * for (re)fetching glue from a zone. Since the address should 399 * have been glue, query again to the servers that should have 400 * been returning it as glue. 401 * The delegation point must be set to the one that should *not* 402 * be used when creating the state. A higher one will be attempted. 403 */ 404 int refetch_glue; 405 406 /** list of pending queries to authoritative servers. */ 407 struct outbound_list outlist; 408 409 /** QNAME minimisation state, RFC9156 */ 410 enum minimisation_state minimisation_state; 411 412 /** State for capsfail: QNAME minimisation state for comparisons. */ 413 enum minimisation_state caps_minimisation_state; 414 415 /** 416 * The query info that is sent upstream. Will be a subset of qchase 417 * when qname minimisation is enabled. 418 */ 419 struct query_info qinfo_out; 420 421 /** 422 * Count number of QNAME minimisation iterations. Used to limit number of 423 * outgoing queries when QNAME minimisation is enabled. 424 */ 425 int minimise_count; 426 427 /** 428 * Count number of time-outs. Used to prevent resolving failures when 429 * the QNAME minimisation QTYPE is blocked. Used to determine if 430 * capsforid fallback should be started.*/ 431 int timeout_count; 432 433 /** True if the current response is from auth_zone */ 434 int auth_zone_response; 435 /** True if the auth_zones should not be consulted for the query */ 436 int auth_zone_avoid; 437 /** true if there have been scrubbing failures of reply packets */ 438 int scrub_failures; 439 /** true if there have been parse failures of reply packets */ 440 int parse_failures; 441 /** a failure printout address for last received answer */ 442 struct comm_reply* fail_reply; 443 }; 444 445 /** 446 * List of prepend items 447 */ 448 struct iter_prep_list { 449 /** next in list */ 450 struct iter_prep_list* next; 451 /** rrset */ 452 struct ub_packed_rrset_key* rrset; 453 }; 454 455 /** 456 * Get the iterator function block. 457 * @return: function block with function pointers to iterator methods. 458 */ 459 struct module_func_block* iter_get_funcblock(void); 460 461 /** 462 * Get iterator state as a string 463 * @param state: to convert 464 * @return constant string that is printable. 465 */ 466 const char* iter_state_to_string(enum iter_state state); 467 468 /** 469 * See if iterator state is a response state 470 * @param s: to inspect 471 * @return true if response state. 472 */ 473 int iter_state_is_responsestate(enum iter_state s); 474 475 /** iterator init */ 476 int iter_init(struct module_env* env, int id); 477 478 /** iterator deinit */ 479 void iter_deinit(struct module_env* env, int id); 480 481 /** iterator operate on a query */ 482 void iter_operate(struct module_qstate* qstate, enum module_ev event, int id, 483 struct outbound_entry* outbound); 484 485 /** 486 * Return priming query results to interested super querystates. 487 * 488 * Sets the delegation point and delegation message (not nonRD queries). 489 * This is a callback from walk_supers. 490 * 491 * @param qstate: query state that finished. 492 * @param id: module id. 493 * @param super: the qstate to inform. 494 */ 495 void iter_inform_super(struct module_qstate* qstate, int id, 496 struct module_qstate* super); 497 498 /** iterator cleanup query state */ 499 void iter_clear(struct module_qstate* qstate, int id); 500 501 /** iterator alloc size routine */ 502 size_t iter_get_mem(struct module_env* env, int id); 503 504 #endif /* ITERATOR_ITERATOR_H */ 505