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