view.h 34.6 KB
Newer Older
Bob Halley's avatar
add  
Bob Halley committed
1
/*
2
 * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
3
 *
4 5 6
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
7 8 9
 *
 * See the COPYRIGHT file distributed with this work for additional
 * information regarding copyright ownership.
Bob Halley's avatar
add  
Bob Halley committed
10 11 12 13 14 15 16 17 18
 */

#ifndef DNS_VIEW_H
#define DNS_VIEW_H 1

/*****
 ***** Module Info
 *****/

19
/*! \file dns/view.h
20
 * \brief
Bob Halley's avatar
add  
Bob Halley committed
21 22
 * DNS View
 *
Bob Halley's avatar
Bob Halley committed
23 24 25 26 27 28 29 30 31 32 33 34
 * A "view" is a DNS namespace, together with an optional resolver and a
 * forwarding policy.  A "DNS namespace" is a (possibly empty) set of
 * authoritative zones together with an optional cache and optional
 * "hints" information.
 *
 * Views start out "unfrozen".  In this state, core attributes like
 * the cache, set of zones, and forwarding policy may be set.  While
 * "unfrozen", the caller (e.g. nameserver configuration loading
 * code), must ensure exclusive access to the view.  When the view is
 * "frozen", the core attributes become immutable, and the view module
 * will ensure synchronization.  Freezing allows the view's core attributes
 * to be accessed without locking.
Bob Halley's avatar
add  
Bob Halley committed
35 36
 *
 * MP:
37
 *\li	Before the view is frozen, the caller must ensure synchronization.
Bob Halley's avatar
Bob Halley committed
38
 *
39
 *\li	After the view is frozen, the module guarantees appropriate
Bob Halley's avatar
Bob Halley committed
40
 *	synchronization of any data structures it creates and manipulates.
Bob Halley's avatar
add  
Bob Halley committed
41 42
 *
 * Reliability:
43
 *\li	No anticipated impact.
Bob Halley's avatar
add  
Bob Halley committed
44 45
 *
 * Resources:
46
 *\li	TBS
Bob Halley's avatar
add  
Bob Halley committed
47 48
 *
 * Security:
49
 *\li	No anticipated impact.
Bob Halley's avatar
add  
Bob Halley committed
50 51
 *
 * Standards:
52
 *\li	None.
53
 */
Bob Halley's avatar
add  
Bob Halley committed
54

55
#include <stdbool.h>
Brian Wellington's avatar
Brian Wellington committed
56
#include <stdio.h>
57
#include <inttypes.h>
Brian Wellington's avatar
Brian Wellington committed
58

Bob Halley's avatar
add  
Bob Halley committed
59
#include <isc/lang.h>
60
#include <isc/magic.h>
Bob Halley's avatar
add  
Bob Halley committed
61
#include <isc/event.h>
Brian Wellington's avatar
Brian Wellington committed
62
#include <isc/mutex.h>
63
#include <isc/net.h>
64
#include <isc/refcount.h>
65
#include <isc/rwlock.h>
Bob Halley's avatar
Bob Halley committed
66
#include <isc/stdtime.h>
Bob Halley's avatar
add  
Bob Halley committed
67

68
#include <dns/acl.h>
69
#include <dns/catz.h>
70
#include <dns/clientinfo.h>
Evan Hunt's avatar
Evan Hunt committed
71
#include <dns/dnstap.h>
72
#include <dns/fixedname.h>
Evan Hunt's avatar
Evan Hunt committed
73
#include <dns/rrl.h>
74
#include <dns/rdatastruct.h>
75
#include <dns/rpz.h>
Bob Halley's avatar
add  
Bob Halley committed
76
#include <dns/types.h>
77
#include <dns/zt.h>
Bob Halley's avatar
add  
Bob Halley committed
78 79 80 81 82 83 84 85 86

ISC_LANG_BEGINDECLS

struct dns_view {
	/* Unlocked. */
	unsigned int			magic;
	isc_mem_t *			mctx;
	dns_rdataclass_t		rdclass;
	char *				name;
87
	dns_zt_t *			zonetable;
Bob Halley's avatar
add  
Bob Halley committed
88
	dns_resolver_t *		resolver;
Bob Halley's avatar
add adb  
Bob Halley committed
89
	dns_adb_t *			adb;
Mark Andrews's avatar
Mark Andrews committed
90
	dns_requestmgr_t *		requestmgr;
91
	dns_cache_t *			cache;
Bob Halley's avatar
Bob Halley committed
92
	dns_db_t *			cachedb;
Bob Halley's avatar
Bob Halley committed
93
	dns_db_t *			hints;
94 95

	/*
Evan Hunt's avatar
Evan Hunt committed
96
	 * security roots and negative trust anchors.
97 98 99
	 * internal use only; access via * dns_view_getsecroots()
	 */
	dns_keytable_t *		secroots_priv;
Evan Hunt's avatar
Evan Hunt committed
100
	dns_ntatable_t *		ntatable_priv;
101

Bob Halley's avatar
add  
Bob Halley committed
102
	isc_mutex_t			lock;
103
	bool				frozen;
104 105 106
	isc_task_t *			task;
	isc_event_t			resevent;
	isc_event_t			adbevent;
Mark Andrews's avatar
Mark Andrews committed
107
	isc_event_t			reqevent;
108
	isc_stats_t *			adbstats;
109
	isc_stats_t *			resstats;
110
	dns_stats_t *			resquerystats;
111
	bool				cacheshared;
112

113
	/* Configurable data. */
Brian Wellington's avatar
Brian Wellington committed
114 115
	dns_tsig_keyring_t *		statickeys;
	dns_tsig_keyring_t *		dynamickeys;
116
	dns_peerlist_t *		peers;
117
	dns_order_t *			order;
118
	dns_fwdtable_t *		fwdtable;
119 120 121 122 123 124
	bool				recursion;
	bool				qminimization;
	bool				qmin_strict;
	bool				auth_nxdomain;
	bool				use_glue_cache;
	bool				minimal_any;
125
	dns_minimaltype_t		minimalresponses;
126 127 128 129 130 131
	bool				enablevalidation;
	bool				acceptexpired;
	bool				requireservercookie;
	bool				synthfromdnssec;
	bool				trust_anchor_telemetry;
	bool				root_key_sentinel;
132
	dns_transfer_format_t		transfer_format;
133 134
	dns_acl_t *			cacheacl;
	dns_acl_t *			cacheonacl;
135
	dns_acl_t *			queryacl;
136
	dns_acl_t *			queryonacl;
137
	dns_acl_t *			recursionacl;
138
	dns_acl_t *			recursiononacl;
139
	dns_acl_t *			sortlist;
140 141 142 143
	dns_acl_t *			notifyacl;
	dns_acl_t *			transferacl;
	dns_acl_t *			updateacl;
	dns_acl_t *			upfwdacl;
144
	dns_acl_t *			denyansweracl;
Evan Hunt's avatar
Evan Hunt committed
145
	dns_acl_t *			nocasecompress;
146
	bool				msgcompression;
147 148 149
	dns_rbt_t *			answeracl_exclude;
	dns_rbt_t *			denyanswernames;
	dns_rbt_t *			answernames_exclude;
Evan Hunt's avatar
Evan Hunt committed
150
	dns_rrl_t *			rrl;
151 152 153
	bool				provideixfr;
	bool				requestnsid;
	bool				sendcookie;
154 155
	dns_ttl_t			maxcachettl;
	dns_ttl_t			maxncachettl;
156 157
	dns_ttl_t			mincachettl;
	dns_ttl_t			minncachettl;
158 159
	uint32_t			nta_lifetime;
	uint32_t			nta_recheck;
160
	char				*nta_file;
161 162
	dns_ttl_t			prefetch_trigger;
	dns_ttl_t			prefetch_eligible;
163
	in_port_t			dstport;
164
	dns_aclenv_t			aclenv;
165
	dns_rdatatype_t			preferred_glue;
166
	bool				flush;
167
	dns_namelist_t *		delonly;
168
	bool				rootdelonly;
Mark Andrews's avatar
Mark Andrews committed
169
	dns_namelist_t *		rootexclude;
170
	bool				checknames;
171 172
	dns_name_t *			dlv;
	dns_fixedname_t			dlv_fixed;
173
	uint16_t			maxudp;
174 175
	dns_ttl_t			staleanswerttl;
	dns_stale_answer_t		staleanswersok;		/* rndc setting */
176
	bool				staleanswersenable;	/* named.conf setting */
177 178
	uint16_t			nocookieudp;
	uint16_t			padding;
179
	dns_acl_t *			pad_acl;
180
	unsigned int			maxbits;
181 182
	dns_dns64list_t 		dns64;
	unsigned int 			dns64cnt;
183
	dns_rpz_zones_t			*rpzs;
184
	dns_catz_zones_t		*catzs;
Evan Hunt's avatar
Evan Hunt committed
185 186
	dns_dlzdblist_t 		dlz_searched;
	dns_dlzdblist_t 		dlz_unsearched;
187
	uint32_t			fail_ttl;
Evan Hunt's avatar
Evan Hunt committed
188
	dns_badcache_t			*failcache;
189

190 191 192 193 194
	/*
	 * Configurable data for server use only,
	 * locked by server configuration lock.
	 */
	dns_acl_t *			matchclients;
195
	dns_acl_t *			matchdestinations;
196
	bool				matchrecursiveonly;
197

198 199 200
	/* Locked by themselves. */
	isc_refcount_t			references;

Bob Halley's avatar
add  
Bob Halley committed
201
	/* Locked by lock. */
202
	unsigned int			weakrefs;
203
	unsigned int			attributes;
Bob Halley's avatar
add  
Bob Halley committed
204 205
	/* Under owner's locking control. */
	ISC_LINK(struct dns_view)	link;
206
	dns_viewlist_t *		viewlist;
Automatic Updater's avatar
Automatic Updater committed
207

208
	dns_zone_t *			managed_keys;
209
	dns_zone_t *			redirect;
Evan Hunt's avatar
Evan Hunt committed
210
	dns_name_t *			redirectzone;	/* points to
211 212
							 * redirectfixed
							 * when valid */
213
	dns_fixedname_t 		redirectfixed;
214

Tinderbox User's avatar
Tinderbox User committed
215
	/*
216 217 218 219 220 221
	 * File and configuration data for zones added at runtime
	 * (only used in BIND9).
	 *
	 * XXX: This should be a pointer to an opaque type that
	 * named implements.
	 */
222
	char *				new_zone_dir;
223
	char *				new_zone_file;
224
	char *				new_zone_db;
225
	void *				new_zone_dbenv;
226
	uint64_t			new_zone_mapsize;
227 228
	void *				new_zone_config;
	void				(*cfg_destroy)(void **);
229
	isc_mutex_t			new_zone_lock;
230

Mark Andrews's avatar
Mark Andrews committed
231
	unsigned char			secret[32];	/* Client secret */
232
	unsigned int			v6bias;
Evan Hunt's avatar
Evan Hunt committed
233 234 235 236

	dns_dtenv_t			*dtenv;		/* Dnstap environment */
	dns_dtmsgtype_t			dttypes;	/* Dnstap message types
							   to log */
237

238
	/* Registered module instances */
239 240
	void				*plugins;
	void				(*plugins_free)(isc_mem_t *, void **);
241 242

	/* Hook table */
243 244
	void				*hooktable;	/* ns_hooktable */
	void				(*hooktable_free)(isc_mem_t *, void **);
245

Bob Halley's avatar
add  
Bob Halley committed
246 247
};

248
#define DNS_VIEW_MAGIC			ISC_MAGIC('V','i','e','w')
249
#define DNS_VIEW_VALID(view)		ISC_MAGIC_VALID(view, DNS_VIEW_MAGIC)
Bob Halley's avatar
add  
Bob Halley committed
250

251 252
#define DNS_VIEWATTR_RESSHUTDOWN	0x01
#define DNS_VIEWATTR_ADBSHUTDOWN	0x02
Mark Andrews's avatar
Mark Andrews committed
253
#define DNS_VIEWATTR_REQSHUTDOWN	0x04
254

255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273
#ifdef HAVE_LMDB
#include <lmdb.h>
/*
 * MDB_NOTLS is used to prevent problems after configuration is reloaded, due
 * to the way LMDB's use of thread-local storage (TLS) interacts with the BIND9
 * thread model.
 */
#define DNS_LMDB_COMMON_FLAGS		(MDB_CREATE | MDB_NOSUBDIR | MDB_NOTLS)
#ifndef __OpenBSD__
#define DNS_LMDB_FLAGS			(DNS_LMDB_COMMON_FLAGS)
#else /* __OpenBSD__ */
/*
 * OpenBSD does not have a unified buffer cache, which requires both reads and
 * writes to be performed using mmap().
 */
#define DNS_LMDB_FLAGS			(DNS_LMDB_COMMON_FLAGS | MDB_WRITEMAP)
#endif /* __OpenBSD__ */
#endif /* HAVE_LMDB */

Bob Halley's avatar
add  
Bob Halley committed
274
isc_result_t
275 276
dns_view_create(isc_mem_t *mctx, dns_rdataclass_t rdclass,
		const char *name, dns_view_t **viewp);
277
/*%<
Bob Halley's avatar
Bob Halley committed
278 279 280 281
 * Create a view.
 *
 * Notes:
 *
282
 *\li	The newly created view has no cache, no resolver, and an empty
Bob Halley's avatar
Bob Halley committed
283 284 285 286
 *	zone table.  The view is not frozen.
 *
 * Requires:
 *
287
 *\li	'mctx' is a valid memory context.
Bob Halley's avatar
Bob Halley committed
288
 *
289
 *\li	'rdclass' is a valid class.
Bob Halley's avatar
Bob Halley committed
290
 *
291
 *\li	'name' is a valid C string.
Bob Halley's avatar
Bob Halley committed
292
 *
293
 *\li	viewp != NULL && *viewp == NULL
Bob Halley's avatar
Bob Halley committed
294 295 296
 *
 * Returns:
 *
297 298
 *\li	#ISC_R_SUCCESS
 *\li	#ISC_R_NOMEMORY
Bob Halley's avatar
Bob Halley committed
299
 *
300
 *\li	Other errors are possible.
Bob Halley's avatar
Bob Halley committed
301
 */
Bob Halley's avatar
add  
Bob Halley committed
302 303 304

void
dns_view_attach(dns_view_t *source, dns_view_t **targetp);
305
/*%<
Bob Halley's avatar
Bob Halley committed
306 307 308 309
 * Attach '*targetp' to 'source'.
 *
 * Requires:
 *
310
 *\li	'source' is a valid, frozen view.
Bob Halley's avatar
Bob Halley committed
311
 *
312
 *\li	'targetp' points to a NULL dns_view_t *.
Bob Halley's avatar
Bob Halley committed
313 314 315
 *
 * Ensures:
 *
316
 *\li	*targetp is attached to source.
317
 *
318
 *\li	While *targetp is attached, the view will not shut down.
Bob Halley's avatar
Bob Halley committed
319
 */
Bob Halley's avatar
add  
Bob Halley committed
320 321 322

void
dns_view_detach(dns_view_t **viewp);
323
/*%<
Bob Halley's avatar
Bob Halley committed
324 325 326 327
 * Detach '*viewp' from its view.
 *
 * Requires:
 *
328
 *\li	'viewp' points to a valid dns_view_t *
Bob Halley's avatar
Bob Halley committed
329 330 331
 *
 * Ensures:
 *
332
 *\li	*viewp is NULL.
333 334
 */

335 336
void
dns_view_flushanddetach(dns_view_t **viewp);
337
/*%<
338
 * Detach '*viewp' from its view.  If this was the last reference
Francis Dupont's avatar
Francis Dupont committed
339
 * uncommitted changed in zones will be flushed to disk.
340 341 342
 *
 * Requires:
 *
343
 *\li	'viewp' points to a valid dns_view_t *
344 345 346
 *
 * Ensures:
 *
347
 *\li	*viewp is NULL.
348 349
 */

350 351
void
dns_view_weakattach(dns_view_t *source, dns_view_t **targetp);
352
/*%<
353 354 355 356
 * Weakly attach '*targetp' to 'source'.
 *
 * Requires:
 *
357
 *\li	'source' is a valid, frozen view.
358
 *
359
 *\li	'targetp' points to a NULL dns_view_t *.
360 361
 *
 * Ensures:
Bob Halley's avatar
Bob Halley committed
362
 *
363
 *\li	*targetp is attached to source.
364
 *
365
 * \li	While *targetp is attached, the view will not be freed.
366 367 368 369
 */

void
dns_view_weakdetach(dns_view_t **targetp);
370
/*%<
371
 * Detach '*viewp' from its view.
Bob Halley's avatar
Bob Halley committed
372
 *
373 374
 * Requires:
 *
375
 *\li	'viewp' points to a valid dns_view_t *.
376 377 378
 *
 * Ensures:
 *
379
 *\li	*viewp is NULL.
Bob Halley's avatar
Bob Halley committed
380
 */
Bob Halley's avatar
add  
Bob Halley committed
381

382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399
isc_result_t
dns_view_createzonetable(dns_view_t *view);
/*%<
 * Create a zonetable for the view.
 *
 * Requires:
 *
 *\li	'view' is a valid, unfrozen view.
 *
 *\li	'view' does not have a zonetable already.
 *
 * Returns:
 *
 *\li   	#ISC_R_SUCCESS
 *
 *\li	Any error that dns_zt_create() can return.
 */

Bob Halley's avatar
Bob Halley committed
400
isc_result_t
Bob Halley's avatar
Bob Halley committed
401
dns_view_createresolver(dns_view_t *view,
402 403
			isc_taskmgr_t *taskmgr,
			unsigned int ntasks, unsigned int ndisp,
Bob Halley's avatar
Bob Halley committed
404 405
			isc_socketmgr_t *socketmgr,
			isc_timermgr_t *timermgr,
406
			unsigned int options,
407
			dns_dispatchmgr_t *dispatchmgr,
408 409
			dns_dispatch_t *dispatchv4,
			dns_dispatch_t *dispatchv6);
410
/*%<
Bob Halley's avatar
add adb  
Bob Halley committed
411
 * Create a resolver and address database for the view.
Bob Halley's avatar
Bob Halley committed
412 413 414
 *
 * Requires:
 *
415
 *\li	'view' is a valid, unfrozen view.
Bob Halley's avatar
Bob Halley committed
416
 *
417
 *\li	'view' does not have a resolver already.
Bob Halley's avatar
Bob Halley committed
418
 *
419
 *\li	The requirements of dns_resolver_create() apply to 'taskmgr',
420 421
 *	'ntasks', 'socketmgr', 'timermgr', 'options', 'dispatchv4', and
 *	'dispatchv6'.
Bob Halley's avatar
Bob Halley committed
422 423
 *
 * Returns:
Bob Halley's avatar
Bob Halley committed
424
 *
425
 *\li   	#ISC_R_SUCCESS
Bob Halley's avatar
Bob Halley committed
426
 *
427
 *\li	Any error that dns_resolver_create() can return.
Bob Halley's avatar
Bob Halley committed
428
 */
429 430

void
431
dns_view_setcache(dns_view_t *view, dns_cache_t *cache, bool shared);
432
/*%<
433 434
 * Set the view's cache database.  If 'shared' is true, this means the cache
 * is created by another view and is shared with that view.  dns_view_setcache()
435
 * is a backward compatible version equivalent to setcache2(..., false).
Bob Halley's avatar
Bob Halley committed
436 437 438
 *
 * Requires:
 *
439
 *\li	'view' is a valid, unfrozen view.
Bob Halley's avatar
Bob Halley committed
440
 *
441
 *\li	'cache' is a valid cache.
Bob Halley's avatar
Bob Halley committed
442 443 444
 *
 * Ensures:
 *
445
 * \li    	The cache of 'view' is 'cached.
Bob Halley's avatar
add adb  
Bob Halley committed
446
 *
447
 *\li	If this is not the first call to dns_view_setcache() for this
448
 *	view, then previously set cache is detached.
Bob Halley's avatar
Bob Halley committed
449
 */
450

Bob Halley's avatar
Bob Halley committed
451 452
void
dns_view_sethints(dns_view_t *view, dns_db_t *hints);
453
/*%<
Bob Halley's avatar
Bob Halley committed
454 455 456 457
 * Set the view's hints database.
 *
 * Requires:
 *
458
 *\li	'view' is a valid, unfrozen view, whose hints database has not been
Bob Halley's avatar
Bob Halley committed
459 460
 *	set.
 *
461
 *\li	'hints' is a valid zone database.
Bob Halley's avatar
Bob Halley committed
462 463 464
 *
 * Ensures:
 *
465
 * \li    	The hints database of 'view' is 'hints'.
Bob Halley's avatar
Bob Halley committed
466 467
 */

Brian Wellington's avatar
Brian Wellington committed
468 469
void
dns_view_setkeyring(dns_view_t *view, dns_tsig_keyring_t *ring);
470 471
void
dns_view_setdynamickeyring(dns_view_t *view, dns_tsig_keyring_t *ring);
472
/*%<
Brian Wellington's avatar
Brian Wellington committed
473 474 475 476
 * Set the view's static TSIG keys
 *
 * Requires:
 *
477
 *   \li   'view' is a valid, unfrozen view, whose static TSIG keyring has not
Brian Wellington's avatar
Brian Wellington committed
478 479
 *	been set.
 *
480
 *\li      'ring' is a valid TSIG keyring
Brian Wellington's avatar
Brian Wellington committed
481 482 483
 *
 * Ensures:
 *
484
 *\li      The static TSIG keyring of 'view' is 'ring'.
Brian Wellington's avatar
Brian Wellington committed
485 486
 */

487 488 489 490 491 492 493 494 495
void
dns_view_getdynamickeyring(dns_view_t *view, dns_tsig_keyring_t **ringp);
/*%<
 * Return the views dynamic keys.
 *
 *   \li  'view' is a valid, unfrozen view.
 *   \li  'ringp' != NULL && ringp == NULL.
 */

496 497
void
dns_view_setdstport(dns_view_t *view, in_port_t dstport);
498
/*%<
499 500 501 502 503 504
 * Set the view's destination port.  This is the port to
 * which outgoing queries are sent.  The default is 53,
 * the standard DNS port.
 *
 * Requires:
 *
505
 *\li      'view' is a valid view.
506
 *
507
 *\li      'dstport' is a valid TCP/UDP port number.
508 509
 *
 * Ensures:
Francis Dupont's avatar
Francis Dupont committed
510
 *\li	External name servers will be assumed to be listening
511 512 513 514 515
 *	on 'dstport'.  For servers whose address has already
 *	obtained obtained at the time of the call, the view may
 *	continue to use the previously set port until the address
 *	times out from the view's address database.
 */
Brian Wellington's avatar
Brian Wellington committed
516 517


518
isc_result_t
519
dns_view_addzone(dns_view_t *view, dns_zone_t *zone);
520
/*%<
521
 * Add zone 'zone' to 'view'.
Bob Halley's avatar
Bob Halley committed
522 523 524
 *
 * Requires:
 *
525
 *\li	'view' is a valid, unfrozen view.
Bob Halley's avatar
Bob Halley committed
526
 *
527
 *\li	'zone' is a valid zone.
528
 */
529 530 531

void
dns_view_freeze(dns_view_t *view);
532
/*%<
533
 * Freeze view.  No changes can be made to view configuration while frozen.
Bob Halley's avatar
Bob Halley committed
534 535 536
 *
 * Requires:
 *
537
 *\li	'view' is a valid, unfrozen view.
Bob Halley's avatar
Bob Halley committed
538 539 540
 *
 * Ensures:
 *
541
 *\li	'view' is frozen.
Bob Halley's avatar
Bob Halley committed
542 543
 */

544 545 546 547 548 549 550 551 552 553 554 555 556 557 558
void
dns_view_thaw(dns_view_t *view);
/*%<
 * Thaw view.  This allows zones to be added or removed at runtime.  This is
 * NOT thread-safe; the caller MUST have run isc_task_exclusive() prior to
 * thawing the view.
 *
 * Requires:
 *
 *\li	'view' is a valid, frozen view.
 *
 * Ensures:
 *
 *\li	'view' is no longer frozen.
 */
559

Bob Halley's avatar
Bob Halley committed
560
isc_result_t
561
dns_view_find(dns_view_t *view, const dns_name_t *name, dns_rdatatype_t type,
562
	      isc_stdtime_t now, unsigned int options,
563
	      bool use_hints, bool use_static_stub,
564
	      dns_db_t **dbp, dns_dbnode_t **nodep, dns_name_t *foundname,
Bob Halley's avatar
Bob Halley committed
565
	      dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
566
/*%<
567 568
 * Find an rdataset whose owner name is 'name', and whose type is
 * 'type'.
569 570
 * In general, this function first searches view's zone and cache DBs for the
 * best match data against 'name'.  If nothing found there, and if 'use_hints'
571
 * is true, the view's hint DB (if configured) is searched.
572 573
 * If the view is configured with a static-stub zone which gives the longest
 * match for 'name' among the zones, however, the cache DB is not consulted
574
 * unless 'use_static_stub' is false (see below about this argument).
575 576
 *
 * dns_view_find() is a backward compatible version equivalent to
577
 * dns_view_find2() with use_static_stub argument being false.
578 579 580
 *
 * Notes:
 *
581 582
 *\li	See the description of dns_db_find() for information about 'options'.
 *	If the caller sets #DNS_DBFIND_GLUEOK, it must ensure that 'name'
583 584
 *	and 'type' are appropriate for glue retrieval.
 *
585
 *\li	If 'now' is zero, then the current time will be used.
586
 *
587
 *\li	If 'use_hints' is true, and the view has a hints database, then
588
 *	it will be searched last.  If the answer is found in the hints
589 590
 *	database, the result code will be DNS_R_HINT.  If the name is found
 *	in the hints database but not the type, the result code will be
591
 *	#DNS_R_HINTNXRRSET.
592
 *
593
 *\li	If 'use_static_stub' is false and the longest match zone for 'name'
594 595
 *	is a static-stub zone, it's ignored and the cache and/or hints will be
 *	searched.  In the majority of the cases this argument should be
596
 *	false.  The only known usage of this argument being true is
597 598 599 600 601 602 603 604 605 606 607 608 609
 *	if this search is for a "bailiwick" glue A or AAAA RRset that may
 *	best match a static-stub zone.  Consider the following example:
 *	this view is configured with a static-stub zone "example.com",
 *	and an attempt of recursive resolution needs to send a query for the
 *	zone.  In this case it's quite likely that the resolver is trying to
 *	find A/AAAA RRs for the apex name "example.com".  And, to honor the
 *	static-stub configuration it needs to return the glue RRs in the
 *	static-stub zone even if that exact RRs coming from the authoritative
 *	zone has been cached.
 *	In other general cases, the requested data is better to be
 *	authoritative, either locally configured or retrieved from an external
 *	server, and the data in the static-stub zone should better be ignored.
 *
610
 *\li	'foundname' must meet the requirements of dns_db_find().
611
 *
612
 *\li	If 'sigrdataset' is not NULL, and there is a SIG rdataset which
613 614 615 616
 *	covers 'type', then 'sigrdataset' will be bound to it.
 *
 * Requires:
 *
617
 *\li	'view' is a valid, frozen view.
618
 *
619
 *\li	'name' is valid name.
620
 *
621
 *\li	'type' is a valid dns_rdatatype_t, and is not a meta query type
622
 *	except dns_rdatatype_any.
623
 *
624
 *\li	dbp == NULL || *dbp == NULL
625
 *
626
 *\li	nodep == NULL || *nodep == NULL.  If nodep != NULL, dbp != NULL.
627
 *
628
 *\li	'foundname' is a valid name with a dedicated buffer or NULL.
629
 *
630
 *\li	'rdataset' is a valid, disassociated rdataset.
631
 *
632
 *\li	'sigrdataset' is NULL, or is a valid, disassociated rdataset.
633 634 635
 *
 * Ensures:
 *
636
 *\li	In successful cases, 'rdataset', and possibly 'sigrdataset', are
637 638
 *	bound to the found data.
 *
639
 *\li	If dbp != NULL, it points to the database containing the data.
640
 *
641
 *\li	If nodep != NULL, it points to the database node containing the data.
642
 *
643
 *\li	If foundname != NULL, it contains the full name of the found data.
644
 *
645 646
 * Returns:
 *
647 648
 *\li	Any result that dns_db_find() can return, with the exception of
 *	#DNS_R_DELEGATION.
649 650 651
 */

isc_result_t
652 653
dns_view_simplefind(dns_view_t *view, const dns_name_t *name,
		    dns_rdatatype_t type, isc_stdtime_t now,
654
		    unsigned int options, bool use_hints,
655
		    dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
656
/*%<
Bob Halley's avatar
Bob Halley committed
657 658 659 660 661
 * Find an rdataset whose owner name is 'name', and whose type is
 * 'type'.
 *
 * Notes:
 *
662
 *\li	This routine is appropriate for simple, exact-match queries of the
Bob Halley's avatar
Bob Halley committed
663 664
 *	view.  'name' must be a canonical name; there is no DNAME or CNAME
 *	processing.
Bob Halley's avatar
Bob Halley committed
665
 *
666
 *\li	See the description of dns_db_find() for information about 'options'.
Bob Halley's avatar
Bob Halley committed
667 668 669
 *	If the caller sets DNS_DBFIND_GLUEOK, it must ensure that 'name'
 *	and 'type' are appropriate for glue retrieval.
 *
670
 *\li	If 'now' is zero, then the current time will be used.
Bob Halley's avatar
Bob Halley committed
671
 *
672
 *\li	If 'use_hints' is true, and the view has a hints database, then
Bob Halley's avatar
Bob Halley committed
673
 *	it will be searched last.  If the answer is found in the hints
674 675 676
 *	database, the result code will be DNS_R_HINT.  If the name is found
 *	in the hints database but not the type, the result code will be
 *	DNS_R_HINTNXRRSET.
Bob Halley's avatar
Bob Halley committed
677
 *
678
 *\li	If 'sigrdataset' is not NULL, and there is a SIG rdataset which
Bob Halley's avatar
Bob Halley committed
679 680 681 682
 *	covers 'type', then 'sigrdataset' will be bound to it.
 *
 * Requires:
 *
683
 *\li	'view' is a valid, frozen view.
Bob Halley's avatar
Bob Halley committed
684
 *
685
 *\li	'name' is valid name.
Bob Halley's avatar
Bob Halley committed
686
 *
687
 *\li	'type' is a valid dns_rdatatype_t, and is not a meta query type
688
 *	(e.g. dns_rdatatype_any), or dns_rdatatype_rrsig.
Bob Halley's avatar
Bob Halley committed
689
 *
690
 *\li	'rdataset' is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
691
 *
692
 *\li	'sigrdataset' is NULL, or is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
693 694 695
 *
 * Ensures:
 *
696
 *\li	In successful cases, 'rdataset', and possibly 'sigrdataset', are
697
 *	bound to the found data.
Bob Halley's avatar
Bob Halley committed
698 699 700
 *
 * Returns:
 *
701 702 703 704 705 706 707 708
 *\li	#ISC_R_SUCCESS			Success; result is desired type.
 *\li	DNS_R_GLUE			Success; result is glue.
 *\li	DNS_R_HINT			Success; result is a hint.
 *\li	DNS_R_NCACHENXDOMAIN		Success; result is a ncache entry.
 *\li	DNS_R_NCACHENXRRSET		Success; result is a ncache entry.
 *\li	DNS_R_NXDOMAIN			The name does not exist.
 *\li	DNS_R_NXRRSET			The rrset does not exist.
 *\li	#ISC_R_NOTFOUND			No matching data found,
709
 *					or an error occurred.
Bob Halley's avatar
Bob Halley committed
710
 */
711

Bob Halley's avatar
Bob Halley committed
712
isc_result_t
713
dns_view_findzonecut(dns_view_t *view, const dns_name_t *name,
714
		     dns_name_t *fname, dns_name_t *dcname, isc_stdtime_t now,
715
		     unsigned int options,
716
		     bool use_hints, bool use_cache,
Bob Halley's avatar
Bob Halley committed
717
		     dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
718
/*%<
Bob Halley's avatar
Bob Halley committed
719 720
 * Find the best known zonecut containing 'name'.
 *
Andreas Gustafsson's avatar
Andreas Gustafsson committed
721 722 723
 * This uses local authority, cache, and optionally hints data.
 * No external queries are performed.
 *
Bob Halley's avatar
Bob Halley committed
724 725
 * Notes:
 *
726
 *\li	If 'now' is zero, then the current time will be used.
Bob Halley's avatar
Bob Halley committed
727
 *
728
 *\li	If 'use_hints' is true, and the view has a hints database, then
Bob Halley's avatar
Bob Halley committed
729 730
 *	it will be searched last.
 *
731
 *\li	If 'use_cache' is true, and the view has a cache, then it will be
732 733
 *	searched.
 *
734
 *\li	If 'sigrdataset' is not NULL, and there is a SIG rdataset which
Bob Halley's avatar
Bob Halley committed
735 736
 *	covers 'type', then 'sigrdataset' will be bound to it.
 *
737
 *\li	If the DNS_DBFIND_NOEXACT option is set, then the zonecut returned
738
 *	(if any) will be the deepest known ancestor of 'name'.
Andreas Gustafsson's avatar
Andreas Gustafsson committed
739
 *
740 741
 *\li	If dcname is not NULL the deepest cached name is copied to it.
 *
Bob Halley's avatar
Bob Halley committed
742 743
 * Requires:
 *
744
 *\li	'view' is a valid, frozen view.
Bob Halley's avatar
Bob Halley committed
745
 *
746
 *\li	'name' is valid name.
Bob Halley's avatar
Bob Halley committed
747
 *
748
 *\li	'rdataset' is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
749
 *
750
 *\li	'sigrdataset' is NULL, or is a valid, disassociated rdataset.
Bob Halley's avatar
Bob Halley committed
751 752 753
 *
 * Returns:
 *
754
 *\li	#ISC_R_SUCCESS				Success.
Bob Halley's avatar
Bob Halley committed
755
 *
756
 *\li	Many other results are possible.
Bob Halley's avatar
Bob Halley committed
757 758
 */

759 760 761
isc_result_t
dns_viewlist_find(dns_viewlist_t *list, const char *name,
		  dns_rdataclass_t rdclass, dns_view_t **viewp);
762
/*%<
763 764 765 766 767
 * Search for a view with name 'name' and class 'rdclass' in 'list'.
 * If found, '*viewp' is (strongly) attached to it.
 *
 * Requires:
 *
768
 *\li	'viewp' points to a NULL dns_view_t *.
769 770 771
 *
 * Returns:
 *
772 773
 *\li	#ISC_R_SUCCESS		A matching view was found.
 *\li	#ISC_R_NOTFOUND		No matching view was found.
774 775
 */

776
isc_result_t
777
dns_viewlist_findzone(dns_viewlist_t *list, const dns_name_t *name,
778
		      bool allclasses, dns_rdataclass_t rdclass,
779
		      dns_zone_t **zonep);
780 781 782 783 784 785 786 787

/*%<
 * Search zone with 'name' in view with 'rdclass' in viewlist 'list'
 * If found, zone is returned in *zonep. If allclasses is set rdclass is ignored
 *
 * Returns:
 *\li	#ISC_R_SUCCESS          A matching zone was found.
 *\li	#ISC_R_NOTFOUND         No matching zone was found.
788
 *\li	#ISC_R_MULTIPLE         Multiple zones with the same name were found.
789 790
 */

791
isc_result_t
792 793
dns_view_findzone(dns_view_t *view, const dns_name_t *name,
		  dns_zone_t **zonep);
794
/*%<