contrib/bind9/lib/dns/include/dns/view.h

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