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