1 /* $NetBSD: view.h,v 1.13 2025/05/21 14:48:04 christos Exp $ */ 2 3 /* 4 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5 * 6 * SPDX-License-Identifier: MPL-2.0 7 * 8 * This Source Code Form is subject to the terms of the Mozilla Public 9 * License, v. 2.0. If a copy of the MPL was not distributed with this 10 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 11 * 12 * See the COPYRIGHT file distributed with this work for additional 13 * information regarding copyright ownership. 14 */ 15 16 #pragma once 17 18 /***** 19 ***** Module Info 20 *****/ 21 22 /*! \file dns/view.h 23 * \brief 24 * DNS View 25 * 26 * A "view" is a DNS namespace, together with an optional resolver and a 27 * forwarding policy. A "DNS namespace" is a (possibly empty) set of 28 * authoritative zones together with an optional cache and optional 29 * "hints" information. 30 * 31 * Views start out "unfrozen". In this state, core attributes like 32 * the cache, set of zones, and forwarding policy may be set. While 33 * "unfrozen", the caller (e.g. nameserver configuration loading 34 * code), must ensure exclusive access to the view. When the view is 35 * "frozen", the core attributes become immutable, and the view module 36 * will ensure synchronization. Freezing allows the view's core attributes 37 * to be accessed without locking. 38 * 39 * MP: 40 *\li Before the view is frozen, the caller must ensure synchronization. 41 * 42 *\li After the view is frozen, the module guarantees appropriate 43 * synchronization of any data structures it creates and manipulates. 44 * 45 * Reliability: 46 *\li No anticipated impact. 47 * 48 * Resources: 49 *\li TBS 50 * 51 * Security: 52 *\li No anticipated impact. 53 * 54 * Standards: 55 *\li None. 56 */ 57 58 #include <inttypes.h> 59 #include <stdbool.h> 60 #include <stdio.h> 61 62 #include <isc/lang.h> 63 #include <isc/magic.h> 64 #include <isc/mutex.h> 65 #include <isc/net.h> 66 #include <isc/refcount.h> 67 #include <isc/rwlock.h> 68 #include <isc/stdtime.h> 69 70 #include <dns/acl.h> 71 #include <dns/catz.h> 72 #include <dns/clientinfo.h> 73 #include <dns/dnstap.h> 74 #include <dns/fixedname.h> 75 #include <dns/nta.h> 76 #include <dns/rdatastruct.h> 77 #include <dns/rpz.h> 78 #include <dns/rrl.h> 79 #include <dns/transport.h> 80 #include <dns/types.h> 81 #include <dns/zt.h> 82 83 ISC_LANG_BEGINDECLS 84 85 struct dns_view { 86 /* Unlocked. */ 87 unsigned int magic; 88 isc_mem_t *mctx; 89 dns_rdataclass_t rdclass; 90 char *name; 91 dns_zt_t *zonetable; 92 dns_resolver_t *resolver; 93 dns_adb_t *adb; 94 dns_requestmgr_t *requestmgr; 95 dns_dispatchmgr_t *dispatchmgr; 96 dns_cache_t *cache; 97 dns_db_t *cachedb; 98 dns_db_t *hints; 99 100 /* 101 * security roots and negative trust anchors. 102 * internal use only; access via * dns_view_getsecroots() 103 */ 104 dns_keytable_t *secroots_priv; 105 dns_ntatable_t *ntatable_priv; 106 107 isc_mutex_t lock; 108 bool frozen; 109 bool cacheshared; 110 111 /* Configurable data. */ 112 dns_transport_list_t *transports; 113 dns_tsigkeyring_t *statickeys; 114 dns_tsigkeyring_t *dynamickeys; 115 dns_peerlist_t *peers; 116 dns_order_t *order; 117 dns_fwdtable_t *fwdtable; 118 bool recursion; 119 bool qminimization; 120 bool qmin_strict; 121 bool auth_nxdomain; 122 bool minimal_any; 123 dns_minimaltype_t minimalresponses; 124 bool enablevalidation; 125 bool acceptexpired; 126 bool requireservercookie; 127 bool synthfromdnssec; 128 bool trust_anchor_telemetry; 129 bool root_key_sentinel; 130 dns_transfer_format_t transfer_format; 131 dns_acl_t *cacheacl; 132 dns_acl_t *cacheonacl; 133 dns_acl_t *queryacl; 134 dns_acl_t *queryonacl; 135 dns_acl_t *recursionacl; 136 dns_acl_t *recursiononacl; 137 dns_acl_t *sortlist; 138 dns_acl_t *notifyacl; 139 dns_acl_t *transferacl; 140 dns_acl_t *updateacl; 141 dns_acl_t *upfwdacl; 142 dns_acl_t *denyansweracl; 143 dns_acl_t *nocasecompress; 144 dns_acl_t *proxyacl; 145 dns_acl_t *proxyonacl; 146 bool msgcompression; 147 dns_nametree_t *answeracl_exclude; 148 dns_nametree_t *denyanswernames; 149 dns_nametree_t *answernames_exclude; 150 dns_nametree_t *sfd; 151 dns_rrl_t *rrl; 152 bool provideixfr; 153 bool requestnsid; 154 bool sendcookie; 155 dns_ttl_t maxcachettl; 156 dns_ttl_t maxncachettl; 157 dns_ttl_t mincachettl; 158 dns_ttl_t minncachettl; 159 uint32_t nta_lifetime; 160 uint32_t nta_recheck; 161 char *nta_file; 162 dns_ttl_t prefetch_trigger; 163 dns_ttl_t prefetch_eligible; 164 in_port_t dstport; 165 dns_aclenv_t *aclenv; 166 dns_rdatatype_t preferred_glue; 167 bool flush; 168 bool checknames; 169 uint16_t maxudp; 170 dns_ttl_t staleanswerttl; 171 dns_stale_answer_t staleanswersok; /* rndc setting */ 172 bool staleanswersenable; /* named.conf setting */ 173 uint32_t staleanswerclienttimeout; 174 uint16_t nocookieudp; 175 uint16_t padding; 176 dns_acl_t *pad_acl; 177 unsigned int maxbits; 178 dns_dns64list_t dns64; 179 unsigned int dns64cnt; 180 bool usedns64; 181 dns_rpz_zones_t *rpzs; 182 dns_catz_zones_t *catzs; 183 dns_dlzdblist_t dlz_searched; 184 dns_dlzdblist_t dlz_unsearched; 185 uint32_t fail_ttl; 186 dns_badcache_t *failcache; 187 unsigned int udpsize; 188 uint32_t sig0key_checks_limit; 189 uint32_t sig0message_checks_limit; 190 uint32_t maxrrperset; 191 uint32_t maxtypepername; 192 uint16_t max_queries; 193 uint8_t max_restarts; 194 195 /* 196 * Configurable data for server use only, 197 * locked by server configuration lock. 198 */ 199 dns_acl_t *matchclients; 200 dns_acl_t *matchdestinations; 201 bool matchrecursiveonly; 202 203 /* Locked by themselves. */ 204 isc_refcount_t references; 205 isc_refcount_t weakrefs; 206 207 /* Under owner's locking control. */ 208 ISC_LINK(struct dns_view) link; 209 dns_viewlist_t *viewlist; 210 211 dns_zone_t *managed_keys; 212 dns_zone_t *redirect; 213 dns_name_t *redirectzone; /* points to 214 * redirectfixed 215 * when valid */ 216 dns_fixedname_t redirectfixed; 217 218 /* 219 * File and configuration data for zones added at runtime 220 * (only used in BIND9). 221 * 222 * XXX: This should be a pointer to an opaque type that 223 * named implements. 224 */ 225 char *new_zone_dir; 226 char *new_zone_file; 227 char *new_zone_db; 228 void *new_zone_dbenv; 229 uint64_t new_zone_mapsize; 230 void *new_zone_config; 231 void (*cfg_destroy)(void **); 232 isc_mutex_t new_zone_lock; 233 234 unsigned char secret[32]; /* Client secret */ 235 unsigned int v6bias; 236 237 dns_dtenv_t *dtenv; /* Dnstap environment */ 238 dns_dtmsgtype_t dttypes; /* Dnstap message types 239 * to log */ 240 241 /* Registered module instances */ 242 void *plugins; 243 void (*plugins_free)(isc_mem_t *, void **); 244 245 /* Hook table */ 246 void *hooktable; /* ns_hooktable */ 247 void (*hooktable_free)(isc_mem_t *, void **); 248 }; 249 250 #define DNS_VIEW_MAGIC ISC_MAGIC('V', 'i', 'e', 'w') 251 #define DNS_VIEW_VALID(view) ISC_MAGIC_VALID(view, DNS_VIEW_MAGIC) 252 253 #define DNS_VIEWATTR_RESSHUTDOWN 0x01 254 #define DNS_VIEWATTR_ADBSHUTDOWN 0x02 255 #define DNS_VIEWATTR_REQSHUTDOWN 0x04 256 257 #ifdef HAVE_LMDB 258 #define DNS_LMDB_COMMON_FLAGS (MDB_CREATE | MDB_NOSUBDIR | MDB_NOLOCK) 259 #ifndef __OpenBSD__ 260 #define DNS_LMDB_FLAGS (DNS_LMDB_COMMON_FLAGS) 261 #else /* __OpenBSD__ */ 262 /* 263 * OpenBSD does not have a unified buffer cache, which requires both reads and 264 * writes to be performed using mmap(). 265 */ 266 #define DNS_LMDB_FLAGS (DNS_LMDB_COMMON_FLAGS | MDB_WRITEMAP) 267 #endif /* __OpenBSD__ */ 268 #endif /* HAVE_LMDB */ 269 270 isc_result_t 271 dns_view_create(isc_mem_t *mctx, isc_loopmgr_t *loopmgr, 272 dns_dispatchmgr_t *dispmgr, dns_rdataclass_t rdclass, 273 const char *name, dns_view_t **viewp); 274 /*%< 275 * Create a view. 276 * 277 * Notes: 278 * 279 *\li The newly created view has no cache, no resolver, and an empty 280 * zone table. The view is not frozen. 281 * 282 * Requires: 283 * 284 *\li 'mctx' is a valid memory context. 285 * 286 *\li 'rdclass' is a valid class. 287 * 288 *\li 'name' is a valid C string. 289 * 290 *\li viewp != NULL && *viewp == NULL 291 * 292 * Returns: 293 * 294 *\li #ISC_R_SUCCESS 295 *\li #ISC_R_NOMEMORY 296 * 297 *\li Other errors are possible. 298 */ 299 300 void 301 dns_view_attach(dns_view_t *source, dns_view_t **targetp); 302 /*%< 303 * Attach '*targetp' to 'source', incrementing the view's reference 304 * counter. 305 * 306 * Requires: 307 * 308 *\li 'source' is a valid, frozen view. 309 * 310 *\li 'targetp' points to a NULL dns_view_t *. 311 * 312 * Ensures: 313 * 314 *\li *targetp is attached to source. 315 * 316 *\li While *targetp is attached, the view will not shut down. 317 */ 318 319 void 320 dns_view_detach(dns_view_t **viewp); 321 /*%< 322 * Detach '*viewp' and decrement the view's reference counter. If this was 323 * the last reference, then the associated resolver, requestmgr, ADB and 324 * zones will be shut down; if dns_view_flushonshutdown() has been called 325 * with 'true', uncommitted changed in zones will also be flushed to disk. 326 * The view will not be fully destroyed, however, until the weak references 327 * (see below) reach zero as well. 328 * 329 * Requires: 330 * 331 *\li 'viewp' points to a valid dns_view_t * 332 * 333 * Ensures: 334 * 335 *\li *viewp is NULL. 336 */ 337 338 void 339 dns_view_weakattach(dns_view_t *source, dns_view_t **targetp); 340 /*%< 341 * Attach '*targetp' to 'source', incrementing the view's weak reference 342 * counter. 343 * 344 * Weak references are used by objects such as the resolver, requestmgr, 345 * ADB, and zones, which are subsidiary to the view; they need the view 346 * object to remain in existence as long as they persist, but they do 347 * not need to prevent it from being shut down. 348 * 349 * Requires: 350 * 351 *\li 'source' is a valid, frozen view. 352 * 353 *\li 'targetp' points to a NULL dns_view_t *. 354 * 355 * Ensures: 356 * 357 *\li *targetp is attached to source. 358 * 359 * \li While *targetp is attached, the view will not be freed. 360 */ 361 362 void 363 dns_view_weakdetach(dns_view_t **targetp); 364 /*%< 365 * Detach '*viewp' from its view. If this is the last weak reference, 366 * the view will be destroyed. 367 * 368 * Requires: 369 * 370 *\li 'viewp' points to a valid dns_view_t *. 371 * 372 * Ensures: 373 * 374 *\li *viewp is NULL. 375 */ 376 377 isc_result_t 378 dns_view_createresolver(dns_view_t *view, isc_nm_t *netmgr, 379 unsigned int options, isc_tlsctx_cache_t *tlsctx_cache, 380 dns_dispatch_t *dispatchv4, dns_dispatch_t *dispatchv6); 381 /*%< 382 * Create a resolver and address database for the view. 383 * 384 * Requires: 385 * 386 *\li 'view' is a valid, unfrozen view. 387 * 388 *\li 'view' does not have a resolver already. 389 * 390 *\li The requirements of dns_resolver_create() apply to 'ndisp', 391 * 'netmgr', 'options', 'tlsctx_cache', 'dispatchv4', and 'dispatchv6'. 392 * 393 * Returns: 394 * 395 *\li #ISC_R_SUCCESS 396 * 397 *\li Any error that dns_resolver_create() can return. 398 */ 399 400 void 401 dns_view_setcache(dns_view_t *view, dns_cache_t *cache, bool shared); 402 /*%< 403 * Set the view's cache database. If 'shared' is true, this means the cache 404 * is created by another view and is shared with that view. dns_view_setcache() 405 * is a backward compatible version equivalent to setcache2(..., false). 406 * 407 * Requires: 408 * 409 *\li 'view' is a valid, unfrozen view. 410 * 411 *\li 'cache' is a valid cache. 412 * 413 * Ensures: 414 * 415 * \li The cache of 'view' is 'cached. 416 * 417 *\li If this is not the first call to dns_view_setcache() for this 418 * view, then previously set cache is detached. 419 */ 420 421 void 422 dns_view_sethints(dns_view_t *view, dns_db_t *hints); 423 /*%< 424 * Set the view's hints database. 425 * 426 * Requires: 427 * 428 *\li 'view' is a valid, unfrozen view, whose hints database has not been 429 * set. 430 * 431 *\li 'hints' is a valid zone database. 432 * 433 * Ensures: 434 * 435 * \li The hints database of 'view' is 'hints'. 436 */ 437 438 void 439 dns_view_settransports(dns_view_t *view, dns_transport_list_t *list); 440 441 void 442 dns_view_setkeyring(dns_view_t *view, dns_tsigkeyring_t *ring); 443 void 444 dns_view_setdynamickeyring(dns_view_t *view, dns_tsigkeyring_t *ring); 445 /*%< 446 * Set the view's static TSIG keys 447 * 448 * Requires: 449 * 450 * \li 'view' is a valid, unfrozen view, whose static TSIG keyring has not 451 * been set. 452 * 453 *\li 'ring' is a valid TSIG keyring 454 * 455 * Ensures: 456 * 457 *\li The static TSIG keyring of 'view' is 'ring'. 458 */ 459 460 void 461 dns_view_getdynamickeyring(dns_view_t *view, dns_tsigkeyring_t **ringp); 462 /*%< 463 * Return the views dynamic keys. 464 * 465 * \li 'view' is a valid, unfrozen view. 466 * \li 'ringp' != NULL && ringp == NULL. 467 */ 468 469 void 470 dns_view_setdstport(dns_view_t *view, in_port_t dstport); 471 /*%< 472 * Set the view's destination port. This is the port to 473 * which outgoing queries are sent. The default is 53, 474 * the standard DNS port. 475 * 476 * Requires: 477 * 478 *\li 'view' is a valid view. 479 * 480 *\li 'dstport' is a valid TCP/UDP port number. 481 * 482 * Ensures: 483 *\li External name servers will be assumed to be listening 484 * on 'dstport'. For servers whose address has already 485 * obtained obtained at the time of the call, the view may 486 * continue to use the previously set port until the address 487 * times out from the view's address database. 488 */ 489 490 isc_result_t 491 dns_view_addzone(dns_view_t *view, dns_zone_t *zone); 492 /*%< 493 * Add zone 'zone' to 'view'. 494 * 495 * Requires: 496 * 497 *\li 'view' is a valid, unfrozen view. 498 * 499 *\li 'zone' is a valid zone. 500 */ 501 502 isc_result_t 503 dns_view_delzone(dns_view_t *view, dns_zone_t *zone); 504 /*%< 505 * Removes zone 'zone' from 'view'. 506 * 507 * Requires: 508 * 509 *\li 'zone' is a valid zone. 510 */ 511 512 void 513 dns_view_freeze(dns_view_t *view); 514 /*%< 515 * Freeze view. No changes can be made to view configuration while frozen. 516 * 517 * Requires: 518 * 519 *\li 'view' is a valid, unfrozen view. 520 * 521 * Ensures: 522 * 523 *\li 'view' is frozen. 524 */ 525 526 void 527 dns_view_thaw(dns_view_t *view); 528 /*%< 529 * Thaw view. This allows zones to be added or removed at runtime. This is 530 * NOT thread-safe; the caller MUST have paused the loopmgr prior to thawing 531 * the view. 532 * 533 * Requires: 534 * 535 *\li 'view' is a valid, frozen view. 536 * 537 * Ensures: 538 * 539 *\li 'view' is no longer frozen. 540 */ 541 542 isc_result_t 543 dns_view_find(dns_view_t *view, const dns_name_t *name, dns_rdatatype_t type, 544 isc_stdtime_t now, unsigned int options, bool use_hints, 545 bool use_static_stub, dns_db_t **dbp, dns_dbnode_t **nodep, 546 dns_name_t *foundname, dns_rdataset_t *rdataset, 547 dns_rdataset_t *sigrdataset); 548 /*%< 549 * Find an rdataset whose owner name is 'name', and whose type is 550 * 'type'. 551 * In general, this function first searches view's zone and cache DBs for the 552 * best match data against 'name'. If nothing found there, and if 'use_hints' 553 * is true, the view's hint DB (if configured) is searched. 554 * If the view is configured with a static-stub zone which gives the longest 555 * match for 'name' among the zones, however, the cache DB is not consulted 556 * unless 'use_static_stub' is false (see below about this argument). 557 * 558 * Notes: 559 * 560 *\li See the description of dns_db_find() for information about 'options'. 561 562 *\li If the caller sets #DNS_DBFIND_GLUEOK, it must ensure that 'name' 563 * and 'type' are appropriate for glue retrieval. Glue found in a 564 * zone database will be returned without checking the cache for a 565 * better answer. 566 * 567 *\li If 'now' is zero, then the current time will be used. 568 * 569 *\li If 'use_hints' is true, and the view has a hints database, then 570 * it will be searched last. If the answer is found in the hints 571 * database, the result code will be DNS_R_HINT. If the name is found 572 * in the hints database but not the type, the result code will be 573 * #DNS_R_HINTNXRRSET. 574 * 575 *\li If 'use_static_stub' is false and the longest match zone for 'name' 576 * is a static-stub zone, it's ignored and the cache and/or hints will be 577 * searched. In the majority of the cases this argument should be 578 * false. The only known usage of this argument being true is 579 * if this search is for a "bailiwick" glue A or AAAA RRset that may 580 * best match a static-stub zone. Consider the following example: 581 * this view is configured with a static-stub zone "example.com", 582 * and an attempt of recursive resolution needs to send a query for the 583 * zone. In this case it's quite likely that the resolver is trying to 584 * find A/AAAA RRs for the apex name "example.com". And, to honor the 585 * static-stub configuration it needs to return the glue RRs in the 586 * static-stub zone even if that exact RRs coming from the authoritative 587 * zone has been cached. 588 * In other general cases, the requested data is better to be 589 * authoritative, either locally configured or retrieved from an external 590 * server, and the data in the static-stub zone should better be ignored. 591 * 592 *\li 'foundname' must meet the requirements of dns_db_find(). 593 * 594 *\li If 'sigrdataset' is not NULL, and there is a SIG rdataset which 595 * covers 'type', then 'sigrdataset' will be bound to it. 596 * 597 * Requires: 598 * 599 *\li 'view' is a valid, frozen view. 600 * 601 *\li 'name' is valid name. 602 * 603 *\li 'type' is a valid dns_rdatatype_t, and is not a meta query type 604 * except dns_rdatatype_any. 605 * 606 *\li dbp == NULL || *dbp == NULL 607 * 608 *\li nodep == NULL || *nodep == NULL. If nodep != NULL, dbp != NULL. 609 * 610 *\li 'foundname' is a valid name with a dedicated buffer or NULL. 611 * 612 *\li 'rdataset' is a valid, disassociated rdataset. 613 * 614 *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset. 615 * 616 * Ensures: 617 * 618 *\li In successful cases, 'rdataset', and possibly 'sigrdataset', are 619 * bound to the found data. 620 * 621 *\li If dbp != NULL, it points to the database containing the data. 622 * 623 *\li If nodep != NULL, it points to the database node containing the data. 624 * 625 *\li If foundname != NULL, it contains the full name of the found data. 626 * 627 * Returns: 628 * 629 *\li Any result that dns_db_find() can return, with the exception of 630 * #DNS_R_DELEGATION. 631 */ 632 633 isc_result_t 634 dns_view_simplefind(dns_view_t *view, const dns_name_t *name, 635 dns_rdatatype_t type, isc_stdtime_t now, 636 unsigned int options, bool use_hints, 637 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset); 638 /*%< 639 * Find an rdataset whose owner name is 'name', and whose type is 640 * 'type'. 641 * 642 * Notes: 643 * 644 *\li This routine is appropriate for simple, exact-match queries of the 645 * view. 'name' must be a canonical name; there is no DNAME or CNAME 646 * processing. 647 * 648 *\li See the description of dns_db_find() for information about 'options'. 649 * If the caller sets DNS_DBFIND_GLUEOK, it must ensure that 'name' 650 * and 'type' are appropriate for glue retrieval. 651 * 652 *\li If 'now' is zero, then the current time will be used. 653 * 654 *\li If 'use_hints' is true, and the view has a hints database, then 655 * it will be searched last. If the answer is found in the hints 656 * database, the result code will be DNS_R_HINT. If the name is found 657 * in the hints database but not the type, the result code will be 658 * DNS_R_HINTNXRRSET. 659 * 660 *\li If 'sigrdataset' is not NULL, and there is a SIG rdataset which 661 * covers 'type', then 'sigrdataset' will be bound to it. 662 * 663 * Requires: 664 * 665 *\li 'view' is a valid, frozen view. 666 * 667 *\li 'name' is valid name. 668 * 669 *\li 'type' is a valid dns_rdatatype_t, and is not a meta query type 670 * (e.g. dns_rdatatype_any), or dns_rdatatype_rrsig. 671 * 672 *\li 'rdataset' is a valid, disassociated rdataset. 673 * 674 *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset. 675 * 676 * Ensures: 677 * 678 *\li In successful cases, 'rdataset', and possibly 'sigrdataset', are 679 * bound to the found data. 680 * 681 * Returns: 682 * 683 *\li #ISC_R_SUCCESS Success; result is desired type. 684 *\li DNS_R_GLUE Success; result is glue. 685 *\li DNS_R_HINT Success; result is a hint. 686 *\li DNS_R_NCACHENXDOMAIN Success; result is a ncache entry. 687 *\li DNS_R_NCACHENXRRSET Success; result is a ncache entry. 688 *\li DNS_R_NXDOMAIN The name does not exist. 689 *\li DNS_R_NXRRSET The rrset does not exist. 690 *\li #ISC_R_NOTFOUND No matching data found, 691 * or an error occurred. 692 */ 693 694 isc_result_t 695 dns_view_findzonecut(dns_view_t *view, const dns_name_t *name, 696 dns_name_t *fname, dns_name_t *dcname, isc_stdtime_t now, 697 unsigned int options, bool use_hints, bool use_cache, 698 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset); 699 /*%< 700 * Find the best known zonecut containing 'name'. 701 * 702 * This uses local authority, cache, and optionally hints data. 703 * No external queries are performed. 704 * 705 * Notes: 706 * 707 *\li If 'now' is zero, then the current time will be used. 708 * 709 *\li If 'use_hints' is true, and the view has a hints database, then 710 * it will be searched last. 711 * 712 *\li If 'use_cache' is true, and the view has a cache, then it will be 713 * searched. 714 * 715 *\li If 'sigrdataset' is not NULL, and there is a SIG rdataset which 716 * covers 'type', then 'sigrdataset' will be bound to it. 717 * 718 *\li If the DNS_DBFIND_NOEXACT option is set, then the zonecut returned 719 * (if any) will be the deepest known ancestor of 'name'. 720 * 721 *\li If dcname is not NULL the deepest cached name is copied to it. 722 * 723 * Requires: 724 * 725 *\li 'view' is a valid, frozen view. 726 * 727 *\li 'name' is valid name. 728 * 729 *\li 'rdataset' is a valid, disassociated rdataset. 730 * 731 *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset. 732 * 733 * Returns: 734 * 735 *\li #ISC_R_SUCCESS Success. 736 * 737 *\li Many other results are possible. 738 */ 739 740 isc_result_t 741 dns_viewlist_find(dns_viewlist_t *list, const char *name, 742 dns_rdataclass_t rdclass, dns_view_t **viewp); 743 /*%< 744 * Search for a view with name 'name' and class 'rdclass' in 'list'. 745 * If found, '*viewp' is (strongly) attached to it. 746 * 747 * Requires: 748 * 749 *\li 'viewp' points to a NULL dns_view_t *. 750 * 751 * Returns: 752 * 753 *\li #ISC_R_SUCCESS A matching view was found. 754 *\li #ISC_R_NOTFOUND No matching view was found. 755 */ 756 757 isc_result_t 758 dns_viewlist_findzone(dns_viewlist_t *list, const dns_name_t *name, 759 bool allclasses, dns_rdataclass_t rdclass, 760 dns_zone_t **zonep); 761 762 /*%< 763 * Search zone with 'name' in view with 'rdclass' in viewlist 'list' 764 * If found, zone is returned in *zonep. If allclasses is set rdclass is ignored 765 * 766 * Returns: 767 *\li #ISC_R_SUCCESS A matching zone was found. 768 *\li #ISC_R_NOTFOUND No matching zone was found. 769 *\li #ISC_R_MULTIPLE Multiple zones with the same name were found. 770 */ 771 772 isc_result_t 773 dns_view_findzone(dns_view_t *view, const dns_name_t *name, 774 unsigned int options, dns_zone_t **zonep); 775 /*%< 776 * Search for the zone 'name' in the zone table of 'view'. 777 * If found, 'zonep' is (strongly) attached to it. 778 * 779 * Requires: 780 * 781 *\li 'zonep' points to a NULL dns_zone_t *. 782 * 783 * Returns: 784 *\li #ISC_R_SUCCESS A matching zone was found. 785 *\li #ISC_R_NOTFOUND No matching zone was found. 786 */ 787 788 isc_result_t 789 dns_view_load(dns_view_t *view, bool stop, bool newonly); 790 791 isc_result_t 792 dns_view_asyncload(dns_view_t *view, bool newonly, dns_zt_callback_t *callback, 793 void *arg); 794 /*%< 795 * Load zones attached to this view. dns_view_load() loads 796 * all zones whose master file has changed since the last 797 * load 798 * 799 * dns_view_asyncload() loads zones asynchronously. When all zones 800 * in the view have finished loading, 'callback' is called with argument 801 * 'arg' to inform the caller. 802 * 803 * If 'stop' is true, stop on the first error and return it. 804 * If 'stop' is false (or we are loading asynchronously), ignore errors. 805 * 806 * If 'newonly' is true load only zones that were never loaded. 807 * 808 * Requires: 809 * 810 *\li 'view' is valid. 811 */ 812 813 isc_result_t 814 dns_view_gettransport(dns_view_t *view, const dns_transport_type_t type, 815 const dns_name_t *name, dns_transport_t **transportp); 816 817 isc_result_t 818 dns_view_gettsig(dns_view_t *view, const dns_name_t *keyname, 819 dns_tsigkey_t **keyp); 820 /*%< 821 * Find the TSIG key configured in 'view' with name 'keyname', 822 * if any. 823 * 824 * Requires: 825 *\li keyp points to a NULL dns_tsigkey_t *. 826 * 827 * Returns: 828 *\li #ISC_R_SUCCESS A key was found and '*keyp' now points to it. 829 *\li #ISC_R_NOTFOUND No key was found. 830 *\li others An error occurred. 831 */ 832 833 isc_result_t 834 dns_view_getpeertsig(dns_view_t *view, const isc_netaddr_t *peeraddr, 835 dns_tsigkey_t **keyp); 836 /*%< 837 * Find the TSIG key configured in 'view' for the server whose 838 * address is 'peeraddr', if any. 839 * 840 * Requires: 841 * keyp points to a NULL dns_tsigkey_t *. 842 * 843 * Returns: 844 *\li #ISC_R_SUCCESS A key was found and '*keyp' now points to it. 845 *\li #ISC_R_NOTFOUND No key was found. 846 *\li others An error occurred. 847 */ 848 849 isc_result_t 850 dns_view_checksig(dns_view_t *view, isc_buffer_t *source, dns_message_t *msg); 851 /*%< 852 * Verifies the signature of a message. 853 * 854 * Requires: 855 * 856 *\li 'view' is a valid view. 857 *\li 'source' is a valid buffer containing the message 858 *\li 'msg' is a valid message 859 * 860 * Returns: 861 *\li see dns_tsig_verify() 862 */ 863 864 void 865 dns_view_dialup(dns_view_t *view); 866 /*%< 867 * Perform dialup-time maintenance on the zones of 'view'. 868 */ 869 870 isc_result_t 871 dns_view_flushcache(dns_view_t *view, bool fixuponly); 872 /*%< 873 * Flush the view's cache (and ADB). If 'fixuponly' is true, it only updates 874 * the internal reference to the cache DB with omitting actual flush operation. 875 * 'fixuponly' is intended to be used for a view that shares a cache with 876 * a different view. dns_view_flushcache() is a backward compatible version 877 * that always sets fixuponly to false. 878 * 879 * Requires: 880 * 'view' is valid. 881 * 882 * No other tasks are executing. 883 * 884 * Returns: 885 *\li #ISC_R_SUCCESS 886 *\li #ISC_R_NOMEMORY 887 */ 888 889 isc_result_t 890 dns_view_flushnode(dns_view_t *view, const dns_name_t *name, bool tree); 891 /*%< 892 * Flush the given name from the view's cache (and optionally ADB/badcache). 893 * 894 * Flush the given name from the cache, ADB, and bad cache. If 'tree' 895 * is true, also flush all subdomains of 'name'. 896 * 897 * Requires: 898 *\li 'view' is valid. 899 *\li 'name' is valid. 900 * 901 * Returns: 902 *\li #ISC_R_SUCCESS 903 * other returns are failures. 904 */ 905 906 isc_result_t 907 dns_view_flushname(dns_view_t *view, const dns_name_t *name); 908 /*%< 909 * Flush the given name from the view's cache, ADB and badcache. 910 * Equivalent to dns_view_flushnode(view, name, false). 911 * 912 * 913 * Requires: 914 *\li 'view' is valid. 915 *\li 'name' is valid. 916 * 917 * Returns: 918 *\li #ISC_R_SUCCESS 919 * other returns are failures. 920 */ 921 922 isc_result_t 923 dns_view_freezezones(dns_view_t *view, bool freeze); 924 /*%< 925 * Freeze/thaw updates to primary zones. 926 * 927 * Requires: 928 * \li 'view' is valid. 929 */ 930 931 bool 932 dns_view_iscacheshared(dns_view_t *view); 933 /*%< 934 * Check if the view shares the cache created by another view. 935 * 936 * Requires: 937 * \li 'view' is valid. 938 * 939 * Returns: 940 *\li #true if the cache is shared. 941 *\li #false otherwise. 942 */ 943 944 void 945 dns_view_initntatable(dns_view_t *view, isc_loopmgr_t *loopmgr); 946 /*%< 947 * Initialize the negative trust anchor table for the view. 948 * 949 * Requires: 950 * \li 'view' is valid. 951 * \li 'loopmgr' is a valid loopmgr. 952 */ 953 954 isc_result_t 955 dns_view_getntatable(dns_view_t *view, dns_ntatable_t **ntp); 956 /*%< 957 * Get the negative trust anchor table for this view. Returns 958 * ISC_R_NOTFOUND if the table not been initialized for the view. 959 * 960 * '*ntp' is attached on success; the caller is responsible for 961 * detaching it with dns_ntatable_detach(). 962 * 963 * Requires: 964 * \li 'view' is valid. 965 * \li 'nta' is not NULL and '*nta' is NULL. 966 * 967 * Returns: 968 *\li ISC_R_SUCCESS 969 *\li ISC_R_NOTFOUND 970 */ 971 972 void 973 dns_view_initsecroots(dns_view_t *view); 974 /*%< 975 * Initialize security roots for the view, detaching any previously 976 * existing security roots first. (Note that secroots_priv is 977 * NULL until this function is called, so any function using 978 * security roots must check that they have been initialized first. 979 * One way to do this is use dns_view_getsecroots() and check its 980 * return value.) 981 * 982 * Requires: 983 * \li 'view' is valid. 984 * 985 * Returns: 986 *\li ISC_R_SUCCESS 987 *\li Any other result indicates failure 988 */ 989 990 isc_result_t 991 dns_view_getsecroots(dns_view_t *view, dns_keytable_t **ktp); 992 /*%< 993 * Get the security roots for this view. Returns ISC_R_NOTFOUND if 994 * the security roots keytable has not been initialized for the view. 995 * 996 * '*ktp' is attached on success; the caller is responsible for 997 * detaching it with dns_keytable_detach(). 998 * 999 * Requires: 1000 * \li 'view' is valid. 1001 * \li 'ktp' is not NULL and '*ktp' is NULL. 1002 * 1003 * Returns: 1004 *\li ISC_R_SUCCESS 1005 *\li ISC_R_NOTFOUND 1006 */ 1007 1008 isc_result_t 1009 dns_view_issecuredomain(dns_view_t *view, const dns_name_t *name, 1010 isc_stdtime_t now, bool checknta, bool *ntap, 1011 bool *secure_domain); 1012 /*%< 1013 * Is 'name' at or beneath a trusted key, and not covered by a valid 1014 * negative trust anchor? Put answer in '*secure_domain'. 1015 * 1016 * If 'checknta' is false, ignore the NTA table in determining 1017 * whether this is a secure domain. If 'checknta' is not false, and if 1018 * 'ntap' is non-NULL, then '*ntap' will be updated with true if the 1019 * name is covered by an NTA. 1020 * 1021 * Requires: 1022 * \li 'view' is valid. 1023 * 1024 * Returns: 1025 *\li ISC_R_SUCCESS 1026 *\li Any other value indicates failure 1027 */ 1028 1029 bool 1030 dns_view_ntacovers(dns_view_t *view, isc_stdtime_t now, const dns_name_t *name, 1031 const dns_name_t *anchor); 1032 /*%< 1033 * Is there a current negative trust anchor above 'name' and below 'anchor'? 1034 * 1035 * Requires: 1036 * \li 'view' is valid. 1037 * 1038 * Returns: 1039 *\li ISC_R_TRUE 1040 *\li ISC_R_FALSE 1041 */ 1042 1043 void 1044 dns_view_untrust(dns_view_t *view, const dns_name_t *keyname, 1045 const dns_rdata_dnskey_t *dnskey); 1046 /*%< 1047 * Remove keys that match 'keyname' and 'dnskey' from the views trust 1048 * anchors. 1049 * 1050 * (NOTE: If the configuration specifies that there should be a 1051 * trust anchor at 'keyname', but no keys are left after this 1052 * operation, that is an error. We fail closed, inserting a NULL 1053 * key so as to prevent validation until a legimitate key has been 1054 * provided.) 1055 * 1056 * Requires: 1057 * \li 'view' is valid. 1058 * \li 'keyname' is valid. 1059 * \li 'dnskey' is valid. 1060 */ 1061 1062 bool 1063 dns_view_istrusted(dns_view_t *view, const dns_name_t *keyname, 1064 const dns_rdata_dnskey_t *dnskey); 1065 /*%< 1066 * Determine if the key defined by 'keyname' and 'dnskey' is 1067 * trusted by 'view'. 1068 * 1069 * Requires: 1070 * \li 'view' is valid. 1071 * \li 'keyname' is valid. 1072 * \li 'dnskey' is valid. 1073 */ 1074 1075 isc_result_t 1076 dns_view_setnewzones(dns_view_t *view, bool allow, void *cfgctx, 1077 void (*cfg_destroy)(void **), uint64_t mapsize); 1078 /*%< 1079 * Set whether or not to allow zones to be created or deleted at runtime. 1080 * 1081 * If 'allow' is true, determines the filename into which new zone 1082 * configuration will be written. Preserves the configuration context 1083 * (a pointer to which is passed in 'cfgctx') for use when parsing new 1084 * zone configuration. 'cfg_destroy' points to a callback routine to 1085 * destroy the configuration context when the view is destroyed. (This 1086 * roundabout method is used in order to avoid libdns having a dependency 1087 * on libisccfg and libbind9.) 1088 * 1089 * If 'allow' is false, removes any existing references to 1090 * configuration context and frees any memory. 1091 * 1092 * Requires: 1093 * \li 'view' is valid. 1094 * 1095 * Returns: 1096 * \li ISC_R_SUCCESS 1097 * \li ISC_R_NOSPACE 1098 */ 1099 1100 void 1101 dns_view_setnewzonedir(dns_view_t *view, const char *dir); 1102 const char * 1103 dns_view_getnewzonedir(dns_view_t *view); 1104 /*%< 1105 * Set/get the path to the directory in which NZF or NZD files should 1106 * be stored. If the path was previously set to a non-NULL value, 1107 * the previous value is freed. 1108 * 1109 * Requires: 1110 * \li 'view' is valid. 1111 */ 1112 1113 void 1114 dns_view_restorekeyring(dns_view_t *view); 1115 1116 isc_result_t 1117 dns_view_searchdlz(dns_view_t *view, const dns_name_t *name, 1118 unsigned int minlabels, dns_clientinfomethods_t *methods, 1119 dns_clientinfo_t *clientinfo, dns_db_t **dbp); 1120 1121 /*%< 1122 * Search through the DLZ database(s) in view->dlz_searched to find 1123 * one that can answer a query for 'name', using the DLZ driver's 1124 * findzone method. If successful, '*dbp' is set to point to the 1125 * DLZ database. 1126 * 1127 * Returns: 1128 * \li ISC_R_SUCCESS 1129 * \li ISC_R_NOTFOUND 1130 * 1131 * Requires: 1132 * \li 'view' is valid. 1133 * \li 'name' is not NULL. 1134 * \li 'dbp' is not NULL and *dbp is NULL. 1135 */ 1136 1137 uint32_t 1138 dns_view_getfailttl(dns_view_t *view); 1139 /*%< 1140 * Get the view's servfail-ttl. zero => no servfail caching. 1141 * 1142 * Requires: 1143 *\li 'view' to be valid. 1144 */ 1145 1146 void 1147 dns_view_setfailttl(dns_view_t *view, uint32_t failttl); 1148 /*%< 1149 * Set the view's servfail-ttl. zero => no servfail caching. 1150 * 1151 * Requires: 1152 *\li 'view' to be valid. 1153 */ 1154 1155 isc_result_t 1156 dns_view_saventa(dns_view_t *view); 1157 /*%< 1158 * Save NTA for names in this view to a file. 1159 * 1160 * Requires: 1161 *\li 'view' to be valid. 1162 */ 1163 1164 isc_result_t 1165 dns_view_loadnta(dns_view_t *view); 1166 /*%< 1167 * Loads NTA for names in this view from a file. 1168 * 1169 * Requires: 1170 *\li 'view' to be valid. 1171 */ 1172 1173 void 1174 dns_view_setviewcommit(dns_view_t *view); 1175 /*%< 1176 * Commit dns_zone_setview() calls previously made for all zones in this 1177 * view. 1178 * 1179 * Requires: 1180 *\li 'view' to be valid. 1181 */ 1182 1183 void 1184 dns_view_setviewrevert(dns_view_t *view); 1185 /*%< 1186 * Revert dns_zone_setview() calls previously made for all zones in this 1187 * view. 1188 * 1189 * Requires: 1190 *\li 'view' to be valid. 1191 */ 1192 1193 bool 1194 dns_view_staleanswerenabled(dns_view_t *view); 1195 /*%< 1196 * Check if stale answers are enabled for this view. 1197 * 1198 * Requires: 1199 *\li 'view' to be valid. 1200 */ 1201 1202 void 1203 dns_view_flushonshutdown(dns_view_t *view, bool flush); 1204 /*%< 1205 * Inform the view that the zones should (or should not) be flushed to 1206 * disk on shutdown. 1207 * 1208 * Requires: 1209 *\li 'view' to be valid. 1210 */ 1211 1212 void 1213 dns_view_sfd_add(dns_view_t *view, const dns_name_t *name); 1214 /*%< 1215 * Add 'name' to the synth-from-dnssec namespace tree for the 1216 * view. If the tree does not already exist create it. 1217 * 1218 * Requires: 1219 *\li 'view' to be valid. 1220 *\li 'name' to be valid. 1221 */ 1222 1223 void 1224 dns_view_sfd_del(dns_view_t *view, const dns_name_t *name); 1225 /*%< 1226 * Delete 'name' to the synth-from-dnssec namespace tree for 1227 * the view when the count of previous adds and deletes becomes 1228 * zero. 1229 * 1230 * Requires: 1231 *\li 'view' to be valid. 1232 *\li 'name' to be valid. 1233 */ 1234 1235 void 1236 dns_view_sfd_find(dns_view_t *view, const dns_name_t *name, 1237 dns_name_t *foundname); 1238 /*%< 1239 * Find the enclosing name to the synth-from-dnssec namespace tree for 'name' 1240 * in the specified view. 1241 * 1242 * Requires: 1243 *\li 'view' to be valid. 1244 *\li 'name' to be valid. 1245 *\li 'foundname' to be valid with a buffer sufficient to hold the name. 1246 */ 1247 1248 isc_result_t 1249 dns_view_getresolver(dns_view_t *view, dns_resolver_t **resolverp); 1250 /*%< 1251 * Return the resolver associated with the view. 1252 */ 1253 1254 void 1255 dns_view_setmaxrrperset(dns_view_t *view, uint32_t value); 1256 /*%< 1257 * Set the maximum resource records per RRSet that can be cached. 1258 */ 1259 1260 void 1261 dns_view_setmaxtypepername(dns_view_t *view, uint32_t value); 1262 /*%< 1263 * Set the maximum resource record types per owner name that can be cached. 1264 */ 1265 1266 void 1267 dns_view_setudpsize(dns_view_t *view, uint16_t udpsize); 1268 /*%< 1269 * Set the EDNS UDP buffer size advertised by the server. 1270 */ 1271 1272 uint16_t 1273 dns_view_getudpsize(dns_view_t *view); 1274 /*%< 1275 * Get the current EDNS UDP buffer size. 1276 */ 1277 1278 dns_dispatchmgr_t * 1279 dns_view_getdispatchmgr(dns_view_t *view); 1280 /*%< 1281 * Get the attached dispatch manager for the view; this will be used 1282 * by the resolver and request managers to send and receive DNS 1283 * messages. 1284 */ 1285 1286 isc_result_t 1287 dns_view_addtrustedkey(dns_view_t *view, dns_rdatatype_t rdtype, 1288 const dns_name_t *keyname, isc_buffer_t *databuf); 1289 /*%< 1290 * Add a DNSSEC trusted key to a view of class 'IN'. 'rdtype' is the type 1291 * of the RR data for the key, either DNSKEY or DS. 'keyname' is the DNS 1292 * name of the key, and 'databuf' stores the RR data. 1293 * 1294 * Requires: 1295 * 1296 *\li 'view' is a valid view. 1297 * 1298 *\li 'view' is class 'IN'. 1299 * 1300 *\li 'keyname' is a valid name. 1301 * 1302 *\li 'keydatabuf' is a valid buffer. 1303 * 1304 * Returns: 1305 * 1306 *\li #ISC_R_SUCCESS On success. 1307 * 1308 *\li Anything else Failure. 1309 */ 1310 1311 isc_result_t 1312 dns_view_apply(dns_view_t *view, bool stop, isc_result_t *sub, 1313 isc_result_t (*action)(dns_zone_t *, void *), void *uap); 1314 /*%< 1315 * Call dns_zt_apply on the view's zonetable. 1316 * 1317 * Returns: 1318 * \li ISC_R_SUCCESS if action was applied to all nodes. If 'stop' is 1319 * false and 'sub' is non NULL then the first error (if any) 1320 * reported by 'action' is returned in '*sub'. If 'stop' is true, 1321 * the first error code from 'action' is returned. 1322 * 1323 * \li ISC_R_SHUTTINGDOWN if the view is in the process of shutting down. 1324 */ 1325 1326 void 1327 dns_view_getadb(dns_view_t *view, dns_adb_t **adbp); 1328 /*%< 1329 * Get the view's adb if it exist. 1330 * 1331 * Requires: 1332 * 1333 *\li 'view' is a valid view. 1334 *\li 'adbp' is non-NULL and '*adbp' is NULL. 1335 */ 1336 1337 void 1338 dns_view_setmaxrestarts(dns_view_t *view, uint8_t max_restarts); 1339 /*%< 1340 * Set the number of permissible chained queries before we give up, 1341 * to prevent CNAME loops. This defaults to 11. 1342 * 1343 * Requires: 1344 * 1345 *\li 'view' is valid; 1346 *\li 'max_restarts' is greater than 0. 1347 */ 1348 1349 void 1350 dns_view_setmaxqueries(dns_view_t *view, uint16_t max_queries); 1351 /*% 1352 * Set the number of permissible outgoing queries before we give up. 1353 * This defaults to 200. 1354 * 1355 * Requires: 1356 * 1357 *\li 'view' is valid; 1358 *\li 'max_queries' is greater than 0. 1359 */ 1360 1361 ISC_LANG_ENDDECLS 1362
Indexes created Sat Jun 13 00:24:39 UTC 2026