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 /** Number of retries for empty nodata packets before it is accepted. */
 105 #define EMPTY_NODATA_RETRY_COUNT 2
 106
 107 /**
 108  * Global state for the iterator.
 109  */
 110 struct iter_env {
 111         /** A flag to indicate whether or not we have an IPv6 route */
 112         int supports_ipv6;
 113
 114         /** A flag to indicate whether or not we have an IPv4 route */
 115         int supports_ipv4;
 116
 117         /** A flag to locally apply NAT64 to make IPv4 addrs into IPv6 */
 118         int use_nat64;
 119
 120         /** NAT64 prefix address, cf. dns64_env->prefix_addr */
 121         struct sockaddr_storage nat64_prefix_addr;
 122
 123         /** sizeof(sockaddr_in6) */
 124         socklen_t nat64_prefix_addrlen;
 125
 126         /** CIDR mask length of NAT64 prefix */
 127         int nat64_prefix_net;
 128
 129         /** A set of inetaddrs that should never be queried. */
 130         struct iter_donotq* donotq;
 131
 132         /** private address space and private domains */
 133         struct iter_priv* priv;
 134
 135         /** whitelist for capsforid names */
 136         struct rbtree_type* caps_white;
 137
 138         /** The maximum dependency depth that this resolver will pursue. */
 139         int max_dependency_depth;
 140
 141         /**
 142          * The target fetch policy for each dependency level. This is
 143          * described as a simple number (per dependency level):
 144          *      negative numbers (usually just -1) mean fetch-all,
 145          *      0 means only fetch on demand, and
 146          *      positive numbers mean to fetch at most that many targets.
 147          * array of max_dependency_depth+1 size.
 148          */
 149         int* target_fetch_policy;
 150
 151         /** lock on ratelimit counter */
 152         lock_basic_type queries_ratelimit_lock;
 153         /** number of queries that have been ratelimited */
 154         size_t num_queries_ratelimited;
 155
 156         /** number of retries on outgoing queries */
 157         int outbound_msg_retry;
 158
 159         /** number of queries_sent */
 160         int max_sent_count;
 161
 162         /** max number of query restarts to limit length of CNAME chain */
 163         int max_query_restarts;
 164 };
 165
 166 /**
 167  * QNAME minimisation state
 168  */
 169 enum minimisation_state {
 170         /**
 171          * (Re)start minimisation. Outgoing QNAME should be set to dp->name.
 172          * State entered on new query or after following referral or CNAME.
 173          */
 174         INIT_MINIMISE_STATE = 0,
 175         /**
 176          * QNAME minimisation ongoing. Increase QNAME on every iteration.
 177          */
 178         MINIMISE_STATE,
 179         /**
 180          * Don't increment QNAME this iteration
 181          */
 182         SKIP_MINIMISE_STATE,
 183         /**
 184          * Send out full QNAME + original QTYPE
 185          */
 186         DONOT_MINIMISE_STATE,
 187 };
 188
 189 /**
 190  * State of the iterator for a query.
 191  */
 192 enum iter_state {
 193         /**
 194          * Externally generated queries start at this state. Query restarts are
 195          * reset to this state.
 196          */
 197         INIT_REQUEST_STATE = 0,
 198
 199         /**
 200          * Root priming events reactivate here, most other events pass
 201          * through this naturally as the 2nd part of the INIT_REQUEST_STATE.
 202          */
 203         INIT_REQUEST_2_STATE,
 204
 205         /**
 206          * Stub priming events reactivate here, most other events pass
 207          * through this naturally as the 3rd part of the INIT_REQUEST_STATE.
 208          */
 209         INIT_REQUEST_3_STATE,
 210
 211         /**
 212          * Each time a delegation point changes for a given query or a
 213          * query times out and/or wakes up, this state is (re)visited.
 214          * This state is responsible for iterating through a list of
 215          * nameserver targets.
 216          */
 217         QUERYTARGETS_STATE,
 218
 219         /**
 220          * Responses to queries start at this state. This state handles
 221          * the decision tree associated with handling responses.
 222          */
 223         QUERY_RESP_STATE,
 224
 225         /** Responses to priming queries finish at this state. */
 226         PRIME_RESP_STATE,
 227
 228         /** Collecting query class information, for qclass=ANY, when
 229          * it spawns off queries for every class, it returns here. */
 230         COLLECT_CLASS_STATE,
 231
 232         /** Find NS record to resolve DS record from, walking to the right
 233          * NS spot until we find it */
 234         DSNS_FIND_STATE,
 235
 236         /** Responses that are to be returned upstream end at this state.
 237          * As well as responses to target queries. */
 238         FINISHED_STATE
 239 };
 240
 241 /**
 242  * Shared counters for queries.
 243  */
 244 enum target_count_variables {
 245         /** Reference count for the shared iter_qstate->target_count. */
 246         TARGET_COUNT_REF = 0,
 247         /** Number of target queries spawned for the query and subqueries. */
 248         TARGET_COUNT_QUERIES,
 249         /** Number of nxdomain responses encountered. */
 250         TARGET_COUNT_NX,
 251
 252         /** This should stay last here, it is used for the allocation */
 253         TARGET_COUNT_MAX,
 254 };
 255
 256 /**
 257  * Per query state for the iterator module.
 258  */
 259 struct iter_qstate {
 260         /**
 261          * State of the iterator module.
 262          * This is the state that event is in or should sent to -- all
 263          * requests should start with the INIT_REQUEST_STATE. All
 264          * responses should start with QUERY_RESP_STATE. Subsequent
 265          * processing of the event will change this state.
 266          */
 267         enum iter_state state;
 268
 269         /**
 270          * Final state for the iterator module.
 271          * This is the state that responses should be routed to once the
 272          * response is final. For externally initiated queries, this
 273          * will be FINISHED_STATE, locally initiated queries will have
 274          * different final states.
 275          */
 276         enum iter_state final_state;
 277
 278         /**
 279          * The depth of this query, this means the depth of recursion.
 280          * This address is needed for another query, which is an address
 281          * needed for another query, etc. Original client query has depth 0.
 282          */
 283         int depth;
 284
 285         /**
 286          * The response
 287          */
 288         struct dns_msg* response;
 289
 290         /**
 291          * This is a list of RRsets that must be prepended to the
 292          * ANSWER section of a response before being sent upstream.
 293          */
 294         struct iter_prep_list* an_prepend_list;
 295         /** Last element of the prepend list */
 296         struct iter_prep_list* an_prepend_last;
 297
 298         /**
 299          * This is the list of RRsets that must be prepended to the
 300          * AUTHORITY section of the response before being sent upstream.
 301          */
 302         struct iter_prep_list* ns_prepend_list;
 303         /** Last element of the authority prepend list */
 304         struct iter_prep_list* ns_prepend_last;
 305
 306         /** query name used for chasing the results. Initially the same as
 307          * the state qinfo, but after CNAMEs this will be different.
 308          * The query info used to elicit the results needed. */
 309         struct query_info qchase;
 310         /** query flags to use when chasing the answer (i.e. RD flag) */
 311         uint16_t chase_flags;
 312         /** true if we set RD bit because of last resort recursion lame query*/
 313         int chase_to_rd;
 314
 315         /**
 316          * This is the current delegation point for an in-progress query. This
 317          * object retains state as to which delegation targets need to be
 318          * (sub)queried for vs which ones have already been visited.
 319          */
 320         struct delegpt* dp;
 321
 322         /** state for 0x20 fallback when capsfail happens, 0 not a fallback */
 323         int caps_fallback;
 324         /** state for capsfail: current server number to try */
 325         size_t caps_server;
 326         /** state for capsfail: stored query for comparisons. Can be NULL if
 327          * no response had been seen prior to starting the fallback. */
 328         struct reply_info* caps_reply;
 329         struct dns_msg* caps_response;
 330
 331         /** Current delegation message - returned for non-RD queries */
 332         struct dns_msg* deleg_msg;
 333
 334         /** number of outstanding target sub queries */
 335         int num_target_queries;
 336
 337         /** outstanding direct queries */
 338         int num_current_queries;
 339
 340         /** the number of times this query has been restarted. */
 341         int query_restart_count;
 342
 343         /** the number of times this query has followed a referral. */
 344         int referral_count;
 345
 346         /** number of queries fired off */
 347         int sent_count;
 348
 349         /** malloced-array shared with this query and its subqueries. It keeps
 350          * track of the defined enum target_count_variables counters. */
 351         int* target_count;
 352
 353         /** number of target lookups per delegation point. Reset to 0 after
 354          * receiving referral answer. Not shared with subqueries. */
 355         int dp_target_count;
 356
 357         /** Delegation point that triggered the NXNS fallback; shared with
 358          * this query and its subqueries, count-referenced by the reference
 359          * counter in target_count.
 360          * This also marks the fallback activation. */
 361         uint8_t** nxns_dp;
 362
 363         /** if true, already tested for ratelimiting and passed the test */
 364         int ratelimit_ok;
 365
 366         /**
 367          * The query must store NS records from referrals as parentside RRs
 368          * Enabled once it hits resolution problems, to throttle retries.
 369          * If enabled it is the pointer to the old delegation point with
 370          * the old retry counts for bad-nameserver-addresses.
 371          */
 372         struct delegpt* store_parent_NS;
 373
 374         /**
 375          * The query is for parent-side glue(A or AAAA) for a nameserver.
 376          * If the item is seen as glue in a referral, and pside_glue is NULL,
 377          * then it is stored in pside_glue for later.
 378          * If it was never seen, at the end, then a negative caching element
 379          * must be created.
 380          * The (data or negative) RR cache element then throttles retries.
 381          */
 382         int query_for_pside_glue;
 383         /** the parent-side-glue element (NULL if none, its first match) */
 384         struct ub_packed_rrset_key* pside_glue;
 385
 386         /** If nonNULL we are walking upwards from DS query to find NS */
 387         uint8_t* dsns_point;
 388         /** length of the dname in dsns_point */
 389         size_t dsns_point_len;
 390
 391         /**
 392          * expected dnssec information for this iteration step.
 393          * If dnssec rrsigs are expected and not given, the server is marked
 394          * lame (dnssec-lame).
 395          */
 396         int dnssec_expected;
 397
 398         /**
 399          * We are expecting dnssec information, but we also know the server
 400          * is DNSSEC lame.  The response need not be marked dnssec-lame again.
 401          */
 402         int dnssec_lame_query;
 403
 404         /**
 405          * This is flag that, if true, means that this event is
 406          * waiting for a stub priming query.
 407          */
 408         int wait_priming_stub;
 409
 410         /**
 411          * This is a flag that, if true, means that this query is
 412          * for (re)fetching glue from a zone. Since the address should
 413          * have been glue, query again to the servers that should have
 414          * been returning it as glue.
 415          * The delegation point must be set to the one that should *not*
 416          * be used when creating the state. A higher one will be attempted.
 417          */
 418         int refetch_glue;
 419
 420         /**
 421          * This flag detects that a completely empty nodata was received,
 422          * already so that it is accepted later. */
 423         int empty_nodata_found;
 424
 425         /** list of pending queries to authoritative servers. */
 426         struct outbound_list outlist;
 427
 428         /** QNAME minimisation state, RFC9156 */
 429         enum minimisation_state minimisation_state;
 430
 431         /** State for capsfail: QNAME minimisation state for comparisons. */
 432         enum minimisation_state caps_minimisation_state;
 433
 434         /**
 435          * The query info that is sent upstream. Will be a subset of qchase
 436          * when qname minimisation is enabled.
 437          */
 438         struct query_info qinfo_out;
 439
 440         /**
 441          * Count number of QNAME minimisation iterations. Used to limit number of
 442          * outgoing queries when QNAME minimisation is enabled.
 443          */
 444         int minimise_count;
 445
 446         /**
 447          * Count number of time-outs. Used to prevent resolving failures when
 448          * the QNAME minimisation QTYPE is blocked. Used to determine if
 449          * capsforid fallback should be started.*/
 450         int timeout_count;
 451
 452         /** True if the current response is from auth_zone */
 453         int auth_zone_response;
 454         /** True if the auth_zones should not be consulted for the query */
 455         int auth_zone_avoid;
 456         /** true if there have been scrubbing failures of reply packets */
 457         int scrub_failures;
 458         /** true if there have been parse failures of reply packets */
 459         int parse_failures;
 460         /** a failure printout address for last received answer */
 461         union {
 462                 struct in_addr in;
 463 #ifdef AF_INET6
 464                 struct in6_addr in6;
 465 #endif
 466         } fail_addr;
 467         /** which fail_addr, 0 is nothing, 4 or 6 */
 468         int fail_addr_type;
 469 };
 470
 471 /**
 472  * List of prepend items
 473  */
 474 struct iter_prep_list {
 475         /** next in list */
 476         struct iter_prep_list* next;
 477         /** rrset */
 478         struct ub_packed_rrset_key* rrset;
 479 };
 480
 481 /**
 482  * Get the iterator function block.
 483  * @return: function block with function pointers to iterator methods.
 484  */
 485 struct module_func_block* iter_get_funcblock(void);
 486
 487 /**
 488  * Get iterator state as a string
 489  * @param state: to convert
 490  * @return constant string that is printable.
 491  */
 492 const char* iter_state_to_string(enum iter_state state);
 493
 494 /**
 495  * See if iterator state is a response state
 496  * @param s: to inspect
 497  * @return true if response state.
 498  */
 499 int iter_state_is_responsestate(enum iter_state s);
 500
 501 /** iterator init */
 502 int iter_init(struct module_env* env, int id);
 503
 504 /** iterator deinit */
 505 void iter_deinit(struct module_env* env, int id);
 506
 507 /** iterator operate on a query */
 508 void iter_operate(struct module_qstate* qstate, enum module_ev event, int id,
 509         struct outbound_entry* outbound);
 510
 511 /**
 512  * Return priming query results to interested super querystates.
 513  *
 514  * Sets the delegation point and delegation message (not nonRD queries).
 515  * This is a callback from walk_supers.
 516  *
 517  * @param qstate: query state that finished.
 518  * @param id: module id.
 519  * @param super: the qstate to inform.
 520  */
 521 void iter_inform_super(struct module_qstate* qstate, int id,
 522         struct module_qstate* super);
 523
 524 /** iterator cleanup query state */
 525 void iter_clear(struct module_qstate* qstate, int id);
 526
 527 /** iterator alloc size routine */
 528 size_t iter_get_mem(struct module_env* env, int id);
 529
 530 #endif /* ITERATOR_ITERATOR_H */