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