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