contrib/unbound/iterator/iterator.h

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