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 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 */