1 /* $NetBSD: view.h,v 1.10 2014/12/10 04:37:58 christos Exp $ */ 2 3 /* 4 * Copyright (C) 2004-2014 Internet Systems Consortium, Inc. ("ISC") 5 * Copyright (C) 1999-2003 Internet Software Consortium. 6 * 7 * Permission to use, copy, modify, and/or distribute this software for any 8 * purpose with or without fee is hereby granted, provided that the above 9 * copyright notice and this permission notice appear in all copies. 10 * 11 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 12 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 13 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 14 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 15 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 16 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 17 * PERFORMANCE OF THIS SOFTWARE. 18 */ 19 20 /* Id */ 21 22 #ifndef DNS_VIEW_H 23 #define DNS_VIEW_H 1 24 25 /***** 26 ***** Module Info 27 *****/ 28 29 /*! \file dns/view.h 30 * \brief 31 * DNS View 32 * 33 * A "view" is a DNS namespace, together with an optional resolver and a 34 * forwarding policy. A "DNS namespace" is a (possibly empty) set of 35 * authoritative zones together with an optional cache and optional 36 * "hints" information. 37 * 38 * Views start out "unfrozen". In this state, core attributes like 39 * the cache, set of zones, and forwarding policy may be set. While 40 * "unfrozen", the caller (e.g. nameserver configuration loading 41 * code), must ensure exclusive access to the view. When the view is 42 * "frozen", the core attributes become immutable, and the view module 43 * will ensure synchronization. Freezing allows the view's core attributes 44 * to be accessed without locking. 45 * 46 * MP: 47 *\li Before the view is frozen, the caller must ensure synchronization. 48 * 49 *\li After the view is frozen, the module guarantees appropriate 50 * synchronization of any data structures it creates and manipulates. 51 * 52 * Reliability: 53 *\li No anticipated impact. 54 * 55 * Resources: 56 *\li TBS 57 * 58 * Security: 59 *\li No anticipated impact. 60 * 61 * Standards: 62 *\li None. 63 */ 64 65 #include <stdio.h> 66 67 #include <isc/lang.h> 68 #include <isc/magic.h> 69 #include <isc/event.h> 70 #include <isc/mutex.h> 71 #include <isc/net.h> 72 #include <isc/refcount.h> 73 #include <isc/rwlock.h> 74 #include <isc/stdtime.h> 75 76 #include <dns/acl.h> 77 #include <dns/clientinfo.h> 78 #include <dns/fixedname.h> 79 #include <dns/rrl.h> 80 #include <dns/rdatastruct.h> 81 #include <dns/rpz.h> 82 #include <dns/types.h> 83 #include <dns/zt.h> 84 85 ISC_LANG_BEGINDECLS 86 87 struct dns_view { 88 /* Unlocked. */ 89 unsigned int magic; 90 isc_mem_t * mctx; 91 dns_rdataclass_t rdclass; 92 char * name; 93 dns_zt_t * zonetable; 94 dns_resolver_t * resolver; 95 dns_adb_t * adb; 96 dns_requestmgr_t * requestmgr; 97 dns_acache_t * acache; 98 dns_cache_t * cache; 99 dns_db_t * cachedb; 100 dns_db_t * hints; 101 102 /* 103 * security roots. 104 * internal use only; access via * dns_view_getsecroots() 105 */ 106 dns_keytable_t * secroots_priv; 107 108 isc_mutex_t lock; 109 isc_boolean_t frozen; 110 isc_task_t * task; 111 isc_event_t resevent; 112 isc_event_t adbevent; 113 isc_event_t reqevent; 114 isc_stats_t * adbstats; 115 isc_stats_t * resstats; 116 dns_stats_t * resquerystats; 117 isc_boolean_t cacheshared; 118 119 /* Configurable data. */ 120 dns_tsig_keyring_t * statickeys; 121 dns_tsig_keyring_t * dynamickeys; 122 dns_peerlist_t * peers; 123 dns_order_t * order; 124 dns_fwdtable_t * fwdtable; 125 isc_boolean_t recursion; 126 isc_boolean_t auth_nxdomain; 127 isc_boolean_t additionalfromcache; 128 isc_boolean_t additionalfromauth; 129 isc_boolean_t minimalresponses; 130 isc_boolean_t enablednssec; 131 isc_boolean_t enablevalidation; 132 isc_boolean_t acceptexpired; 133 dns_transfer_format_t transfer_format; 134 dns_acl_t * cacheacl; 135 dns_acl_t * cacheonacl; 136 dns_acl_t * queryacl; 137 dns_acl_t * queryonacl; 138 dns_acl_t * recursionacl; 139 dns_acl_t * recursiononacl; 140 dns_acl_t * sortlist; 141 dns_acl_t * notifyacl; 142 dns_acl_t * transferacl; 143 dns_acl_t * updateacl; 144 dns_acl_t * upfwdacl; 145 dns_acl_t * denyansweracl; 146 dns_acl_t * nocasecompress; 147 dns_rbt_t * answeracl_exclude; 148 dns_rbt_t * denyanswernames; 149 dns_rbt_t * answernames_exclude; 150 dns_rrl_t * rrl; 151 isc_boolean_t provideixfr; 152 isc_boolean_t requestnsid; 153 isc_boolean_t requestsit; 154 dns_ttl_t maxcachettl; 155 dns_ttl_t maxncachettl; 156 dns_ttl_t prefetch_trigger; 157 dns_ttl_t prefetch_eligible; 158 in_port_t dstport; 159 dns_aclenv_t aclenv; 160 dns_rdatatype_t preferred_glue; 161 isc_boolean_t flush; 162 dns_namelist_t * delonly; 163 isc_boolean_t rootdelonly; 164 dns_namelist_t * rootexclude; 165 isc_boolean_t checknames; 166 dns_name_t * dlv; 167 dns_fixedname_t dlv_fixed; 168 isc_uint16_t maxudp; 169 isc_uint16_t situdp; 170 unsigned int maxbits; 171 dns_aaaa_t v4_aaaa; 172 dns_aaaa_t v6_aaaa; 173 dns_acl_t * aaaa_acl; 174 dns_dns64list_t dns64; 175 unsigned int dns64cnt; 176 dns_rpz_zones_t *rpzs; 177 dns_dlzdblist_t dlz_searched; 178 dns_dlzdblist_t dlz_unsearched; 179 180 /* 181 * Configurable data for server use only, 182 * locked by server configuration lock. 183 */ 184 dns_acl_t * matchclients; 185 dns_acl_t * matchdestinations; 186 isc_boolean_t matchrecursiveonly; 187 188 /* Locked by themselves. */ 189 isc_refcount_t references; 190 191 /* Locked by lock. */ 192 unsigned int weakrefs; 193 unsigned int attributes; 194 /* Under owner's locking control. */ 195 ISC_LINK(struct dns_view) link; 196 dns_viewlist_t * viewlist; 197 198 dns_zone_t * managed_keys; 199 dns_zone_t * redirect; 200 201 /* 202 * File and configuration data for zones added at runtime 203 * (only used in BIND9). 204 * 205 * XXX: This should be a pointer to an opaque type that 206 * named implements. 207 */ 208 char * new_zone_file; 209 void * new_zone_config; 210 void (*cfg_destroy)(void **); 211 212 unsigned char secret[32]; /* Client secret */ 213 }; 214 215 #define DNS_VIEW_MAGIC ISC_MAGIC('V','i','e','w') 216 #define DNS_VIEW_VALID(view) ISC_MAGIC_VALID(view, DNS_VIEW_MAGIC) 217 218 #define DNS_VIEWATTR_RESSHUTDOWN 0x01 219 #define DNS_VIEWATTR_ADBSHUTDOWN 0x02 220 #define DNS_VIEWATTR_REQSHUTDOWN 0x04 221 222 isc_result_t 223 dns_view_create(isc_mem_t *mctx, dns_rdataclass_t rdclass, 224 const char *name, dns_view_t **viewp); 225 /*%< 226 * Create a view. 227 * 228 * Notes: 229 * 230 *\li The newly created view has no cache, no resolver, and an empty 231 * zone table. The view is not frozen. 232 * 233 * Requires: 234 * 235 *\li 'mctx' is a valid memory context. 236 * 237 *\li 'rdclass' is a valid class. 238 * 239 *\li 'name' is a valid C string. 240 * 241 *\li viewp != NULL && *viewp == NULL 242 * 243 * Returns: 244 * 245 *\li #ISC_R_SUCCESS 246 *\li #ISC_R_NOMEMORY 247 * 248 *\li Other errors are possible. 249 */ 250 251 void 252 dns_view_attach(dns_view_t *source, dns_view_t **targetp); 253 /*%< 254 * Attach '*targetp' to 'source'. 255 * 256 * Requires: 257 * 258 *\li 'source' is a valid, frozen view. 259 * 260 *\li 'targetp' points to a NULL dns_view_t *. 261 * 262 * Ensures: 263 * 264 *\li *targetp is attached to source. 265 * 266 *\li While *targetp is attached, the view will not shut down. 267 */ 268 269 void 270 dns_view_detach(dns_view_t **viewp); 271 /*%< 272 * Detach '*viewp' from its view. 273 * 274 * Requires: 275 * 276 *\li 'viewp' points to a valid dns_view_t * 277 * 278 * Ensures: 279 * 280 *\li *viewp is NULL. 281 */ 282 283 void 284 dns_view_flushanddetach(dns_view_t **viewp); 285 /*%< 286 * Detach '*viewp' from its view. If this was the last reference 287 * uncommitted changed in zones will be flushed to disk. 288 * 289 * Requires: 290 * 291 *\li 'viewp' points to a valid dns_view_t * 292 * 293 * Ensures: 294 * 295 *\li *viewp is NULL. 296 */ 297 298 void 299 dns_view_weakattach(dns_view_t *source, dns_view_t **targetp); 300 /*%< 301 * Weakly attach '*targetp' to 'source'. 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 be freed. 314 */ 315 316 void 317 dns_view_weakdetach(dns_view_t **targetp); 318 /*%< 319 * Detach '*viewp' from its view. 320 * 321 * Requires: 322 * 323 *\li 'viewp' points to a valid dns_view_t *. 324 * 325 * Ensures: 326 * 327 *\li *viewp is NULL. 328 */ 329 330 isc_result_t 331 dns_view_createzonetable(dns_view_t *view); 332 /*%< 333 * Create a zonetable for the view. 334 * 335 * Requires: 336 * 337 *\li 'view' is a valid, unfrozen view. 338 * 339 *\li 'view' does not have a zonetable already. 340 * 341 * Returns: 342 * 343 *\li #ISC_R_SUCCESS 344 * 345 *\li Any error that dns_zt_create() can return. 346 */ 347 348 isc_result_t 349 dns_view_createresolver(dns_view_t *view, 350 isc_taskmgr_t *taskmgr, 351 unsigned int ntasks, unsigned int ndisp, 352 isc_socketmgr_t *socketmgr, 353 isc_timermgr_t *timermgr, 354 unsigned int options, 355 dns_dispatchmgr_t *dispatchmgr, 356 dns_dispatch_t *dispatchv4, 357 dns_dispatch_t *dispatchv6); 358 /*%< 359 * Create a resolver and address database for the view. 360 * 361 * Requires: 362 * 363 *\li 'view' is a valid, unfrozen view. 364 * 365 *\li 'view' does not have a resolver already. 366 * 367 *\li The requirements of dns_resolver_create() apply to 'taskmgr', 368 * 'ntasks', 'socketmgr', 'timermgr', 'options', 'dispatchv4', and 369 * 'dispatchv6'. 370 * 371 * Returns: 372 * 373 *\li #ISC_R_SUCCESS 374 * 375 *\li Any error that dns_resolver_create() can return. 376 */ 377 378 void 379 dns_view_setcache(dns_view_t *view, dns_cache_t *cache); 380 void 381 dns_view_setcache2(dns_view_t *view, dns_cache_t *cache, isc_boolean_t shared); 382 /*%< 383 * Set the view's cache database. If 'shared' is true, this means the cache 384 * is created by another view and is shared with that view. dns_view_setcache() 385 * is a backward compatible version equivalent to setcache2(..., ISC_FALSE). 386 * 387 * Requires: 388 * 389 *\li 'view' is a valid, unfrozen view. 390 * 391 *\li 'cache' is a valid cache. 392 * 393 * Ensures: 394 * 395 * \li The cache of 'view' is 'cached. 396 * 397 *\li If this is not the first call to dns_view_setcache() for this 398 * view, then previously set cache is detached. 399 */ 400 401 void 402 dns_view_sethints(dns_view_t *view, dns_db_t *hints); 403 /*%< 404 * Set the view's hints database. 405 * 406 * Requires: 407 * 408 *\li 'view' is a valid, unfrozen view, whose hints database has not been 409 * set. 410 * 411 *\li 'hints' is a valid zone database. 412 * 413 * Ensures: 414 * 415 * \li The hints database of 'view' is 'hints'. 416 */ 417 418 void 419 dns_view_setkeyring(dns_view_t *view, dns_tsig_keyring_t *ring); 420 void 421 dns_view_setdynamickeyring(dns_view_t *view, dns_tsig_keyring_t *ring); 422 /*%< 423 * Set the view's static TSIG keys 424 * 425 * Requires: 426 * 427 * \li 'view' is a valid, unfrozen view, whose static TSIG keyring has not 428 * been set. 429 * 430 *\li 'ring' is a valid TSIG keyring 431 * 432 * Ensures: 433 * 434 *\li The static TSIG keyring of 'view' is 'ring'. 435 */ 436 437 void 438 dns_view_getdynamickeyring(dns_view_t *view, dns_tsig_keyring_t **ringp); 439 /*%< 440 * Return the views dynamic keys. 441 * 442 * \li 'view' is a valid, unfrozen view. 443 * \li 'ringp' != NULL && ringp == NULL. 444 */ 445 446 void 447 dns_view_setdstport(dns_view_t *view, in_port_t dstport); 448 /*%< 449 * Set the view's destination port. This is the port to 450 * which outgoing queries are sent. The default is 53, 451 * the standard DNS port. 452 * 453 * Requires: 454 * 455 *\li 'view' is a valid view. 456 * 457 *\li 'dstport' is a valid TCP/UDP port number. 458 * 459 * Ensures: 460 *\li External name servers will be assumed to be listening 461 * on 'dstport'. For servers whose address has already 462 * obtained obtained at the time of the call, the view may 463 * continue to use the previously set port until the address 464 * times out from the view's address database. 465 */ 466 467 468 isc_result_t 469 dns_view_addzone(dns_view_t *view, dns_zone_t *zone); 470 /*%< 471 * Add zone 'zone' to 'view'. 472 * 473 * Requires: 474 * 475 *\li 'view' is a valid, unfrozen view. 476 * 477 *\li 'zone' is a valid zone. 478 */ 479 480 void 481 dns_view_freeze(dns_view_t *view); 482 /*%< 483 * Freeze view. No changes can be made to view configuration while frozen. 484 * 485 * Requires: 486 * 487 *\li 'view' is a valid, unfrozen view. 488 * 489 * Ensures: 490 * 491 *\li 'view' is frozen. 492 */ 493 494 void 495 dns_view_thaw(dns_view_t *view); 496 /*%< 497 * Thaw view. This allows zones to be added or removed at runtime. This is 498 * NOT thread-safe; the caller MUST have run isc_task_exclusive() prior to 499 * thawing the view. 500 * 501 * Requires: 502 * 503 *\li 'view' is a valid, frozen view. 504 * 505 * Ensures: 506 * 507 *\li 'view' is no longer frozen. 508 */ 509 isc_result_t 510 dns_view_find(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type, 511 isc_stdtime_t now, unsigned int options, isc_boolean_t use_hints, 512 dns_db_t **dbp, dns_dbnode_t **nodep, dns_name_t *foundname, 513 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset); 514 isc_result_t 515 dns_view_find2(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type, 516 isc_stdtime_t now, unsigned int options, 517 isc_boolean_t use_hints, isc_boolean_t use_static_stub, 518 dns_db_t **dbp, dns_dbnode_t **nodep, dns_name_t *foundname, 519 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset); 520 /*%< 521 * Find an rdataset whose owner name is 'name', and whose type is 522 * 'type'. 523 * In general, this function first searches view's zone and cache DBs for the 524 * best match data against 'name'. If nothing found there, and if 'use_hints' 525 * is ISC_TRUE, the view's hint DB (if configured) is searched. 526 * If the view is configured with a static-stub zone which gives the longest 527 * match for 'name' among the zones, however, the cache DB is not consulted 528 * unless 'use_static_stub' is ISC_FALSE (see below about this argument). 529 * 530 * dns_view_find() is a backward compatible version equivalent to 531 * dns_view_find2() with use_static_stub argument being ISC_FALSE. 532 * 533 * Notes: 534 * 535 *\li See the description of dns_db_find() for information about 'options'. 536 * If the caller sets #DNS_DBFIND_GLUEOK, it must ensure that 'name' 537 * and 'type' are appropriate for glue retrieval. 538 * 539 *\li If 'now' is zero, then the current time will be used. 540 * 541 *\li If 'use_hints' is ISC_TRUE, and the view has a hints database, then 542 * it will be searched last. If the answer is found in the hints 543 * database, the result code will be DNS_R_HINT. If the name is found 544 * in the hints database but not the type, the result code will be 545 * #DNS_R_HINTNXRRSET. 546 * 547 *\li If 'use_static_stub' is ISC_FALSE and the longest match zone for 'name' 548 * is a static-stub zone, it's ignored and the cache and/or hints will be 549 * searched. In the majority of the cases this argument should be 550 * ISC_FALSE. The only known usage of this argument being ISC_TRUE is 551 * if this search is for a "bailiwick" glue A or AAAA RRset that may 552 * best match a static-stub zone. Consider the following example: 553 * this view is configured with a static-stub zone "example.com", 554 * and an attempt of recursive resolution needs to send a query for the 555 * zone. In this case it's quite likely that the resolver is trying to 556 * find A/AAAA RRs for the apex name "example.com". And, to honor the 557 * static-stub configuration it needs to return the glue RRs in the 558 * static-stub zone even if that exact RRs coming from the authoritative 559 * zone has been cached. 560 * In other general cases, the requested data is better to be 561 * authoritative, either locally configured or retrieved from an external 562 * server, and the data in the static-stub zone should better be ignored. 563 * 564 *\li 'foundname' must meet the requirements of dns_db_find(). 565 * 566 *\li If 'sigrdataset' is not NULL, and there is a SIG rdataset which 567 * covers 'type', then 'sigrdataset' will be bound to it. 568 * 569 * Requires: 570 * 571 *\li 'view' is a valid, frozen view. 572 * 573 *\li 'name' is valid name. 574 * 575 *\li 'type' is a valid dns_rdatatype_t, and is not a meta query type 576 * except dns_rdatatype_any. 577 * 578 *\li dbp == NULL || *dbp == NULL 579 * 580 *\li nodep == NULL || *nodep == NULL. If nodep != NULL, dbp != NULL. 581 * 582 *\li 'foundname' is a valid name with a dedicated buffer or NULL. 583 * 584 *\li 'rdataset' is a valid, disassociated rdataset. 585 * 586 *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset. 587 * 588 * Ensures: 589 * 590 *\li In successful cases, 'rdataset', and possibly 'sigrdataset', are 591 * bound to the found data. 592 * 593 *\li If dbp != NULL, it points to the database containing the data. 594 * 595 *\li If nodep != NULL, it points to the database node containing the data. 596 * 597 *\li If foundname != NULL, it contains the full name of the found data. 598 * 599 * Returns: 600 * 601 *\li Any result that dns_db_find() can return, with the exception of 602 * #DNS_R_DELEGATION. 603 */ 604 605 isc_result_t 606 dns_view_simplefind(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type, 607 isc_stdtime_t now, unsigned int options, 608 isc_boolean_t use_hints, 609 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset); 610 /*%< 611 * Find an rdataset whose owner name is 'name', and whose type is 612 * 'type'. 613 * 614 * Notes: 615 * 616 *\li This routine is appropriate for simple, exact-match queries of the 617 * view. 'name' must be a canonical name; there is no DNAME or CNAME 618 * processing. 619 * 620 *\li See the description of dns_db_find() for information about 'options'. 621 * If the caller sets DNS_DBFIND_GLUEOK, it must ensure that 'name' 622 * and 'type' are appropriate for glue retrieval. 623 * 624 *\li If 'now' is zero, then the current time will be used. 625 * 626 *\li If 'use_hints' is ISC_TRUE, and the view has a hints database, then 627 * it will be searched last. If the answer is found in the hints 628 * database, the result code will be DNS_R_HINT. If the name is found 629 * in the hints database but not the type, the result code will be 630 * DNS_R_HINTNXRRSET. 631 * 632 *\li If 'sigrdataset' is not NULL, and there is a SIG rdataset which 633 * covers 'type', then 'sigrdataset' will be bound to it. 634 * 635 * Requires: 636 * 637 *\li 'view' is a valid, frozen view. 638 * 639 *\li 'name' is valid name. 640 * 641 *\li 'type' is a valid dns_rdatatype_t, and is not a meta query type 642 * (e.g. dns_rdatatype_any), or dns_rdatatype_rrsig. 643 * 644 *\li 'rdataset' is a valid, disassociated rdataset. 645 * 646 *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset. 647 * 648 * Ensures: 649 * 650 *\li In successful cases, 'rdataset', and possibly 'sigrdataset', are 651 * bound to the found data. 652 * 653 * Returns: 654 * 655 *\li #ISC_R_SUCCESS Success; result is desired type. 656 *\li DNS_R_GLUE Success; result is glue. 657 *\li DNS_R_HINT Success; result is a hint. 658 *\li DNS_R_NCACHENXDOMAIN Success; result is a ncache entry. 659 *\li DNS_R_NCACHENXRRSET Success; result is a ncache entry. 660 *\li DNS_R_NXDOMAIN The name does not exist. 661 *\li DNS_R_NXRRSET The rrset does not exist. 662 *\li #ISC_R_NOTFOUND No matching data found, 663 * or an error occurred. 664 */ 665 666 /*% See dns_view_findzonecut2() */ 667 isc_result_t 668 dns_view_findzonecut(dns_view_t *view, dns_name_t *name, dns_name_t *fname, 669 isc_stdtime_t now, unsigned int options, 670 isc_boolean_t use_hints, 671 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset); 672 673 isc_result_t 674 dns_view_findzonecut2(dns_view_t *view, dns_name_t *name, dns_name_t *fname, 675 isc_stdtime_t now, unsigned int options, 676 isc_boolean_t use_hints, isc_boolean_t use_cache, 677 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset); 678 /*%< 679 * Find the best known zonecut containing 'name'. 680 * 681 * This uses local authority, cache, and optionally hints data. 682 * No external queries are performed. 683 * 684 * Notes: 685 * 686 *\li If 'now' is zero, then the current time will be used. 687 * 688 *\li If 'use_hints' is ISC_TRUE, and the view has a hints database, then 689 * it will be searched last. 690 * 691 *\li If 'use_cache' is ISC_TRUE, and the view has a cache, then it will be 692 * searched. 693 * 694 *\li If 'sigrdataset' is not NULL, and there is a SIG rdataset which 695 * covers 'type', then 'sigrdataset' will be bound to it. 696 * 697 *\li If the DNS_DBFIND_NOEXACT option is set, then the zonecut returned 698 * (if any) will be the deepest known ancestor of 'name'. 699 * 700 * Requires: 701 * 702 *\li 'view' is a valid, frozen view. 703 * 704 *\li 'name' is valid name. 705 * 706 *\li 'rdataset' is a valid, disassociated rdataset. 707 * 708 *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset. 709 * 710 * Returns: 711 * 712 *\li #ISC_R_SUCCESS Success. 713 * 714 *\li Many other results are possible. 715 */ 716 717 isc_result_t 718 dns_viewlist_find(dns_viewlist_t *list, const char *name, 719 dns_rdataclass_t rdclass, dns_view_t **viewp); 720 /*%< 721 * Search for a view with name 'name' and class 'rdclass' in 'list'. 722 * If found, '*viewp' is (strongly) attached to it. 723 * 724 * Requires: 725 * 726 *\li 'viewp' points to a NULL dns_view_t *. 727 * 728 * Returns: 729 * 730 *\li #ISC_R_SUCCESS A matching view was found. 731 *\li #ISC_R_NOTFOUND No matching view was found. 732 */ 733 734 isc_result_t 735 dns_viewlist_findzone(dns_viewlist_t *list, dns_name_t *name, isc_boolean_t allclasses, 736 dns_rdataclass_t rdclass, dns_zone_t **zonep); 737 738 /*%< 739 * Search zone with 'name' in view with 'rdclass' in viewlist 'list' 740 * If found, zone is returned in *zonep. If allclasses is set rdclass is ignored 741 * 742 * Returns: 743 *\li #ISC_R_SUCCESS A matching zone was found. 744 *\li #ISC_R_NOTFOUND No matching zone was found. 745 *\li #ISC_R_MULTIPLE Multiple zones with the same name were found. 746 */ 747 748 isc_result_t 749 dns_view_findzone(dns_view_t *view, dns_name_t *name, dns_zone_t **zonep); 750 /*%< 751 * Search for the zone 'name' in the zone table of 'view'. 752 * If found, 'zonep' is (strongly) attached to it. There 753 * are no partial matches. 754 * 755 * Requires: 756 * 757 *\li 'zonep' points to a NULL dns_zone_t *. 758 * 759 * Returns: 760 *\li #ISC_R_SUCCESS A matching zone was found. 761 *\li #ISC_R_NOTFOUND No matching zone was found. 762 *\li others An error occurred. 763 */ 764 765 isc_result_t 766 dns_view_load(dns_view_t *view, isc_boolean_t stop); 767 768 isc_result_t 769 dns_view_loadnew(dns_view_t *view, isc_boolean_t stop); 770 771 isc_result_t 772 dns_view_asyncload(dns_view_t *view, dns_zt_allloaded_t callback, void *arg); 773 /*%< 774 * Load zones attached to this view. dns_view_load() loads 775 * all zones whose master file has changed since the last 776 * load; dns_view_loadnew() loads only zones that have never 777 * been loaded. 778 * 779 * dns_view_asyncload() loads zones asynchronously. When all zones 780 * in the view have finished loading, 'callback' is called with argument 781 * 'arg' to inform the caller. 782 * 783 * If 'stop' is ISC_TRUE, stop on the first error and return it. 784 * If 'stop' is ISC_FALSE (or we are loading asynchronously), ignore errors. 785 * 786 * Requires: 787 * 788 *\li 'view' is valid. 789 */ 790 791 isc_result_t 792 dns_view_gettsig(dns_view_t *view, dns_name_t *keyname, 793 dns_tsigkey_t **keyp); 794 /*%< 795 * Find the TSIG key configured in 'view' with name 'keyname', 796 * if any. 797 * 798 * Requires: 799 *\li keyp points to a NULL dns_tsigkey_t *. 800 * 801 * Returns: 802 *\li #ISC_R_SUCCESS A key was found and '*keyp' now points to it. 803 *\li #ISC_R_NOTFOUND No key was found. 804 *\li others An error occurred. 805 */ 806 807 isc_result_t 808 dns_view_getpeertsig(dns_view_t *view, isc_netaddr_t *peeraddr, 809 dns_tsigkey_t **keyp); 810 /*%< 811 * Find the TSIG key configured in 'view' for the server whose 812 * address is 'peeraddr', if any. 813 * 814 * Requires: 815 * keyp points to a NULL dns_tsigkey_t *. 816 * 817 * Returns: 818 *\li #ISC_R_SUCCESS A key was found and '*keyp' now points to it. 819 *\li #ISC_R_NOTFOUND No key was found. 820 *\li others An error occurred. 821 */ 822 823 isc_result_t 824 dns_view_checksig(dns_view_t *view, isc_buffer_t *source, dns_message_t *msg); 825 /*%< 826 * Verifies the signature of a message. 827 * 828 * Requires: 829 * 830 *\li 'view' is a valid view. 831 *\li 'source' is a valid buffer containing the message 832 *\li 'msg' is a valid message 833 * 834 * Returns: 835 *\li see dns_tsig_verify() 836 */ 837 838 void 839 dns_view_dialup(dns_view_t *view); 840 /*%< 841 * Perform dialup-time maintenance on the zones of 'view'. 842 */ 843 844 isc_result_t 845 dns_view_dumpdbtostream(dns_view_t *view, FILE *fp); 846 /*%< 847 * Dump the current state of the view 'view' to the stream 'fp' 848 * for purposes of analysis or debugging. 849 * 850 * Currently the dumped state includes the view's cache; in the future 851 * it may also include other state such as the address database. 852 * It will not not include authoritative data since it is voluminous and 853 * easily obtainable by other means. 854 * 855 * Requires: 856 * 857 *\li 'view' is valid. 858 * 859 *\li 'fp' refers to a file open for writing. 860 * 861 * Returns: 862 * \li ISC_R_SUCCESS The cache was successfully dumped. 863 * \li others An error occurred (see dns_master_dump) 864 */ 865 866 isc_result_t 867 dns_view_flushcache(dns_view_t *view); 868 isc_result_t 869 dns_view_flushcache2(dns_view_t *view, isc_boolean_t fixuponly); 870 /*%< 871 * Flush the view's cache (and ADB). If 'fixuponly' is true, it only updates 872 * the internal reference to the cache DB with omitting actual flush operation. 873 * 'fixuponly' is intended to be used for a view that shares a cache with 874 * a different view. dns_view_flushcache() is a backward compatible version 875 * that always sets fixuponly to false. 876 * 877 * Requires: 878 * 'view' is valid. 879 * 880 * No other tasks are executing. 881 * 882 * Returns: 883 *\li #ISC_R_SUCCESS 884 *\li #ISC_R_NOMEMORY 885 */ 886 887 isc_result_t 888 dns_view_flushnode(dns_view_t *view, dns_name_t *name, isc_boolean_t tree); 889 /*%< 890 * Flush the given name from the view's cache (and optionally ADB/badcache). 891 * 892 * Flush the given name from the cache, ADB, and bad cache. If 'tree' 893 * is true, also flush all subdomains of 'name'. 894 * 895 * Requires: 896 *\li 'view' is valid. 897 *\li 'name' is valid. 898 * 899 * Returns: 900 *\li #ISC_R_SUCCESS 901 * other returns are failures. 902 */ 903 904 isc_result_t 905 dns_view_flushname(dns_view_t *view, dns_name_t *name); 906 /*%< 907 * Flush the given name from the view's cache, ADB and badcache. 908 * Equivalent to dns_view_flushnode(view, name, ISC_FALSE). 909 * 910 * 911 * Requires: 912 *\li 'view' is valid. 913 *\li 'name' is valid. 914 * 915 * Returns: 916 *\li #ISC_R_SUCCESS 917 * other returns are failures. 918 */ 919 920 isc_result_t 921 dns_view_adddelegationonly(dns_view_t *view, dns_name_t *name); 922 /*%< 923 * Add the given name to the delegation only table. 924 * 925 * Requires: 926 *\li 'view' is valid. 927 *\li 'name' is valid. 928 * 929 * Returns: 930 *\li #ISC_R_SUCCESS 931 *\li #ISC_R_NOMEMORY 932 */ 933 934 isc_result_t 935 dns_view_excludedelegationonly(dns_view_t *view, dns_name_t *name); 936 /*%< 937 * Add the given name to be excluded from the root-delegation-only. 938 * 939 * 940 * Requires: 941 *\li 'view' is valid. 942 *\li 'name' is valid. 943 * 944 * Returns: 945 *\li #ISC_R_SUCCESS 946 *\li #ISC_R_NOMEMORY 947 */ 948 949 isc_boolean_t 950 dns_view_isdelegationonly(dns_view_t *view, dns_name_t *name); 951 /*%< 952 * Check if 'name' is in the delegation only table or if 953 * rootdelonly is set that name is not being excluded. 954 * 955 * Requires: 956 *\li 'view' is valid. 957 *\li 'name' is valid. 958 * 959 * Returns: 960 *\li #ISC_TRUE if the name is the table. 961 *\li #ISC_FALSE otherwise. 962 */ 963 964 void 965 dns_view_setrootdelonly(dns_view_t *view, isc_boolean_t value); 966 /*%< 967 * Set the root delegation only flag. 968 * 969 * Requires: 970 *\li 'view' is valid. 971 */ 972 973 isc_boolean_t 974 dns_view_getrootdelonly(dns_view_t *view); 975 /*%< 976 * Get the root delegation only flag. 977 * 978 * Requires: 979 *\li 'view' is valid. 980 */ 981 982 isc_result_t 983 dns_view_freezezones(dns_view_t *view, isc_boolean_t freeze); 984 /*%< 985 * Freeze/thaw updates to master zones. 986 * 987 * Requires: 988 * \li 'view' is valid. 989 */ 990 991 void 992 dns_view_setadbstats(dns_view_t *view, isc_stats_t *stats); 993 /*%< 994 * Set a adb statistics set 'stats' for 'view'. 995 * 996 * Requires: 997 * \li 'view' is valid and is not frozen. 998 * 999 *\li stats is a valid statistics supporting adb statistics 1000 * (see dns/stats.h). 1001 */ 1002 1003 void 1004 dns_view_getadbstats(dns_view_t *view, isc_stats_t **statsp); 1005 /*%< 1006 * Get the adb statistics counter set for 'view'. If a statistics set is 1007 * set '*statsp' will be attached to the set; otherwise, '*statsp' will be 1008 * untouched. 1009 * 1010 * Requires: 1011 * \li 'view' is valid and is not frozen. 1012 * 1013 *\li 'statsp' != NULL && '*statsp' != NULL 1014 */ 1015 1016 void 1017 dns_view_setresstats(dns_view_t *view, isc_stats_t *stats); 1018 /*%< 1019 * Set a general resolver statistics counter set 'stats' for 'view'. 1020 * 1021 * Requires: 1022 * \li 'view' is valid and is not frozen. 1023 * 1024 *\li stats is a valid statistics supporting resolver statistics counters 1025 * (see dns/stats.h). 1026 */ 1027 1028 void 1029 dns_view_getresstats(dns_view_t *view, isc_stats_t **statsp); 1030 /*%< 1031 * Get the general statistics counter set for 'view'. If a statistics set is 1032 * set '*statsp' will be attached to the set; otherwise, '*statsp' will be 1033 * untouched. 1034 * 1035 * Requires: 1036 * \li 'view' is valid and is not frozen. 1037 * 1038 *\li 'statsp' != NULL && '*statsp' != NULL 1039 */ 1040 1041 void 1042 dns_view_setresquerystats(dns_view_t *view, dns_stats_t *stats); 1043 /*%< 1044 * Set a statistics counter set of rdata type, 'stats', for 'view'. Once the 1045 * statistic set is installed, view's resolver will count outgoing queries 1046 * per rdata type. 1047 * 1048 * Requires: 1049 * \li 'view' is valid and is not frozen. 1050 * 1051 *\li stats is a valid statistics created by dns_rdatatypestats_create(). 1052 */ 1053 1054 void 1055 dns_view_getresquerystats(dns_view_t *view, dns_stats_t **statsp); 1056 /*%< 1057 * Get the rdatatype statistics counter set for 'view'. If a statistics set is 1058 * set '*statsp' will be attached to the set; otherwise, '*statsp' will be 1059 * untouched. 1060 * 1061 * Requires: 1062 * \li 'view' is valid and is not frozen. 1063 * 1064 *\li 'statsp' != NULL && '*statsp' != NULL 1065 */ 1066 1067 isc_boolean_t 1068 dns_view_iscacheshared(dns_view_t *view); 1069 /*%< 1070 * Check if the view shares the cache created by another view. 1071 * 1072 * Requires: 1073 * \li 'view' is valid. 1074 * 1075 * Returns: 1076 *\li #ISC_TRUE if the cache is shared. 1077 *\li #ISC_FALSE otherwise. 1078 */ 1079 1080 isc_result_t 1081 dns_view_initsecroots(dns_view_t *view, isc_mem_t *mctx); 1082 /*%< 1083 * Initialize security roots for the view. (Note that secroots is 1084 * NULL until this function is called, so any function using 1085 * secroots must check its validity first. One way to do this is 1086 * use dns_view_getsecroots() and check its return value.) 1087 * 1088 * Requires: 1089 * \li 'view' is valid. 1090 * \li 'view->secroots' is NULL. 1091 * 1092 * Returns: 1093 *\li ISC_R_SUCCESS 1094 *\li Any other result indicates failure 1095 */ 1096 1097 isc_result_t 1098 dns_view_getsecroots(dns_view_t *view, dns_keytable_t **ktp); 1099 /*%< 1100 * Get the security roots for this view. Returns ISC_R_NOTFOUND if 1101 * the security roots keytable has not been initialized for the view. 1102 * 1103 * '*ktp' is attached on success; the caller is responsible for 1104 * detaching it with dns_keytable_detach(). 1105 * 1106 * Requires: 1107 * \li 'view' is valid. 1108 * \li 'ktp' is not NULL and '*ktp' is NULL. 1109 * 1110 * Returns: 1111 *\li ISC_R_SUCCESS 1112 *\li ISC_R_NOTFOUND 1113 */ 1114 1115 isc_result_t 1116 dns_view_issecuredomain(dns_view_t *view, dns_name_t *name, 1117 isc_boolean_t *secure_domain); 1118 /*%< 1119 * Is 'name' at or beneath a trusted key? Put answer in 1120 * '*secure_domain'. 1121 * 1122 * Requires: 1123 * \li 'view' is valid. 1124 * 1125 * Returns: 1126 *\li ISC_R_SUCCESS 1127 *\li Any other value indicates failure 1128 */ 1129 1130 void 1131 dns_view_untrust(dns_view_t *view, dns_name_t *keyname, 1132 dns_rdata_dnskey_t *dnskey, isc_mem_t *mctx); 1133 /*%< 1134 * Remove keys that match 'keyname' and 'dnskey' from the views trust 1135 * anchors. 1136 * 1137 * Requires: 1138 * \li 'view' is valid. 1139 * \li 'keyname' is valid. 1140 * \li 'mctx' is valid. 1141 * \li 'dnskey' is valid. 1142 */ 1143 1144 void 1145 dns_view_setnewzones(dns_view_t *view, isc_boolean_t allow, void *cfgctx, 1146 void (*cfg_destroy)(void **)); 1147 /*%< 1148 * Set whether or not to allow zones to be created or deleted at runtime. 1149 * 1150 * If 'allow' is ISC_TRUE, determines the filename into which new zone 1151 * configuration will be written. Preserves the configuration context 1152 * (a pointer to which is passed in 'cfgctx') for use when parsing new 1153 * zone configuration. 'cfg_destroy' points to a callback routine to 1154 * destroy the configuration context when the view is destroyed. (This 1155 * roundabout method is used in order to avoid libdns having a dependency 1156 * on libisccfg and libbind9.) 1157 * 1158 * If 'allow' is ISC_FALSE, removes any existing references to 1159 * configuration context and frees any memory. 1160 * 1161 * Requires: 1162 * \li 'view' is valid. 1163 */ 1164 1165 void 1166 dns_view_restorekeyring(dns_view_t *view); 1167 1168 isc_result_t 1169 dns_view_searchdlz(dns_view_t *view, dns_name_t *name, 1170 unsigned int minlabels, 1171 dns_clientinfomethods_t *methods, 1172 dns_clientinfo_t *clientinfo, 1173 dns_db_t **dbp); 1174 1175 /*%< 1176 * Search through the DLZ database(s) in view->dlz_searched to find 1177 * one that can answer a query for 'name', using the DLZ driver's 1178 * findzone method. If successful, '*dbp' is set to point to the 1179 * DLZ database. 1180 * 1181 * Returns: 1182 * \li ISC_R_SUCCESS 1183 * \li ISC_R_NOTFOUND 1184 * 1185 * Requires: 1186 * \li 'view' is valid. 1187 * \li 'name' is not NULL. 1188 * \li 'dbp' is not NULL and *dbp is NULL. 1189 */ 1190 1191 ISC_LANG_ENDDECLS 1192 1193 #endif /* DNS_VIEW_H */ 1194