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

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