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