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

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