view.h

Go to the documentation of this file.
00001 /*
00002  * Copyright (C) 2004-2015  Internet Systems Consortium, Inc. ("ISC")
00003  * Copyright (C) 1999-2003  Internet Software Consortium.
00004  *
00005  * Permission to use, copy, modify, and/or distribute this software for any
00006  * purpose with or without fee is hereby granted, provided that the above
00007  * copyright notice and this permission notice appear in all copies.
00008  *
00009  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
00010  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
00011  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
00012  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
00013  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
00014  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
00015  * PERFORMANCE OF THIS SOFTWARE.
00016  */
00017 
00018 #ifndef DNS_VIEW_H
00019 #define DNS_VIEW_H 1
00020 
00021 /*****
00022  ***** Module Info
00023  *****/
00024 
00025 /*! \file dns/view.h
00026  * \brief
00027  * DNS View
00028  *
00029  * A "view" is a DNS namespace, together with an optional resolver and a
00030  * forwarding policy.  A "DNS namespace" is a (possibly empty) set of
00031  * authoritative zones together with an optional cache and optional
00032  * "hints" information.
00033  *
00034  * Views start out "unfrozen".  In this state, core attributes like
00035  * the cache, set of zones, and forwarding policy may be set.  While
00036  * "unfrozen", the caller (e.g. nameserver configuration loading
00037  * code), must ensure exclusive access to the view.  When the view is
00038  * "frozen", the core attributes become immutable, and the view module
00039  * will ensure synchronization.  Freezing allows the view's core attributes
00040  * to be accessed without locking.
00041  *
00042  * MP:
00043  *\li   Before the view is frozen, the caller must ensure synchronization.
00044  *
00045  *\li   After the view is frozen, the module guarantees appropriate
00046  *      synchronization of any data structures it creates and manipulates.
00047  *
00048  * Reliability:
00049  *\li   No anticipated impact.
00050  *
00051  * Resources:
00052  *\li   TBS
00053  *
00054  * Security:
00055  *\li   No anticipated impact.
00056  *
00057  * Standards:
00058  *\li   None.
00059  */
00060 
00061 #include <stdio.h>
00062 
00063 #include <isc/lang.h>
00064 #include <isc/magic.h>
00065 #include <isc/event.h>
00066 #include <isc/mutex.h>
00067 #include <isc/net.h>
00068 #include <isc/refcount.h>
00069 #include <isc/rwlock.h>
00070 #include <isc/stdtime.h>
00071 
00072 #include <dns/acl.h>
00073 #include <dns/clientinfo.h>
00074 #include <dns/fixedname.h>
00075 #include <dns/rrl.h>
00076 #include <dns/rdatastruct.h>
00077 #include <dns/rpz.h>
00078 #include <dns/types.h>
00079 #include <dns/zt.h>
00080 
00081 ISC_LANG_BEGINDECLS
00082 
00083 struct dns_view {
00084         /* Unlocked. */
00085         unsigned int                    magic;
00086         isc_mem_t *                     mctx;
00087         dns_rdataclass_t                rdclass;
00088         char *                          name;
00089         dns_zt_t *                      zonetable;
00090         dns_resolver_t *                resolver;
00091         dns_adb_t *                     adb;
00092         dns_requestmgr_t *              requestmgr;
00093         dns_acache_t *                  acache;
00094         dns_cache_t *                   cache;
00095         dns_db_t *                      cachedb;
00096         dns_db_t *                      hints;
00097 
00098         /*
00099          * security roots and negative trust anchors.
00100          * internal use only; access via * dns_view_getsecroots()
00101          */
00102         dns_keytable_t *                secroots_priv;
00103         dns_ntatable_t *                ntatable_priv;
00104 
00105         isc_mutex_t                     lock;
00106         isc_boolean_t                   frozen;
00107         isc_task_t *                    task;
00108         isc_event_t                     resevent;
00109         isc_event_t                     adbevent;
00110         isc_event_t                     reqevent;
00111         isc_stats_t *                   adbstats;
00112         isc_stats_t *                   resstats;
00113         dns_stats_t *                   resquerystats;
00114         isc_boolean_t                   cacheshared;
00115 
00116         /* Configurable data. */
00117         dns_tsig_keyring_t *            statickeys;
00118         dns_tsig_keyring_t *            dynamickeys;
00119         dns_peerlist_t *                peers;
00120         dns_order_t *                   order;
00121         dns_fwdtable_t *                fwdtable;
00122         isc_boolean_t                   recursion;
00123         isc_boolean_t                   auth_nxdomain;
00124         isc_boolean_t                   additionalfromcache;
00125         isc_boolean_t                   additionalfromauth;
00126         isc_boolean_t                   minimalresponses;
00127         isc_boolean_t                   enablednssec;
00128         isc_boolean_t                   enablevalidation;
00129         isc_boolean_t                   acceptexpired;
00130         dns_transfer_format_t           transfer_format;
00131         dns_acl_t *                     cacheacl;
00132         dns_acl_t *                     cacheonacl;
00133         dns_acl_t *                     queryacl;
00134         dns_acl_t *                     queryonacl;
00135         dns_acl_t *                     recursionacl;
00136         dns_acl_t *                     recursiononacl;
00137         dns_acl_t *                     sortlist;
00138         dns_acl_t *                     notifyacl;
00139         dns_acl_t *                     transferacl;
00140         dns_acl_t *                     updateacl;
00141         dns_acl_t *                     upfwdacl;
00142         dns_acl_t *                     denyansweracl;
00143         dns_acl_t *                     nocasecompress;
00144         dns_rbt_t *                     answeracl_exclude;
00145         dns_rbt_t *                     denyanswernames;
00146         dns_rbt_t *                     answernames_exclude;
00147         dns_rrl_t *                     rrl;
00148         isc_boolean_t                   provideixfr;
00149         isc_boolean_t                   requestnsid;
00150         isc_boolean_t                   requestsit;
00151         dns_ttl_t                       maxcachettl;
00152         dns_ttl_t                       maxncachettl;
00153         isc_uint32_t                    nta_lifetime;
00154         isc_uint32_t                    nta_recheck;
00155         char                            *nta_file;
00156         dns_ttl_t                       prefetch_trigger;
00157         dns_ttl_t                       prefetch_eligible;
00158         in_port_t                       dstport;
00159         dns_aclenv_t                    aclenv;
00160         dns_rdatatype_t                 preferred_glue;
00161         isc_boolean_t                   flush;
00162         dns_namelist_t *                delonly;
00163         isc_boolean_t                   rootdelonly;
00164         dns_namelist_t *                rootexclude;
00165         isc_boolean_t                   checknames;
00166         dns_name_t *                    dlv;
00167         dns_fixedname_t                 dlv_fixed;
00168         isc_uint16_t                    maxudp;
00169         isc_uint16_t                    situdp;
00170         unsigned int                    maxbits;
00171         dns_aaaa_t                      v4_aaaa;
00172         dns_aaaa_t                      v6_aaaa;
00173         dns_acl_t *                     aaaa_acl;
00174         dns_dns64list_t                 dns64;
00175         unsigned int                    dns64cnt;
00176         dns_rpz_zones_t                 *rpzs;
00177         dns_dlzdblist_t                 dlz_searched;
00178         dns_dlzdblist_t                 dlz_unsearched;
00179         isc_uint32_t                    fail_ttl;
00180         dns_badcache_t                  *failcache;
00181 
00182         /*
00183          * Configurable data for server use only,
00184          * locked by server configuration lock.
00185          */
00186         dns_acl_t *                     matchclients;
00187         dns_acl_t *                     matchdestinations;
00188         isc_boolean_t                   matchrecursiveonly;
00189 
00190         /* Locked by themselves. */
00191         isc_refcount_t                  references;
00192 
00193         /* Locked by lock. */
00194         unsigned int                    weakrefs;
00195         unsigned int                    attributes;
00196         /* Under owner's locking control. */
00197         ISC_LINK(struct dns_view)       link;
00198         dns_viewlist_t *                viewlist;
00199 
00200         dns_zone_t *                    managed_keys;
00201         dns_zone_t *                    redirect;
00202         dns_name_t *                    redirectzone;   /* points to redirectfixed
00203                                                            when valid */
00204         dns_fixedname_t                 redirectfixed;
00205 
00206         /*
00207          * File and configuration data for zones added at runtime
00208          * (only used in BIND9).
00209          *
00210          * XXX: This should be a pointer to an opaque type that
00211          * named implements.
00212          */
00213         char *                          new_zone_file;
00214         void *                          new_zone_config;
00215         void                            (*cfg_destroy)(void **);
00216 
00217         unsigned char                   secret[32];     /* Client secret */
00218 };
00219 
00220 #define DNS_VIEW_MAGIC                  ISC_MAGIC('V','i','e','w')
00221 #define DNS_VIEW_VALID(view)            ISC_MAGIC_VALID(view, DNS_VIEW_MAGIC)
00222 
00223 #define DNS_VIEWATTR_RESSHUTDOWN        0x01
00224 #define DNS_VIEWATTR_ADBSHUTDOWN        0x02
00225 #define DNS_VIEWATTR_REQSHUTDOWN        0x04
00226 
00227 isc_result_t
00228 dns_view_create(isc_mem_t *mctx, dns_rdataclass_t rdclass,
00229                 const char *name, dns_view_t **viewp);
00230 /*%<
00231  * Create a view.
00232  *
00233  * Notes:
00234  *
00235  *\li   The newly created view has no cache, no resolver, and an empty
00236  *      zone table.  The view is not frozen.
00237  *
00238  * Requires:
00239  *
00240  *\li   'mctx' is a valid memory context.
00241  *
00242  *\li   'rdclass' is a valid class.
00243  *
00244  *\li   'name' is a valid C string.
00245  *
00246  *\li   viewp != NULL && *viewp == NULL
00247  *
00248  * Returns:
00249  *
00250  *\li   #ISC_R_SUCCESS
00251  *\li   #ISC_R_NOMEMORY
00252  *
00253  *\li   Other errors are possible.
00254  */
00255 
00256 void
00257 dns_view_attach(dns_view_t *source, dns_view_t **targetp);
00258 /*%<
00259  * Attach '*targetp' to 'source'.
00260  *
00261  * Requires:
00262  *
00263  *\li   'source' is a valid, frozen view.
00264  *
00265  *\li   'targetp' points to a NULL dns_view_t *.
00266  *
00267  * Ensures:
00268  *
00269  *\li   *targetp is attached to source.
00270  *
00271  *\li   While *targetp is attached, the view will not shut down.
00272  */
00273 
00274 void
00275 dns_view_detach(dns_view_t **viewp);
00276 /*%<
00277  * Detach '*viewp' from its view.
00278  *
00279  * Requires:
00280  *
00281  *\li   'viewp' points to a valid dns_view_t *
00282  *
00283  * Ensures:
00284  *
00285  *\li   *viewp is NULL.
00286  */
00287 
00288 void
00289 dns_view_flushanddetach(dns_view_t **viewp);
00290 /*%<
00291  * Detach '*viewp' from its view.  If this was the last reference
00292  * uncommitted changed in zones will be flushed to disk.
00293  *
00294  * Requires:
00295  *
00296  *\li   'viewp' points to a valid dns_view_t *
00297  *
00298  * Ensures:
00299  *
00300  *\li   *viewp is NULL.
00301  */
00302 
00303 void
00304 dns_view_weakattach(dns_view_t *source, dns_view_t **targetp);
00305 /*%<
00306  * Weakly attach '*targetp' to 'source'.
00307  *
00308  * Requires:
00309  *
00310  *\li   'source' is a valid, frozen view.
00311  *
00312  *\li   'targetp' points to a NULL dns_view_t *.
00313  *
00314  * Ensures:
00315  *
00316  *\li   *targetp is attached to source.
00317  *
00318  * \li  While *targetp is attached, the view will not be freed.
00319  */
00320 
00321 void
00322 dns_view_weakdetach(dns_view_t **targetp);
00323 /*%<
00324  * Detach '*viewp' from its view.
00325  *
00326  * Requires:
00327  *
00328  *\li   'viewp' points to a valid dns_view_t *.
00329  *
00330  * Ensures:
00331  *
00332  *\li   *viewp is NULL.
00333  */
00334 
00335 isc_result_t
00336 dns_view_createzonetable(dns_view_t *view);
00337 /*%<
00338  * Create a zonetable for the view.
00339  *
00340  * Requires:
00341  *
00342  *\li   'view' is a valid, unfrozen view.
00343  *
00344  *\li   'view' does not have a zonetable already.
00345  *
00346  * Returns:
00347  *
00348  *\li           #ISC_R_SUCCESS
00349  *
00350  *\li   Any error that dns_zt_create() can return.
00351  */
00352 
00353 isc_result_t
00354 dns_view_createresolver(dns_view_t *view,
00355                         isc_taskmgr_t *taskmgr,
00356                         unsigned int ntasks, unsigned int ndisp,
00357                         isc_socketmgr_t *socketmgr,
00358                         isc_timermgr_t *timermgr,
00359                         unsigned int options,
00360                         dns_dispatchmgr_t *dispatchmgr,
00361                         dns_dispatch_t *dispatchv4,
00362                         dns_dispatch_t *dispatchv6);
00363 /*%<
00364  * Create a resolver and address database for the view.
00365  *
00366  * Requires:
00367  *
00368  *\li   'view' is a valid, unfrozen view.
00369  *
00370  *\li   'view' does not have a resolver already.
00371  *
00372  *\li   The requirements of dns_resolver_create() apply to 'taskmgr',
00373  *      'ntasks', 'socketmgr', 'timermgr', 'options', 'dispatchv4', and
00374  *      'dispatchv6'.
00375  *
00376  * Returns:
00377  *
00378  *\li           #ISC_R_SUCCESS
00379  *
00380  *\li   Any error that dns_resolver_create() can return.
00381  */
00382 
00383 void
00384 dns_view_setcache(dns_view_t *view, dns_cache_t *cache);
00385 void
00386 dns_view_setcache2(dns_view_t *view, dns_cache_t *cache, isc_boolean_t shared);
00387 /*%<
00388  * Set the view's cache database.  If 'shared' is true, this means the cache
00389  * is created by another view and is shared with that view.  dns_view_setcache()
00390  * is a backward compatible version equivalent to setcache2(..., ISC_FALSE).
00391  *
00392  * Requires:
00393  *
00394  *\li   'view' is a valid, unfrozen view.
00395  *
00396  *\li   'cache' is a valid cache.
00397  *
00398  * Ensures:
00399  *
00400  * \li          The cache of 'view' is 'cached.
00401  *
00402  *\li   If this is not the first call to dns_view_setcache() for this
00403  *      view, then previously set cache is detached.
00404  */
00405 
00406 void
00407 dns_view_sethints(dns_view_t *view, dns_db_t *hints);
00408 /*%<
00409  * Set the view's hints database.
00410  *
00411  * Requires:
00412  *
00413  *\li   'view' is a valid, unfrozen view, whose hints database has not been
00414  *      set.
00415  *
00416  *\li   'hints' is a valid zone database.
00417  *
00418  * Ensures:
00419  *
00420  * \li          The hints database of 'view' is 'hints'.
00421  */
00422 
00423 void
00424 dns_view_setkeyring(dns_view_t *view, dns_tsig_keyring_t *ring);
00425 void
00426 dns_view_setdynamickeyring(dns_view_t *view, dns_tsig_keyring_t *ring);
00427 /*%<
00428  * Set the view's static TSIG keys
00429  *
00430  * Requires:
00431  *
00432  *   \li   'view' is a valid, unfrozen view, whose static TSIG keyring has not
00433  *      been set.
00434  *
00435  *\li      'ring' is a valid TSIG keyring
00436  *
00437  * Ensures:
00438  *
00439  *\li      The static TSIG keyring of 'view' is 'ring'.
00440  */
00441 
00442 void
00443 dns_view_getdynamickeyring(dns_view_t *view, dns_tsig_keyring_t **ringp);
00444 /*%<
00445  * Return the views dynamic keys.
00446  *
00447  *   \li  'view' is a valid, unfrozen view.
00448  *   \li  'ringp' != NULL && ringp == NULL.
00449  */
00450 
00451 void
00452 dns_view_setdstport(dns_view_t *view, in_port_t dstport);
00453 /*%<
00454  * Set the view's destination port.  This is the port to
00455  * which outgoing queries are sent.  The default is 53,
00456  * the standard DNS port.
00457  *
00458  * Requires:
00459  *
00460  *\li      'view' is a valid view.
00461  *
00462  *\li      'dstport' is a valid TCP/UDP port number.
00463  *
00464  * Ensures:
00465  *\li   External name servers will be assumed to be listening
00466  *      on 'dstport'.  For servers whose address has already
00467  *      obtained obtained at the time of the call, the view may
00468  *      continue to use the previously set port until the address
00469  *      times out from the view's address database.
00470  */
00471 
00472 
00473 isc_result_t
00474 dns_view_addzone(dns_view_t *view, dns_zone_t *zone);
00475 /*%<
00476  * Add zone 'zone' to 'view'.
00477  *
00478  * Requires:
00479  *
00480  *\li   'view' is a valid, unfrozen view.
00481  *
00482  *\li   'zone' is a valid zone.
00483  */
00484 
00485 void
00486 dns_view_freeze(dns_view_t *view);
00487 /*%<
00488  * Freeze view.  No changes can be made to view configuration while frozen.
00489  *
00490  * Requires:
00491  *
00492  *\li   'view' is a valid, unfrozen view.
00493  *
00494  * Ensures:
00495  *
00496  *\li   'view' is frozen.
00497  */
00498 
00499 void
00500 dns_view_thaw(dns_view_t *view);
00501 /*%<
00502  * Thaw view.  This allows zones to be added or removed at runtime.  This is
00503  * NOT thread-safe; the caller MUST have run isc_task_exclusive() prior to
00504  * thawing the view.
00505  *
00506  * Requires:
00507  *
00508  *\li   'view' is a valid, frozen view.
00509  *
00510  * Ensures:
00511  *
00512  *\li   'view' is no longer frozen.
00513  */
00514 isc_result_t
00515 dns_view_find(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type,
00516               isc_stdtime_t now, unsigned int options, isc_boolean_t use_hints,
00517               dns_db_t **dbp, dns_dbnode_t **nodep, dns_name_t *foundname,
00518               dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
00519 isc_result_t
00520 dns_view_find2(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type,
00521                isc_stdtime_t now, unsigned int options,
00522                isc_boolean_t use_hints, isc_boolean_t use_static_stub,
00523                dns_db_t **dbp, dns_dbnode_t **nodep, dns_name_t *foundname,
00524                dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
00525 /*%<
00526  * Find an rdataset whose owner name is 'name', and whose type is
00527  * 'type'.
00528  * In general, this function first searches view's zone and cache DBs for the
00529  * best match data against 'name'.  If nothing found there, and if 'use_hints'
00530  * is ISC_TRUE, the view's hint DB (if configured) is searched.
00531  * If the view is configured with a static-stub zone which gives the longest
00532  * match for 'name' among the zones, however, the cache DB is not consulted
00533  * unless 'use_static_stub' is ISC_FALSE (see below about this argument).
00534  *
00535  * dns_view_find() is a backward compatible version equivalent to
00536  * dns_view_find2() with use_static_stub argument being ISC_FALSE.
00537  *
00538  * Notes:
00539  *
00540  *\li   See the description of dns_db_find() for information about 'options'.
00541  *      If the caller sets #DNS_DBFIND_GLUEOK, it must ensure that 'name'
00542  *      and 'type' are appropriate for glue retrieval.
00543  *
00544  *\li   If 'now' is zero, then the current time will be used.
00545  *
00546  *\li   If 'use_hints' is ISC_TRUE, and the view has a hints database, then
00547  *      it will be searched last.  If the answer is found in the hints
00548  *      database, the result code will be DNS_R_HINT.  If the name is found
00549  *      in the hints database but not the type, the result code will be
00550  *      #DNS_R_HINTNXRRSET.
00551  *
00552  *\li   If 'use_static_stub' is ISC_FALSE and the longest match zone for 'name'
00553  *      is a static-stub zone, it's ignored and the cache and/or hints will be
00554  *      searched.  In the majority of the cases this argument should be
00555  *      ISC_FALSE.  The only known usage of this argument being ISC_TRUE is
00556  *      if this search is for a "bailiwick" glue A or AAAA RRset that may
00557  *      best match a static-stub zone.  Consider the following example:
00558  *      this view is configured with a static-stub zone "example.com",
00559  *      and an attempt of recursive resolution needs to send a query for the
00560  *      zone.  In this case it's quite likely that the resolver is trying to
00561  *      find A/AAAA RRs for the apex name "example.com".  And, to honor the
00562  *      static-stub configuration it needs to return the glue RRs in the
00563  *      static-stub zone even if that exact RRs coming from the authoritative
00564  *      zone has been cached.
00565  *      In other general cases, the requested data is better to be
00566  *      authoritative, either locally configured or retrieved from an external
00567  *      server, and the data in the static-stub zone should better be ignored.
00568  *
00569  *\li   'foundname' must meet the requirements of dns_db_find().
00570  *
00571  *\li   If 'sigrdataset' is not NULL, and there is a SIG rdataset which
00572  *      covers 'type', then 'sigrdataset' will be bound to it.
00573  *
00574  * Requires:
00575  *
00576  *\li   'view' is a valid, frozen view.
00577  *
00578  *\li   'name' is valid name.
00579  *
00580  *\li   'type' is a valid dns_rdatatype_t, and is not a meta query type
00581  *      except dns_rdatatype_any.
00582  *
00583  *\li   dbp == NULL || *dbp == NULL
00584  *
00585  *\li   nodep == NULL || *nodep == NULL.  If nodep != NULL, dbp != NULL.
00586  *
00587  *\li   'foundname' is a valid name with a dedicated buffer or NULL.
00588  *
00589  *\li   'rdataset' is a valid, disassociated rdataset.
00590  *
00591  *\li   'sigrdataset' is NULL, or is a valid, disassociated rdataset.
00592  *
00593  * Ensures:
00594  *
00595  *\li   In successful cases, 'rdataset', and possibly 'sigrdataset', are
00596  *      bound to the found data.
00597  *
00598  *\li   If dbp != NULL, it points to the database containing the data.
00599  *
00600  *\li   If nodep != NULL, it points to the database node containing the data.
00601  *
00602  *\li   If foundname != NULL, it contains the full name of the found data.
00603  *
00604  * Returns:
00605  *
00606  *\li   Any result that dns_db_find() can return, with the exception of
00607  *      #DNS_R_DELEGATION.
00608  */
00609 
00610 isc_result_t
00611 dns_view_simplefind(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type,
00612                     isc_stdtime_t now, unsigned int options,
00613                     isc_boolean_t use_hints,
00614                     dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
00615 /*%<
00616  * Find an rdataset whose owner name is 'name', and whose type is
00617  * 'type'.
00618  *
00619  * Notes:
00620  *
00621  *\li   This routine is appropriate for simple, exact-match queries of the
00622  *      view.  'name' must be a canonical name; there is no DNAME or CNAME
00623  *      processing.
00624  *
00625  *\li   See the description of dns_db_find() for information about 'options'.
00626  *      If the caller sets DNS_DBFIND_GLUEOK, it must ensure that 'name'
00627  *      and 'type' are appropriate for glue retrieval.
00628  *
00629  *\li   If 'now' is zero, then the current time will be used.
00630  *
00631  *\li   If 'use_hints' is ISC_TRUE, and the view has a hints database, then
00632  *      it will be searched last.  If the answer is found in the hints
00633  *      database, the result code will be DNS_R_HINT.  If the name is found
00634  *      in the hints database but not the type, the result code will be
00635  *      DNS_R_HINTNXRRSET.
00636  *
00637  *\li   If 'sigrdataset' is not NULL, and there is a SIG rdataset which
00638  *      covers 'type', then 'sigrdataset' will be bound to it.
00639  *
00640  * Requires:
00641  *
00642  *\li   'view' is a valid, frozen view.
00643  *
00644  *\li   'name' is valid name.
00645  *
00646  *\li   'type' is a valid dns_rdatatype_t, and is not a meta query type
00647  *      (e.g. dns_rdatatype_any), or dns_rdatatype_rrsig.
00648  *
00649  *\li   'rdataset' is a valid, disassociated rdataset.
00650  *
00651  *\li   'sigrdataset' is NULL, or is a valid, disassociated rdataset.
00652  *
00653  * Ensures:
00654  *
00655  *\li   In successful cases, 'rdataset', and possibly 'sigrdataset', are
00656  *      bound to the found data.
00657  *
00658  * Returns:
00659  *
00660  *\li   #ISC_R_SUCCESS                  Success; result is desired type.
00661  *\li   DNS_R_GLUE                      Success; result is glue.
00662  *\li   DNS_R_HINT                      Success; result is a hint.
00663  *\li   DNS_R_NCACHENXDOMAIN            Success; result is a ncache entry.
00664  *\li   DNS_R_NCACHENXRRSET             Success; result is a ncache entry.
00665  *\li   DNS_R_NXDOMAIN                  The name does not exist.
00666  *\li   DNS_R_NXRRSET                   The rrset does not exist.
00667  *\li   #ISC_R_NOTFOUND                 No matching data found,
00668  *                                      or an error occurred.
00669  */
00670 
00671 /*% See dns_view_findzonecut2() */
00672 isc_result_t
00673 dns_view_findzonecut(dns_view_t *view, dns_name_t *name, dns_name_t *fname,
00674                      isc_stdtime_t now, unsigned int options,
00675                      isc_boolean_t use_hints,
00676                      dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
00677 
00678 isc_result_t
00679 dns_view_findzonecut2(dns_view_t *view, dns_name_t *name, dns_name_t *fname,
00680                       isc_stdtime_t now, unsigned int options,
00681                       isc_boolean_t use_hints, isc_boolean_t use_cache,
00682                       dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
00683 /*%<
00684  * Find the best known zonecut containing 'name'.
00685  *
00686  * This uses local authority, cache, and optionally hints data.
00687  * No external queries are performed.
00688  *
00689  * Notes:
00690  *
00691  *\li   If 'now' is zero, then the current time will be used.
00692  *
00693  *\li   If 'use_hints' is ISC_TRUE, and the view has a hints database, then
00694  *      it will be searched last.
00695  *
00696  *\li   If 'use_cache' is ISC_TRUE, and the view has a cache, then it will be
00697  *      searched.
00698  *
00699  *\li   If 'sigrdataset' is not NULL, and there is a SIG rdataset which
00700  *      covers 'type', then 'sigrdataset' will be bound to it.
00701  *
00702  *\li   If the DNS_DBFIND_NOEXACT option is set, then the zonecut returned
00703  *      (if any) will be the deepest known ancestor of 'name'.
00704  *
00705  * Requires:
00706  *
00707  *\li   'view' is a valid, frozen view.
00708  *
00709  *\li   'name' is valid name.
00710  *
00711  *\li   'rdataset' is a valid, disassociated rdataset.
00712  *
00713  *\li   'sigrdataset' is NULL, or is a valid, disassociated rdataset.
00714  *
00715  * Returns:
00716  *
00717  *\li   #ISC_R_SUCCESS                          Success.
00718  *
00719  *\li   Many other results are possible.
00720  */
00721 
00722 isc_result_t
00723 dns_viewlist_find(dns_viewlist_t *list, const char *name,
00724                   dns_rdataclass_t rdclass, dns_view_t **viewp);
00725 /*%<
00726  * Search for a view with name 'name' and class 'rdclass' in 'list'.
00727  * If found, '*viewp' is (strongly) attached to it.
00728  *
00729  * Requires:
00730  *
00731  *\li   'viewp' points to a NULL dns_view_t *.
00732  *
00733  * Returns:
00734  *
00735  *\li   #ISC_R_SUCCESS          A matching view was found.
00736  *\li   #ISC_R_NOTFOUND         No matching view was found.
00737  */
00738 
00739 isc_result_t
00740 dns_viewlist_findzone(dns_viewlist_t *list, dns_name_t *name, isc_boolean_t allclasses,
00741                       dns_rdataclass_t rdclass, dns_zone_t **zonep);
00742 
00743 /*%<
00744  * Search zone with 'name' in view with 'rdclass' in viewlist 'list'
00745  * If found, zone is returned in *zonep. If allclasses is set rdclass is ignored
00746  *
00747  * Returns:
00748  *\li   #ISC_R_SUCCESS          A matching zone was found.
00749  *\li   #ISC_R_NOTFOUND         No matching zone was found.
00750  *\li   #ISC_R_MULTIPLE         Multiple zones with the same name were found.
00751  */
00752 
00753 isc_result_t
00754 dns_view_findzone(dns_view_t *view, dns_name_t *name, dns_zone_t **zonep);
00755 /*%<
00756  * Search for the zone 'name' in the zone table of 'view'.
00757  * If found, 'zonep' is (strongly) attached to it.  There
00758  * are no partial matches.
00759  *
00760  * Requires:
00761  *
00762  *\li   'zonep' points to a NULL dns_zone_t *.
00763  *
00764  * Returns:
00765  *\li   #ISC_R_SUCCESS          A matching zone was found.
00766  *\li   #ISC_R_NOTFOUND         No matching zone was found.
00767  *\li   others                  An error occurred.
00768  */
00769 
00770 isc_result_t
00771 dns_view_load(dns_view_t *view, isc_boolean_t stop);
00772 
00773 isc_result_t
00774 dns_view_loadnew(dns_view_t *view, isc_boolean_t stop);
00775 
00776 isc_result_t
00777 dns_view_asyncload(dns_view_t *view, dns_zt_allloaded_t callback, void *arg);
00778 /*%<
00779  * Load zones attached to this view.  dns_view_load() loads
00780  * all zones whose master file has changed since the last
00781  * load; dns_view_loadnew() loads only zones that have never
00782  * been loaded.
00783  *
00784  * dns_view_asyncload() loads zones asynchronously.  When all zones
00785  * in the view have finished loading, 'callback' is called with argument
00786  * 'arg' to inform the caller.
00787  *
00788  * If 'stop' is ISC_TRUE, stop on the first error and return it.
00789  * If 'stop' is ISC_FALSE (or we are loading asynchronously), ignore errors.
00790  *
00791  * Requires:
00792  *
00793  *\li   'view' is valid.
00794  */
00795 
00796 isc_result_t
00797 dns_view_gettsig(dns_view_t *view, dns_name_t *keyname,
00798                  dns_tsigkey_t **keyp);
00799 /*%<
00800  * Find the TSIG key configured in 'view' with name 'keyname',
00801  * if any.
00802  *
00803  * Requires:
00804  *\li   keyp points to a NULL dns_tsigkey_t *.
00805  *
00806  * Returns:
00807  *\li   #ISC_R_SUCCESS  A key was found and '*keyp' now points to it.
00808  *\li   #ISC_R_NOTFOUND No key was found.
00809  *\li   others          An error occurred.
00810  */
00811 
00812 isc_result_t
00813 dns_view_getpeertsig(dns_view_t *view, isc_netaddr_t *peeraddr,
00814                      dns_tsigkey_t **keyp);
00815 /*%<
00816  * Find the TSIG key configured in 'view' for the server whose
00817  * address is 'peeraddr', if any.
00818  *
00819  * Requires:
00820  *      keyp points to a NULL dns_tsigkey_t *.
00821  *
00822  * Returns:
00823  *\li   #ISC_R_SUCCESS  A key was found and '*keyp' now points to it.
00824  *\li   #ISC_R_NOTFOUND No key was found.
00825  *\li   others          An error occurred.
00826  */
00827 
00828 isc_result_t
00829 dns_view_checksig(dns_view_t *view, isc_buffer_t *source, dns_message_t *msg);
00830 /*%<
00831  * Verifies the signature of a message.
00832  *
00833  * Requires:
00834  *
00835  *\li   'view' is a valid view.
00836  *\li   'source' is a valid buffer containing the message
00837  *\li   'msg' is a valid message
00838  *
00839  * Returns:
00840  *\li   see dns_tsig_verify()
00841  */
00842 
00843 void
00844 dns_view_dialup(dns_view_t *view);
00845 /*%<
00846  * Perform dialup-time maintenance on the zones of 'view'.
00847  */
00848 
00849 isc_result_t
00850 dns_view_dumpdbtostream(dns_view_t *view, FILE *fp);
00851 /*%<
00852  * Dump the current state of the view 'view' to the stream 'fp'
00853  * for purposes of analysis or debugging.
00854  *
00855  * Currently the dumped state includes the view's cache; in the future
00856  * it may also include other state such as the address database.
00857  * It will not not include authoritative data since it is voluminous and
00858  * easily obtainable by other means.
00859  *
00860  * Requires:
00861  *
00862  *\li   'view' is valid.
00863  *
00864  *\li   'fp' refers to a file open for writing.
00865  *
00866  * Returns:
00867  * \li  ISC_R_SUCCESS   The cache was successfully dumped.
00868  * \li  others          An error occurred (see dns_master_dump)
00869  */
00870 
00871 isc_result_t
00872 dns_view_flushcache(dns_view_t *view);
00873 isc_result_t
00874 dns_view_flushcache2(dns_view_t *view, isc_boolean_t fixuponly);
00875 /*%<
00876  * Flush the view's cache (and ADB).  If 'fixuponly' is true, it only updates
00877  * the internal reference to the cache DB with omitting actual flush operation.
00878  * 'fixuponly' is intended to be used for a view that shares a cache with
00879  * a different view.  dns_view_flushcache() is a backward compatible version
00880  * that always sets fixuponly to false.
00881  *
00882  * Requires:
00883  *      'view' is valid.
00884  *
00885  *      No other tasks are executing.
00886  *
00887  * Returns:
00888  *\li   #ISC_R_SUCCESS
00889  *\li   #ISC_R_NOMEMORY
00890  */
00891 
00892 isc_result_t
00893 dns_view_flushnode(dns_view_t *view, dns_name_t *name, isc_boolean_t tree);
00894 /*%<
00895  * Flush the given name from the view's cache (and optionally ADB/badcache).
00896  *
00897  * Flush the given name from the cache, ADB, and bad cache.  If 'tree'
00898  * is true, also flush all subdomains of 'name'.
00899  *
00900  * Requires:
00901  *\li   'view' is valid.
00902  *\li   'name' is valid.
00903  *
00904  * Returns:
00905  *\li   #ISC_R_SUCCESS
00906  *      other returns are failures.
00907  */
00908 
00909 isc_result_t
00910 dns_view_flushname(dns_view_t *view, dns_name_t *name);
00911 /*%<
00912  * Flush the given name from the view's cache, ADB and badcache.
00913  * Equivalent to dns_view_flushnode(view, name, ISC_FALSE).
00914  *
00915  *
00916  * Requires:
00917  *\li   'view' is valid.
00918  *\li   'name' is valid.
00919  *
00920  * Returns:
00921  *\li   #ISC_R_SUCCESS
00922  *      other returns are failures.
00923  */
00924 
00925 isc_result_t
00926 dns_view_adddelegationonly(dns_view_t *view, dns_name_t *name);
00927 /*%<
00928  * Add the given name to the delegation only table.
00929  *
00930  * Requires:
00931  *\li   'view' is valid.
00932  *\li   'name' is valid.
00933  *
00934  * Returns:
00935  *\li   #ISC_R_SUCCESS
00936  *\li   #ISC_R_NOMEMORY
00937  */
00938 
00939 isc_result_t
00940 dns_view_excludedelegationonly(dns_view_t *view, dns_name_t *name);
00941 /*%<
00942  * Add the given name to be excluded from the root-delegation-only.
00943  *
00944  *
00945  * Requires:
00946  *\li   'view' is valid.
00947  *\li   'name' is valid.
00948  *
00949  * Returns:
00950  *\li   #ISC_R_SUCCESS
00951  *\li   #ISC_R_NOMEMORY
00952  */
00953 
00954 isc_boolean_t
00955 dns_view_isdelegationonly(dns_view_t *view, dns_name_t *name);
00956 /*%<
00957  * Check if 'name' is in the delegation only table or if
00958  * rootdelonly is set that name is not being excluded.
00959  *
00960  * Requires:
00961  *\li   'view' is valid.
00962  *\li   'name' is valid.
00963  *
00964  * Returns:
00965  *\li   #ISC_TRUE if the name is the table.
00966  *\li   #ISC_FALSE otherwise.
00967  */
00968 
00969 void
00970 dns_view_setrootdelonly(dns_view_t *view, isc_boolean_t value);
00971 /*%<
00972  * Set the root delegation only flag.
00973  *
00974  * Requires:
00975  *\li   'view' is valid.
00976  */
00977 
00978 isc_boolean_t
00979 dns_view_getrootdelonly(dns_view_t *view);
00980 /*%<
00981  * Get the root delegation only flag.
00982  *
00983  * Requires:
00984  *\li   'view' is valid.
00985  */
00986 
00987 isc_result_t
00988 dns_view_freezezones(dns_view_t *view, isc_boolean_t freeze);
00989 /*%<
00990  * Freeze/thaw updates to master zones.
00991  *
00992  * Requires:
00993  * \li  'view' is valid.
00994  */
00995 
00996 void
00997 dns_view_setadbstats(dns_view_t *view, isc_stats_t *stats);
00998 /*%<
00999  * Set a adb statistics set 'stats' for 'view'.
01000  *
01001  * Requires:
01002  * \li  'view' is valid and is not frozen.
01003  *
01004  *\li   stats is a valid statistics supporting adb statistics
01005  *      (see dns/stats.h).
01006  */
01007 
01008 void
01009 dns_view_getadbstats(dns_view_t *view, isc_stats_t **statsp);
01010 /*%<
01011  * Get the adb statistics counter set for 'view'.  If a statistics set is
01012  * set '*statsp' will be attached to the set; otherwise, '*statsp' will be
01013  * untouched.
01014  *
01015  * Requires:
01016  * \li  'view' is valid and is not frozen.
01017  *
01018  *\li   'statsp' != NULL && '*statsp' != NULL
01019  */
01020 
01021 void
01022 dns_view_setresstats(dns_view_t *view, isc_stats_t *stats);
01023 /*%<
01024  * Set a general resolver statistics counter set 'stats' for 'view'.
01025  *
01026  * Requires:
01027  * \li  'view' is valid and is not frozen.
01028  *
01029  *\li   stats is a valid statistics supporting resolver statistics counters
01030  *      (see dns/stats.h).
01031  */
01032 
01033 void
01034 dns_view_getresstats(dns_view_t *view, isc_stats_t **statsp);
01035 /*%<
01036  * Get the general statistics counter set for 'view'.  If a statistics set is
01037  * set '*statsp' will be attached to the set; otherwise, '*statsp' will be
01038  * untouched.
01039  *
01040  * Requires:
01041  * \li  'view' is valid and is not frozen.
01042  *
01043  *\li   'statsp' != NULL && '*statsp' != NULL
01044  */
01045 
01046 void
01047 dns_view_setresquerystats(dns_view_t *view, dns_stats_t *stats);
01048 /*%<
01049  * Set a statistics counter set of rdata type, 'stats', for 'view'.  Once the
01050  * statistic set is installed, view's resolver will count outgoing queries
01051  * per rdata type.
01052  *
01053  * Requires:
01054  * \li  'view' is valid and is not frozen.
01055  *
01056  *\li   stats is a valid statistics created by dns_rdatatypestats_create().
01057  */
01058 
01059 void
01060 dns_view_getresquerystats(dns_view_t *view, dns_stats_t **statsp);
01061 /*%<
01062  * Get the rdatatype statistics counter set for 'view'.  If a statistics set is
01063  * set '*statsp' will be attached to the set; otherwise, '*statsp' will be
01064  * untouched.
01065  *
01066  * Requires:
01067  * \li  'view' is valid and is not frozen.
01068  *
01069  *\li   'statsp' != NULL && '*statsp' != NULL
01070  */
01071 
01072 isc_boolean_t
01073 dns_view_iscacheshared(dns_view_t *view);
01074 /*%<
01075  * Check if the view shares the cache created by another view.
01076  *
01077  * Requires:
01078  * \li  'view' is valid.
01079  *
01080  * Returns:
01081  *\li   #ISC_TRUE if the cache is shared.
01082  *\li   #ISC_FALSE otherwise.
01083  */
01084 
01085 isc_result_t
01086 dns_view_initntatable(dns_view_t *view,
01087                       isc_taskmgr_t *taskmgr, isc_timermgr_t *timermgr);
01088 /*%<
01089  * Initialize the negative trust anchor table for the view.
01090  *
01091  * Requires:
01092  * \li  'view' is valid.
01093  *
01094  * Returns:
01095  *\li   ISC_R_SUCCESS
01096  *\li   Any other result indicates failure
01097  */
01098 
01099 isc_result_t
01100 dns_view_getntatable(dns_view_t *view, dns_ntatable_t **ntp);
01101 /*%<
01102  * Get the negative trust anchor table for this view.  Returns
01103  * ISC_R_NOTFOUND if the table not been initialized for the view.
01104  *
01105  * '*ntp' is attached on success; the caller is responsible for
01106  * detaching it with dns_ntatable_detach().
01107  *
01108  * Requires:
01109  * \li  'view' is valid.
01110  * \li  'nta' is not NULL and '*nta' is NULL.
01111  *
01112  * Returns:
01113  *\li   ISC_R_SUCCESS
01114  *\li   ISC_R_NOTFOUND
01115  */
01116 
01117 isc_result_t
01118 dns_view_initsecroots(dns_view_t *view, isc_mem_t *mctx);
01119 /*%<
01120  * Initialize security roots for the view, detaching any previously
01121  * existing security roots first.  (Note that secroots_priv is
01122  * NULL until this function is called, so any function using
01123  * security roots must check that they have been initialized first.
01124  * One way to do this is use dns_view_getsecroots() and check its
01125  * return value.)
01126  *
01127  * Requires:
01128  * \li  'view' is valid.
01129  *
01130  * Returns:
01131  *\li   ISC_R_SUCCESS
01132  *\li   Any other result indicates failure
01133  */
01134 
01135 isc_result_t
01136 dns_view_getsecroots(dns_view_t *view, dns_keytable_t **ktp);
01137 /*%<
01138  * Get the security roots for this view.  Returns ISC_R_NOTFOUND if
01139  * the security roots keytable has not been initialized for the view.
01140  *
01141  * '*ktp' is attached on success; the caller is responsible for
01142  * detaching it with dns_keytable_detach().
01143  *
01144  * Requires:
01145  * \li  'view' is valid.
01146  * \li  'ktp' is not NULL and '*ktp' is NULL.
01147  *
01148  * Returns:
01149  *\li   ISC_R_SUCCESS
01150  *\li   ISC_R_NOTFOUND
01151  */
01152 
01153 isc_result_t
01154 dns_view_issecuredomain(dns_view_t *view, dns_name_t *name,
01155                         isc_stdtime_t now, isc_boolean_t checknta,
01156                         isc_boolean_t *secure_domain);
01157 /*%<
01158  * Is 'name' at or beneath a trusted key, and not covered by a valid
01159  * negative trust anchor?  Put answer in '*secure_domain'.
01160  *
01161  * If 'checknta' is ISC_FALSE, ignore the NTA table in determining
01162  * whether this is a secure domain.
01163  *
01164  * Requires:
01165  * \li  'view' is valid.
01166  *
01167  * Returns:
01168  *\li   ISC_R_SUCCESS
01169  *\li   Any other value indicates failure
01170  */
01171 
01172 isc_boolean_t
01173 dns_view_ntacovers(dns_view_t *view, isc_stdtime_t now,
01174                    dns_name_t *name, dns_name_t *anchor);
01175 /*%<
01176  * Is there a current negative trust anchor above 'name' and below 'anchor'?
01177  *
01178  * Requires:
01179  * \li  'view' is valid.
01180  *
01181  * Returns:
01182  *\li   ISC_R_TRUE
01183  *\li   ISC_R_FALSE
01184  */
01185 
01186 void
01187 dns_view_untrust(dns_view_t *view, dns_name_t *keyname,
01188                  dns_rdata_dnskey_t *dnskey, isc_mem_t *mctx);
01189 /*%<
01190  * Remove keys that match 'keyname' and 'dnskey' from the views trust
01191  * anchors.
01192  *
01193  * Requires:
01194  * \li  'view' is valid.
01195  * \li  'keyname' is valid.
01196  * \li  'mctx' is valid.
01197  * \li  'dnskey' is valid.
01198  */
01199 
01200 void
01201 dns_view_setnewzones(dns_view_t *view, isc_boolean_t allow, void *cfgctx,
01202                      void (*cfg_destroy)(void **));
01203 /*%<
01204  * Set whether or not to allow zones to be created or deleted at runtime.
01205  *
01206  * If 'allow' is ISC_TRUE, determines the filename into which new zone
01207  * configuration will be written.  Preserves the configuration context
01208  * (a pointer to which is passed in 'cfgctx') for use when parsing new
01209  * zone configuration.  'cfg_destroy' points to a callback routine to
01210  * destroy the configuration context when the view is destroyed.  (This
01211  * roundabout method is used in order to avoid libdns having a dependency
01212  * on libisccfg and libbind9.)
01213  *
01214  * If 'allow' is ISC_FALSE, removes any existing references to
01215  * configuration context and frees any memory.
01216  *
01217  * Requires:
01218  * \li 'view' is valid.
01219  */
01220 
01221 void
01222 dns_view_restorekeyring(dns_view_t *view);
01223 
01224 isc_result_t
01225 dns_view_searchdlz(dns_view_t *view, dns_name_t *name,
01226                    unsigned int minlabels,
01227                    dns_clientinfomethods_t *methods,
01228                    dns_clientinfo_t *clientinfo,
01229                    dns_db_t **dbp);
01230 
01231 /*%<
01232  * Search through the DLZ database(s) in view->dlz_searched to find
01233  * one that can answer a query for 'name', using the DLZ driver's
01234  * findzone method.  If successful, '*dbp' is set to point to the
01235  * DLZ database.
01236  *
01237  * Returns:
01238  * \li ISC_R_SUCCESS
01239  * \li ISC_R_NOTFOUND
01240  *
01241  * Requires:
01242  * \li 'view' is valid.
01243  * \li 'name' is not NULL.
01244  * \li 'dbp' is not NULL and *dbp is NULL.
01245  */
01246 
01247 isc_uint32_t
01248 dns_view_getfailttl(dns_view_t *view);
01249 /*%<
01250  * Get the view's servfail-ttl.  zero => no servfail caching.
01251  *
01252  * Requires:
01253  *\li   'view' to be valid.
01254  */
01255 
01256 void
01257 dns_view_setfailttl(dns_view_t *view, isc_uint32_t failttl);
01258 /*%<
01259  * Set the view's servfail-ttl.  zero => no servfail caching.
01260  *
01261  * Requires:
01262  *\li   'view' to be valid.
01263  */
01264 
01265 isc_result_t
01266 dns_view_saventa(dns_view_t *view);
01267 /*%<
01268  * Save NTA for names in this view to a file.
01269  *
01270  * Requires:
01271  *\li   'view' to be valid.
01272  */
01273 
01274 isc_result_t
01275 dns_view_loadnta(dns_view_t *view);
01276 /*%<
01277  * Loads NTA for names in this view from a file.
01278  *
01279  * Requires:
01280  *\li   'view' to be valid.
01281  */
01282 
01283 ISC_LANG_ENDDECLS
01284 
01285 #endif /* DNS_VIEW_H */

Generated on Tue Apr 28 17:40:57 2015 by Doxygen 1.5.4 for BIND9 Internals 9.11.0pre-alpha