db.h 44.4 KB
Newer Older
Bob Halley's avatar
Bob Halley committed
1
/*
2
 * Copyright (C) 2004-2009, 2011-2016  Internet Systems Consortium, Inc. ("ISC")
Mark Andrews's avatar
Mark Andrews committed
3
 * Copyright (C) 1999-2003  Internet Software Consortium.
4
 *
Automatic Updater's avatar
Automatic Updater committed
5
 * Permission to use, copy, modify, and/or distribute this software for any
Bob Halley's avatar
Bob Halley committed
6 7
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
8
 *
Mark Andrews's avatar
Mark Andrews committed
9 10 11 12 13 14 15
 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
Bob Halley's avatar
Bob Halley committed
16 17
 */

18
/* $Id$ */
David Lawrence's avatar
David Lawrence committed
19

Bob Halley's avatar
Bob Halley committed
20 21 22 23 24 25 26
#ifndef DNS_DB_H
#define DNS_DB_H 1

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

27
/*! \file dns/db.h
28
 * \brief
Bob Halley's avatar
Bob Halley committed
29
 * The DNS DB interface allows named rdatasets to be stored and retrieved.
Bob Halley's avatar
Bob Halley committed
30 31 32 33
 *
 * The dns_db_t type is like a "virtual class".  To actually use
 * DBs, an implementation of the class is required.
 *
34
 * XXX more XXX
Bob Halley's avatar
Bob Halley committed
35 36
 *
 * MP:
Mark Andrews's avatar
Mark Andrews committed
37
 * \li	The module ensures appropriate synchronization of data structures it
Bob Halley's avatar
Bob Halley committed
38
 *	creates and manipulates.
Bob Halley's avatar
Bob Halley committed
39 40
 *
 * Reliability:
Mark Andrews's avatar
Mark Andrews committed
41
 * \li	No anticipated impact.
Bob Halley's avatar
Bob Halley committed
42 43
 *
 * Resources:
Mark Andrews's avatar
Mark Andrews committed
44
 * \li	TBS
Bob Halley's avatar
Bob Halley committed
45 46
 *
 * Security:
Mark Andrews's avatar
Mark Andrews committed
47
 * \li	No anticipated impact.
Bob Halley's avatar
Bob Halley committed
48 49
 *
 * Standards:
Mark Andrews's avatar
Mark Andrews committed
50
 * \li	None.
Bob Halley's avatar
Bob Halley committed
51 52
 */

Bob Halley's avatar
Bob Halley committed
53 54 55 56
/*****
 ***** Imports
 *****/

57
#include <isc/lang.h>
58
#include <isc/magic.h>
59
#include <isc/ondestroy.h>
60
#include <isc/stats.h>
61
#include <isc/stdtime.h>
Bob Halley's avatar
Bob Halley committed
62

63
#include <dns/clientinfo.h>
64
#include <dns/fixedname.h>
Bob Halley's avatar
Bob Halley committed
65
#include <dns/name.h>
66 67
#include <dns/rdata.h>
#include <dns/rdataset.h>
68
#include <dns/rpz.h>
69
#include <dns/types.h>
Bob Halley's avatar
Bob Halley committed
70

71 72
ISC_LANG_BEGINDECLS

Bob Halley's avatar
Bob Halley committed
73 74 75 76
/*****
 ***** Types
 *****/

Bob Halley's avatar
Bob Halley committed
77 78 79
typedef struct dns_dbmethods {
	void		(*attach)(dns_db_t *source, dns_db_t **targetp);
	void		(*detach)(dns_db_t **dbp);
80 81
	isc_result_t	(*beginload)(dns_db_t *db,
				     dns_rdatacallbacks_t *callbacks);
Tinderbox User's avatar
Tinderbox User committed
82
	isc_result_t	(*endload)(dns_db_t *db,
83 84 85
				     dns_rdatacallbacks_t *callbacks);
	isc_result_t	(*serialize)(dns_db_t *db,
				     dns_dbversion_t *version, FILE *file);
86
	isc_result_t	(*dump)(dns_db_t *db, dns_dbversion_t *version,
87 88
				const char *filename,
				dns_masterformat_t masterformat);
Bob Halley's avatar
Bob Halley committed
89 90
	void		(*currentversion)(dns_db_t *db,
					  dns_dbversion_t **versionp);
91
	isc_result_t	(*newversion)(dns_db_t *db,
Bob Halley's avatar
Bob Halley committed
92
				      dns_dbversion_t **versionp);
Bob Halley's avatar
Bob Halley committed
93 94
	void		(*attachversion)(dns_db_t *db, dns_dbversion_t *source,
					 dns_dbversion_t **targetp);
Bob Halley's avatar
Bob Halley committed
95
	void		(*closeversion)(dns_db_t *db,
Bob Halley's avatar
Bob Halley committed
96 97
					dns_dbversion_t **versionp,
					isc_boolean_t commit);
98
	isc_result_t	(*findnode)(dns_db_t *db, dns_name_t *name,
Bob Halley's avatar
Bob Halley committed
99 100
				    isc_boolean_t create,
				    dns_dbnode_t **nodep);
101
	isc_result_t	(*find)(dns_db_t *db, dns_name_t *name,
Bob Halley's avatar
Bob Halley committed
102 103
				dns_dbversion_t *version,
				dns_rdatatype_t type, unsigned int options,
104
				isc_stdtime_t now,
Bob Halley's avatar
Bob Halley committed
105
				dns_dbnode_t **nodep, dns_name_t *foundname,
Bob Halley's avatar
Bob Halley committed
106 107
				dns_rdataset_t *rdataset,
				dns_rdataset_t *sigrdataset);
108
	isc_result_t	(*findzonecut)(dns_db_t *db, dns_name_t *name,
Bob Halley's avatar
Bob Halley committed
109 110 111 112 113
				       unsigned int options, isc_stdtime_t now,
				       dns_dbnode_t **nodep,
				       dns_name_t *foundname,
				       dns_rdataset_t *rdataset,
				       dns_rdataset_t *sigrdataset);
Bob Halley's avatar
Bob Halley committed
114 115 116 117 118
	void		(*attachnode)(dns_db_t *db,
				      dns_dbnode_t *source,
				      dns_dbnode_t **targetp);
	void		(*detachnode)(dns_db_t *db,
				      dns_dbnode_t **targetp);
119
	isc_result_t	(*expirenode)(dns_db_t *db, dns_dbnode_t *node,
Bob Halley's avatar
Bob Halley committed
120
				      isc_stdtime_t now);
Bob Halley's avatar
Bob Halley committed
121 122
	void		(*printnode)(dns_db_t *db, dns_dbnode_t *node,
				     FILE *out);
123
	isc_result_t 	(*createiterator)(dns_db_t *db, unsigned int options,
Bob Halley's avatar
Bob Halley committed
124
					  dns_dbiterator_t **iteratorp);
125
	isc_result_t	(*findrdataset)(dns_db_t *db, dns_dbnode_t *node,
Bob Halley's avatar
Bob Halley committed
126 127
					dns_dbversion_t *version,
					dns_rdatatype_t type,
Bob Halley's avatar
Bob Halley committed
128
					dns_rdatatype_t covers,
129
					isc_stdtime_t now,
Bob Halley's avatar
Bob Halley committed
130 131
					dns_rdataset_t *rdataset,
					dns_rdataset_t *sigrdataset);
132
	isc_result_t	(*allrdatasets)(dns_db_t *db, dns_dbnode_t *node,
Bob Halley's avatar
Bob Halley committed
133
					dns_dbversion_t *version,
134
					isc_stdtime_t now,
Bob Halley's avatar
Bob Halley committed
135
					dns_rdatasetiter_t **iteratorp);
136
	isc_result_t	(*addrdataset)(dns_db_t *db, dns_dbnode_t *node,
Bob Halley's avatar
Bob Halley committed
137
				       dns_dbversion_t *version,
138
				       isc_stdtime_t now,
139
				       dns_rdataset_t *rdataset,
Bob Halley's avatar
Bob Halley committed
140
				       unsigned int options,
141
				       dns_rdataset_t *addedrdataset);
142
	isc_result_t	(*subtractrdataset)(dns_db_t *db, dns_dbnode_t *node,
Bob Halley's avatar
Bob Halley committed
143 144
					    dns_dbversion_t *version,
					    dns_rdataset_t *rdataset,
145
					    unsigned int options,
Bob Halley's avatar
Bob Halley committed
146
					    dns_rdataset_t *newrdataset);
147
	isc_result_t	(*deleterdataset)(dns_db_t *db, dns_dbnode_t *node,
Bob Halley's avatar
Bob Halley committed
148
					  dns_dbversion_t *version,
149 150
					  dns_rdatatype_t type,
					  dns_rdatatype_t covers);
Bob Halley's avatar
Bob Halley committed
151
	isc_boolean_t	(*issecure)(dns_db_t *db);
152
	unsigned int	(*nodecount)(dns_db_t *db);
153
	isc_boolean_t	(*ispersistent)(dns_db_t *db);
Mark Andrews's avatar
Mark Andrews committed
154
	void		(*overmem)(dns_db_t *db, isc_boolean_t overmem);
155
	void		(*settask)(dns_db_t *db, isc_task_t *);
156
	isc_result_t	(*getoriginnode)(dns_db_t *db, dns_dbnode_t **nodep);
157
	void		(*transfernode)(dns_db_t *db, dns_dbnode_t **sourcep,
158
					dns_dbnode_t **targetp);
159 160 161 162 163 164 165 166 167 168
	isc_result_t    (*getnsec3parameters)(dns_db_t *db,
					      dns_dbversion_t *version,
					      dns_hash_t *hash,
					      isc_uint8_t *flags,
					      isc_uint16_t *iterations,
					      unsigned char *salt,
					      size_t *salt_len);
	isc_result_t    (*findnsec3node)(dns_db_t *db, dns_name_t *name,
					 isc_boolean_t create,
					 dns_dbnode_t **nodep);
169 170 171 172 173 174 175 176 177
	isc_result_t	(*setsigningtime)(dns_db_t *db,
					  dns_rdataset_t *rdataset,
					  isc_stdtime_t resign);
	isc_result_t	(*getsigningtime)(dns_db_t *db,
					  dns_rdataset_t *rdataset,
					  dns_name_t *name);
	void		(*resigned)(dns_db_t *db, dns_rdataset_t *rdataset,
					   dns_dbversion_t *version);
	isc_boolean_t	(*isdnssec)(dns_db_t *db);
178
	dns_stats_t	*(*getrrsetstats)(dns_db_t *db);
179 180 181
	void		(*rpz_attach)(dns_db_t *db, dns_rpz_zones_t *rpzs,
				      dns_rpz_num_t rpz_num);
	isc_result_t	(*rpz_ready)(dns_db_t *db);
182 183 184 185 186 187 188 189 190 191 192 193 194 195
	isc_result_t	(*findnodeext)(dns_db_t *db, dns_name_t *name,
				     isc_boolean_t create,
				     dns_clientinfomethods_t *methods,
				     dns_clientinfo_t *clientinfo,
				     dns_dbnode_t **nodep);
	isc_result_t	(*findext)(dns_db_t *db, dns_name_t *name,
				   dns_dbversion_t *version,
				   dns_rdatatype_t type, unsigned int options,
				   isc_stdtime_t now,
				   dns_dbnode_t **nodep, dns_name_t *foundname,
				   dns_clientinfomethods_t *methods,
				   dns_clientinfo_t *clientinfo,
				   dns_rdataset_t *rdataset,
				   dns_rdataset_t *sigrdataset);
196
	isc_result_t	(*setcachestats)(dns_db_t *db, isc_stats_t *stats);
197
	size_t		(*hashsize)(dns_db_t *db);
Bob Halley's avatar
Bob Halley committed
198 199
} dns_dbmethods_t;

200 201 202 203 204
typedef isc_result_t
(*dns_dbcreatefunc_t)(isc_mem_t *mctx, dns_name_t *name,
		      dns_dbtype_t type, dns_rdataclass_t rdclass,
		      unsigned int argc, char *argv[], void *driverarg,
		      dns_db_t **dbp);
Automatic Updater's avatar
Automatic Updater committed
205

206 207 208
typedef isc_result_t
(*dns_dbupdate_callback_t)(dns_db_t *db, void *fn_arg);

209
#define DNS_DB_MAGIC		ISC_MAGIC('D','N','S','D')
210
#define DNS_DB_VALID(db)	ISC_MAGIC_VALID(db, DNS_DB_MAGIC)
Bob Halley's avatar
Bob Halley committed
211

212
/*%
Bob Halley's avatar
Bob Halley committed
213
 * This structure is actually just the common prefix of a DNS db
Bob Halley's avatar
Bob Halley committed
214
 * implementation's version of a dns_db_t.
215
 * \brief
Bob Halley's avatar
Bob Halley committed
216 217
 * Direct use of this structure by clients is forbidden.  DB implementations
 * may change the structure.  'magic' must be DNS_DB_MAGIC for any of the
Bob Halley's avatar
Bob Halley committed
218 219
 * dns_db_ routines to work.  DB implementations must maintain all DB
 * invariants.
Bob Halley's avatar
Bob Halley committed
220 221
 */
struct dns_db {
222 223 224 225 226 227 228 229 230
	unsigned int				magic;
	unsigned int				impmagic;
	dns_dbmethods_t *			methods;
	isc_uint16_t				attributes;
	dns_rdataclass_t			rdclass;
	dns_name_t				origin;
	isc_ondestroy_t				ondest;
	isc_mem_t *				mctx;
	ISC_LIST(dns_dbonupdatelistener_t)	update_listeners;
Bob Halley's avatar
Bob Halley committed
231 232
};

Bob Halley's avatar
Bob Halley committed
233
#define DNS_DBATTR_CACHE		0x01
234
#define DNS_DBATTR_STUB			0x02
Bob Halley's avatar
Bob Halley committed
235

236 237 238 239 240 241
struct dns_dbonupdatelistener {
	dns_dbupdate_callback_t			onupdate;
	void *					onupdate_arg;
	ISC_LINK(dns_dbonupdatelistener_t)	link;
};

242 243
/*@{*/
/*%
Bob Halley's avatar
Bob Halley committed
244 245
 * Options that can be specified for dns_db_find().
 */
246 247 248 249 250 251 252 253 254
#define DNS_DBFIND_GLUEOK		0x0001
#define DNS_DBFIND_VALIDATEGLUE		0x0002
#define DNS_DBFIND_NOWILD		0x0004
#define DNS_DBFIND_PENDINGOK		0x0008
#define DNS_DBFIND_NOEXACT		0x0010
#define DNS_DBFIND_FORCENSEC		0x0020
#define DNS_DBFIND_COVERINGNSEC		0x0040
#define DNS_DBFIND_FORCENSEC3		0x0080
#define DNS_DBFIND_ADDITIONALOK		0x0100
255
#define DNS_DBFIND_NOZONECUT		0x0200
256
/*@}*/
Bob Halley's avatar
Bob Halley committed
257

258 259
/*@{*/
/*%
Bob Halley's avatar
Bob Halley committed
260
 * Options that can be specified for dns_db_addrdataset().
Bob Halley's avatar
Bob Halley committed
261
 */
Bob Halley's avatar
Bob Halley committed
262 263
#define DNS_DBADD_MERGE			0x01
#define DNS_DBADD_FORCE			0x02
264
#define DNS_DBADD_EXACT			0x04
265
#define DNS_DBADD_EXACTTTL		0x08
266
#define DNS_DBADD_PREFETCH		0x10
267
/*@}*/
Bob Halley's avatar
Bob Halley committed
268

269
/*%
270 271 272
 * Options that can be specified for dns_db_subtractrdataset().
 */
#define DNS_DBSUB_EXACT			0x01
273
#define DNS_DBSUB_WANTOLD		0x02
274

275 276 277 278 279 280 281 282 283
/*@{*/
/*%
 * Iterator options
 */
#define DNS_DB_RELATIVENAMES	0x1
#define DNS_DB_NSEC3ONLY	0x2
#define DNS_DB_NONSEC3		0x4
/*@}*/

Bob Halley's avatar
Bob Halley committed
284 285 286 287 288 289 290 291
/*****
 ***** Methods
 *****/

/***
 *** Basic DB Methods
 ***/

292
isc_result_t
David Lawrence's avatar
David Lawrence committed
293
dns_db_create(isc_mem_t *mctx, const char *db_type, dns_name_t *origin,
294
	      dns_dbtype_t type, dns_rdataclass_t rdclass,
Bob Halley's avatar
Bob Halley committed
295
	      unsigned int argc, char *argv[], dns_db_t **dbp);
296
/*%<
Bob Halley's avatar
Bob Halley committed
297 298 299
 * Create a new database using implementation 'db_type'.
 *
 * Notes:
Mark Andrews's avatar
Mark Andrews committed
300
 * \li	All names in the database must be subdomains of 'origin' and in class
David Lawrence's avatar
David Lawrence committed
301 302
 *	'rdclass'.  The database makes its own copy of the origin, so the
 *	caller may do whatever they like with 'origin' and its storage once the
Bob Halley's avatar
Bob Halley committed
303 304
 *	call returns.
 *
Mark Andrews's avatar
Mark Andrews committed
305
 * \li	DB implementation-specific parameters are passed using argc and argv.
Bob Halley's avatar
Bob Halley committed
306 307 308
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
309
 * \li	dbp != NULL and *dbp == NULL
Bob Halley's avatar
Bob Halley committed
310
 *
Mark Andrews's avatar
Mark Andrews committed
311
 * \li	'origin' is a valid absolute domain name.
Bob Halley's avatar
Bob Halley committed
312
 *
Mark Andrews's avatar
Mark Andrews committed
313
 * \li	mctx is a valid memory context
Bob Halley's avatar
Bob Halley committed
314 315 316
 *
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
317
 * \li	A copy of 'origin' has been made for the databases use, and the
Bob Halley's avatar
Bob Halley committed
318 319 320 321 322
 *	caller is free to do whatever they want with the name and storage
 *	associated with 'origin'.
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
323 324 325
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOMEMORY
 * \li	#ISC_R_NOTFOUND				db_type not found
Bob Halley's avatar
Bob Halley committed
326
 *
Mark Andrews's avatar
Mark Andrews committed
327
 * \li	Many other errors are possible, depending on what db_type was
Bob Halley's avatar
Bob Halley committed
328 329
 *	specified.
 */
Bob Halley's avatar
Bob Halley committed
330 331 332

void
dns_db_attach(dns_db_t *source, dns_db_t **targetp);
333
/*%<
Bob Halley's avatar
Bob Halley committed
334 335 336 337
 * Attach *targetp to source.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
338
 * \li	'source' is a valid database.
Bob Halley's avatar
Bob Halley committed
339
 *
Mark Andrews's avatar
Mark Andrews committed
340
 * \li	'targetp' points to a NULL dns_db_t *.
Bob Halley's avatar
Bob Halley committed
341 342 343
 *
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
344
 * \li	*targetp is attached to source.
Bob Halley's avatar
Bob Halley committed
345
 */
Bob Halley's avatar
Bob Halley committed
346 347 348

void
dns_db_detach(dns_db_t **dbp);
349
/*%<
Bob Halley's avatar
Bob Halley committed
350 351 352 353
 * Detach *dbp from its database.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
354
 * \li	'dbp' points to a valid database.
Bob Halley's avatar
Bob Halley committed
355 356 357
 *
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
358
 * \li	*dbp is NULL.
Bob Halley's avatar
Bob Halley committed
359
 *
Mark Andrews's avatar
Mark Andrews committed
360
 * \li	If '*dbp' is the last reference to the database,
361
 *		all resources used by the database will be freed
Bob Halley's avatar
Bob Halley committed
362
 */
Bob Halley's avatar
Bob Halley committed
363

364 365
isc_result_t
dns_db_ondestroy(dns_db_t *db, isc_task_t *task, isc_event_t **eventp);
366
/*%<
367 368 369
 * Causes 'eventp' to be sent to be sent to 'task' when the database is
 * destroyed.
 *
Mark Andrews's avatar
Mark Andrews committed
370
 * Note; ownership of the eventp is taken from the caller (and *eventp is
371 372 373 374
 * set to NULL). The sender field of the event is set to 'db' before it is
 * sent to the task.
 */

Bob Halley's avatar
Bob Halley committed
375 376
isc_boolean_t
dns_db_iscache(dns_db_t *db);
377
/*%<
Bob Halley's avatar
Bob Halley committed
378 379 380 381
 * Does 'db' have cache semantics?
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
382
 * \li	'db' is a valid database.
Bob Halley's avatar
Bob Halley committed
383 384
 *
 * Returns:
Mark Andrews's avatar
Mark Andrews committed
385 386
 * \li	#ISC_TRUE	'db' has cache semantics
 * \li	#ISC_FALSE	otherwise
Bob Halley's avatar
Bob Halley committed
387
 */
Bob Halley's avatar
Bob Halley committed
388 389 390

isc_boolean_t
dns_db_iszone(dns_db_t *db);
391
/*%<
Bob Halley's avatar
Bob Halley committed
392 393
 * Does 'db' have zone semantics?
 *
394 395
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
396
 * \li	'db' is a valid database.
397 398
 *
 * Returns:
Mark Andrews's avatar
Mark Andrews committed
399 400
 * \li	#ISC_TRUE	'db' has zone semantics
 * \li	#ISC_FALSE	otherwise
401 402 403 404
 */

isc_boolean_t
dns_db_isstub(dns_db_t *db);
405
/*%<
406
 * Does 'db' have stub semantics?
Bob Halley's avatar
Bob Halley committed
407 408 409
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
410
 * \li	'db' is a valid database.
Bob Halley's avatar
Bob Halley committed
411 412
 *
 * Returns:
Mark Andrews's avatar
Mark Andrews committed
413 414
 * \li	#ISC_TRUE	'db' has zone semantics
 * \li	#ISC_FALSE	otherwise
Bob Halley's avatar
Bob Halley committed
415
 */
Bob Halley's avatar
Bob Halley committed
416

Bob Halley's avatar
Bob Halley committed
417 418
isc_boolean_t
dns_db_issecure(dns_db_t *db);
419
/*%<
Bob Halley's avatar
Bob Halley committed
420 421 422 423
 * Is 'db' secure?
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
424
 * \li	'db' is a valid database with zone semantics.
Bob Halley's avatar
Bob Halley committed
425 426
 *
 * Returns:
Mark Andrews's avatar
Mark Andrews committed
427 428
 * \li	#ISC_TRUE	'db' is secure.
 * \li	#ISC_FALSE	'db' is not secure.
Bob Halley's avatar
Bob Halley committed
429 430
 */

431 432 433 434 435 436 437 438 439 440 441 442 443 444
isc_boolean_t
dns_db_isdnssec(dns_db_t *db);
/*%<
 * Is 'db' secure or partially secure?
 *
 * Requires:
 *
 * \li	'db' is a valid database with zone semantics.
 *
 * Returns:
 * \li	#ISC_TRUE	'db' is secure or is partially.
 * \li	#ISC_FALSE	'db' is not secure.
 */

Bob Halley's avatar
Bob Halley committed
445 446
dns_name_t *
dns_db_origin(dns_db_t *db);
447
/*%<
Bob Halley's avatar
Bob Halley committed
448 449 450 451 452 453
 * The origin of the database.
 *
 * Note: caller must not try to change this name.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
454
 * \li	'db' is a valid database.
Bob Halley's avatar
Bob Halley committed
455 456 457
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
458
 * \li	The origin of the database.
Bob Halley's avatar
Bob Halley committed
459
 */
Bob Halley's avatar
Bob Halley committed
460 461 462

dns_rdataclass_t
dns_db_class(dns_db_t *db);
463
/*%<
Bob Halley's avatar
Bob Halley committed
464 465 466 467
 * The class of the database.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
468
 * \li	'db' is a valid database.
Bob Halley's avatar
Bob Halley committed
469 470 471
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
472
 * \li	The class of the database.
Bob Halley's avatar
Bob Halley committed
473
 */
Bob Halley's avatar
Bob Halley committed
474

475
isc_result_t
476
dns_db_beginload(dns_db_t *db, dns_rdatacallbacks_t *callbacks);
477
/*%<
Bob Halley's avatar
Bob Halley committed
478 479 480 481
 * Begin loading 'db'.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
482
 * \li	'db' is a valid database.
Bob Halley's avatar
Bob Halley committed
483
 *
Mark Andrews's avatar
Mark Andrews committed
484
 * \li	This is the first attempt to load 'db'.
Bob Halley's avatar
Bob Halley committed
485
 *
486 487
 * \li  'callbacks' is a pointer to an initialized dns_rdatacallbacks_t
 *       structure.
Bob Halley's avatar
Bob Halley committed
488 489 490
 *
 * Ensures:
 *
491 492 493
 * \li	On success, callbacks->add will be a valid dns_addrdatasetfunc_t
 *      suitable for loading records into 'db' from a raw or text zone
 *      file. callbacks->add_private will be a valid DB load context
Tinderbox User's avatar
Tinderbox User committed
494
 *      which should be used as 'arg' when callbacks->add is called.
495
 *      callbacks->deserialize will be a valid dns_deserialize_func_t
Evan Hunt's avatar
Evan Hunt committed
496
 *      suitable for loading 'db' from a map format zone file.
Bob Halley's avatar
Bob Halley committed
497 498 499
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
500 501
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOMEMORY
Bob Halley's avatar
Bob Halley committed
502
 *
Mark Andrews's avatar
Mark Andrews committed
503
 * \li	Other results are possible, depending upon the database
Bob Halley's avatar
Bob Halley committed
504 505 506
 *	implementation used, syntax errors in the master file, etc.
 */

507
isc_result_t
508
dns_db_endload(dns_db_t *db, dns_rdatacallbacks_t *callbacks);
509
/*%<
Bob Halley's avatar
Bob Halley committed
510 511 512 513
 * Finish loading 'db'.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
514
 * \li	'db' is a valid database that is being loaded.
Bob Halley's avatar
Bob Halley committed
515
 *
516 517 518
 * \li	'callbacks' is a valid dns_rdatacallbacks_t structure.
 *
 * \li	callbacks->add_private is not NULL and is a valid database load context.
Bob Halley's avatar
Bob Halley committed
519 520 521
 *
 * Ensures:
 *
522
 * \li	'callbacks' is returned to its state prior to calling dns_db_beginload()
Bob Halley's avatar
Bob Halley committed
523 524 525
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
526 527
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOMEMORY
Bob Halley's avatar
Bob Halley committed
528
 *
Mark Andrews's avatar
Mark Andrews committed
529
 * \li	Other results are possible, depending upon the database
Bob Halley's avatar
Bob Halley committed
530 531 532
 *	implementation used, syntax errors in the master file, etc.
 */

533
isc_result_t
Bob Halley's avatar
Bob Halley committed
534
dns_db_load(dns_db_t *db, const char *filename);
535 536 537

isc_result_t
dns_db_load2(dns_db_t *db, const char *filename, dns_masterformat_t format);
538 539 540

isc_result_t
dns_db_load3(dns_db_t *db, const char *filename, dns_masterformat_t format,
Automatic Updater's avatar
Automatic Updater committed
541
	     unsigned int options);
542
/*%<
Bob Halley's avatar
Bob Halley committed
543 544
 * Load master file 'filename' into 'db'.
 *
Bob Halley's avatar
Bob Halley committed
545
 * Notes:
Mark Andrews's avatar
Mark Andrews committed
546
 * \li	This routine is equivalent to calling
Bob Halley's avatar
Bob Halley committed
547
 *
548
 *\code
Bob Halley's avatar
Bob Halley committed
549
 *		dns_db_beginload();
Bob Halley's avatar
Bob Halley committed
550
 *		dns_master_loadfile();
Bob Halley's avatar
Bob Halley committed
551
 *		dns_db_endload();
552
 *\endcode
Bob Halley's avatar
Bob Halley committed
553
 *
Bob Halley's avatar
Bob Halley committed
554 555
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
556
 * \li	'db' is a valid database.
Bob Halley's avatar
Bob Halley committed
557
 *
Mark Andrews's avatar
Mark Andrews committed
558
 * \li	This is the first attempt to load 'db'.
Bob Halley's avatar
Bob Halley committed
559 560 561
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
562 563
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOMEMORY
Bob Halley's avatar
Bob Halley committed
564
 *
Mark Andrews's avatar
Mark Andrews committed
565
 * \li	Other results are possible, depending upon the database
Bob Halley's avatar
Bob Halley committed
566 567 568
 *	implementation used, syntax errors in the master file, etc.
 */

Tinderbox User's avatar
Tinderbox User committed
569
isc_result_t
570 571
dns_db_serialize(dns_db_t *db, dns_dbversion_t *version, FILE *rbtfile);
/*%<
Evan Hunt's avatar
Evan Hunt committed
572
 * Dump version 'version' of 'db' to map-format file 'filename'.
573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588
 *
 * Requires:
 *
 * \li	'db' is a valid database.
 *
 * \li	'version' is a valid version.
 *
 * Returns:
 *
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOMEMORY
 *
 * \li	Other results are possible, depending upon the database
 *	implementation used, OS file errors, etc.
 */

589
isc_result_t
Bob Halley's avatar
Bob Halley committed
590
dns_db_dump(dns_db_t *db, dns_dbversion_t *version, const char *filename);
591 592 593 594

isc_result_t
dns_db_dump2(dns_db_t *db, dns_dbversion_t *version, const char *filename,
	     dns_masterformat_t masterformat);
595
/*%<
596 597 598 599
 * Dump version 'version' of 'db' to master file 'filename'.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
600
 * \li	'db' is a valid database.
601
 *
Mark Andrews's avatar
Mark Andrews committed
602
 * \li	'version' is a valid version.
603 604 605
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
606 607
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOMEMORY
608
 *
Mark Andrews's avatar
Mark Andrews committed
609
 * \li	Other results are possible, depending upon the database
610 611 612
 *	implementation used, OS file errors, etc.
 */

Bob Halley's avatar
Bob Halley committed
613 614 615
/***
 *** Version Methods
 ***/
Bob Halley's avatar
Bob Halley committed
616

Bob Halley's avatar
Bob Halley committed
617 618
void
dns_db_currentversion(dns_db_t *db, dns_dbversion_t **versionp);
619
/*%<
Bob Halley's avatar
Bob Halley committed
620 621 622 623
 * Open the current version for reading.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
624
 * \li	'db' is a valid database with zone semantics.
Bob Halley's avatar
Bob Halley committed
625
 *
Mark Andrews's avatar
Mark Andrews committed
626
 * \li	versionp != NULL && *verisonp == NULL
Bob Halley's avatar
Bob Halley committed
627 628 629
 *
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
630
 * \li	On success, '*versionp' is attached to the current version.
Bob Halley's avatar
Bob Halley committed
631 632
 *
 */
Bob Halley's avatar
Bob Halley committed
633

634
isc_result_t
Bob Halley's avatar
Bob Halley committed
635
dns_db_newversion(dns_db_t *db, dns_dbversion_t **versionp);
636
/*%<
Bob Halley's avatar
Bob Halley committed
637 638 639 640
 * Open a new version for reading and writing.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
641
 * \li	'db' is a valid database with zone semantics.
Bob Halley's avatar
Bob Halley committed
642
 *
Mark Andrews's avatar
Mark Andrews committed
643
 * \li	versionp != NULL && *verisonp == NULL
Bob Halley's avatar
Bob Halley committed
644 645 646
 *
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
647
 * \li	On success, '*versionp' is attached to the current version.
648
 *
Bob Halley's avatar
Bob Halley committed
649 650
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
651 652
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOMEMORY
Bob Halley's avatar
Bob Halley committed
653
 *
Mark Andrews's avatar
Mark Andrews committed
654
 * \li	Other results are possible, depending upon the database
Bob Halley's avatar
Bob Halley committed
655 656
 *	implementation used.
 */
Bob Halley's avatar
Bob Halley committed
657

Bob Halley's avatar
Bob Halley committed
658 659 660
void
dns_db_attachversion(dns_db_t *db, dns_dbversion_t *source,
		     dns_dbversion_t **targetp);
661
/*%<
Bob Halley's avatar
Bob Halley committed
662 663 664 665
 * Attach '*targetp' to 'source'.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
666
 * \li	'db' is a valid database with zone semantics.
Bob Halley's avatar
Bob Halley committed
667
 *
Mark Andrews's avatar
Mark Andrews committed
668
 * \li	source is a valid open version
Bob Halley's avatar
Bob Halley committed
669
 *
Mark Andrews's avatar
Mark Andrews committed
670
 * \li	targetp != NULL && *targetp == NULL
Bob Halley's avatar
Bob Halley committed
671 672 673
 *
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
674
 * \li	'*targetp' is attached to source.
Bob Halley's avatar
Bob Halley committed
675 676
 */

Bob Halley's avatar
Bob Halley committed
677
void
Bob Halley's avatar
Bob Halley committed
678 679
dns_db_closeversion(dns_db_t *db, dns_dbversion_t **versionp,
		    isc_boolean_t commit);
680
/*%<
Bob Halley's avatar
Bob Halley committed
681 682 683 684
 * Close version '*versionp'.
 *
 * Note: if '*versionp' is a read-write version and 'commit' is ISC_TRUE,
 * then all changes made in the version will take effect, otherwise they
685
 * will be rolled back.  The value of 'commit' is ignored for read-only
Bob Halley's avatar
Bob Halley committed
686 687 688 689
 * versions.
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
690
 * \li	'db' is a valid database with zone semantics.
Bob Halley's avatar
Bob Halley committed
691
 *
Mark Andrews's avatar
Mark Andrews committed
692
 * \li	'*versionp' refers to a valid version.
Bob Halley's avatar
Bob Halley committed
693
 *
Mark Andrews's avatar
Mark Andrews committed
694
 * \li	If committing a writable version, then there must be no other
695 696 697
 *	outstanding references to the version (e.g. an active rdataset
 *	iterator).
 *
Bob Halley's avatar
Bob Halley committed
698 699
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
700
 * \li	*versionp == NULL
Bob Halley's avatar
Bob Halley committed
701
 *
Mark Andrews's avatar
Mark Andrews committed
702
 * \li	If *versionp is a read-write version, and commit is ISC_TRUE, then
703 704 705
 *	the version will become the current version.  If !commit, then all
 *	changes made in the version will be undone, and the version will
 *	not become the current version.
Bob Halley's avatar
Bob Halley committed
706 707
 */

Mark Andrews's avatar
Mark Andrews committed
708
/***
Bob Halley's avatar
Bob Halley committed
709 710
 *** Node Methods
 ***/
Bob Halley's avatar
Bob Halley committed
711

712
isc_result_t
Bob Halley's avatar
Bob Halley committed
713 714
dns_db_findnode(dns_db_t *db, dns_name_t *name, isc_boolean_t create,
		dns_dbnode_t **nodep);
715 716 717 718 719

isc_result_t
dns_db_findnodeext(dns_db_t *db, dns_name_t *name, isc_boolean_t create,
		   dns_clientinfomethods_t *methods,
		   dns_clientinfo_t *clientinfo, dns_dbnode_t **nodep);
720
/*%<
Bob Halley's avatar
Bob Halley committed
721 722
 * Find the node with name 'name'.
 *
723 724 725 726 727
 * dns_db_findnodeext() (findnode extended) also accepts parameters
 * 'methods' and 'clientinfo', which, when provided, enable the database to
 * retreive information about the client from the caller, and modify its
 * response on the basis of that information.
 *
Bob Halley's avatar
Bob Halley committed
728
 * Notes:
Mark Andrews's avatar
Mark Andrews committed
729
 * \li	If 'create' is ISC_TRUE and no node with name 'name' exists, then
Bob Halley's avatar
Bob Halley committed
730
 *	such a node will be created.
Bob Halley's avatar
Bob Halley committed
731
 *
Mark Andrews's avatar
Mark Andrews committed
732
 * \li	This routine is for finding or creating a node with the specified
Bob Halley's avatar
Bob Halley committed
733 734 735
 *	name.  There are no partial matches.  It is not suitable for use
 *	in building responses to ordinary DNS queries; clients which wish
 *	to do that should use dns_db_find() instead.
Bob Halley's avatar
Bob Halley committed
736 737 738
 *
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
739
 * \li	'db' is a valid database.
Bob Halley's avatar
Bob Halley committed
740
 *
Mark Andrews's avatar
Mark Andrews committed
741
 * \li	'name' is a valid, non-empty, absolute name.
Bob Halley's avatar
Bob Halley committed
742
 *
Mark Andrews's avatar
Mark Andrews committed
743
 * \li	nodep != NULL && *nodep == NULL
Bob Halley's avatar
Bob Halley committed
744 745 746
 *
 * Ensures:
 *
Mark Andrews's avatar
Mark Andrews committed
747
 * \li	On success, *nodep is attached to the node with name 'name'.
Bob Halley's avatar
Bob Halley committed
748 749 750
 *
 * Returns:
 *
Mark Andrews's avatar
Mark Andrews committed
751 752
 * \li	#ISC_R_SUCCESS
 * \li	#ISC_R_NOTFOUND			If !create and name not found.
753
 * \li	#ISC_R_NOMEMORY			Can only happen if create is ISC_TRUE.
Bob Halley's avatar
Bob Halley committed
754
 *
Mark Andrews's avatar
Mark Andrews committed
755
 * \li	Other results are possible, depending upon the database
Bob Halley's avatar
Bob Halley committed
756 757
 *	implementation used.
 */
Bob Halley's avatar
Bob Halley committed
758

759
isc_result_t
Bob Halley's avatar
Bob Halley committed
760
dns_db_find(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version,
761
	    dns_rdatatype_t type, unsigned int options, isc_stdtime_t now,
Bob Halley's avatar
Bob Halley committed
762
	    dns_dbnode_t **nodep, dns_name_t *foundname,
Bob Halley's avatar
Bob Halley committed
763
	    dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
764 765 766 767 768 769 770

isc_result_t
dns_db_findext(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version,
	       dns_rdatatype_t type, unsigned int options, isc_stdtime_t now,
	       dns_dbnode_t **nodep, dns_name_t *foundname,
	       dns_clientinfomethods_t *methods, dns_clientinfo_t *clientinfo,
	       dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
771
/*%<
772 773
 * Find the best match for 'name' and 'type' in version 'version' of 'db'.
 *
774 775 776 777 778
 * dns_db_findext() (find extended) also accepts parameters 'methods'
 * and 'clientinfo', which when provided enable the database to retreive
 * information about the client from the caller, and modify its response
 * on the basis of this information.
 *
779 780
 * Notes:
 *
Mark Andrews's avatar
Mark Andrews committed
781
 * \li	If type == dns_rdataset_any, then rdataset will not be bound.
782
 *
Mark Andrews's avatar
Mark Andrews committed
783
 * \li	If 'options' does not have #DNS_DBFIND_GLUEOK set, then no glue will
784
 *	be returned.  For zone databases, glue is as defined in RFC2181.
785 786
 *	For cache databases, glue is any rdataset with a trust of
 *	dns_trust_glue.
787
 *
788
 * \li	If 'options' does not have #DNS_DBFIND_ADDITIONALOK set, then no
Automatic Updater's avatar
Automatic Updater committed
789
 *	additional records will be returned.  Only caches can have
790 791
 *	rdataset with trust dns_trust_additional.
 *
Mark Andrews's avatar
Mark Andrews committed
792
 * \li	If 'options' does not have #DNS_DBFIND_PENDINGOK set, then no
Bob Halley's avatar
Bob Halley committed
793 794 795
 *	pending data will be returned.  This option is only meaningful for
 *	cache databases.
 *
Mark Andrews's avatar
Mark Andrews committed
796
 * \li	If the #DNS_DBFIND_NOWILD option is set, then wildcard matching will
797 798
 *	be disabled.  This option is only meaningful for zone databases.
 *
799 800 801 802 803 804 805 806 807
 * \li  If the #DNS_DBFIND_NOZONECUT option is set, the database is
 *	assumed to contain no zone cuts above 'name'.  An implementation
 *	may therefore choose to search for a match beginning at 'name'
 *	rather than walking down the tree to check check for delegations.
 *	If #DNS_DBFIND_NOWILD is not set, wildcard matching will be
 *	attempted at each node starting at the direct ancestor of 'name'
 *	and working up to the zone origin.  This option is only meaningful
 *	when querying redirect zones.
 *
Mark Andrews's avatar
Mark Andrews committed
808
 * \li	If the #DNS_DBFIND_FORCENSEC option is set, the database is assumed to
809
 *	have NSEC records, and these will be returned when appropriate.  This
810 811 812
 *	is only necessary when querying a database that was not secure
 *	when created.
 *
Mark Andrews's avatar
Mark Andrews committed
813
 * \li	If the DNS_DBFIND_COVERINGNSEC option is set, then look for a
814 815 816 817 818
 *	NSEC record that potentially covers 'name' if a answer cannot
 *	be found.  Note the returned NSEC needs to be checked to ensure
 *	that it is correct.  This only affects answers returned from the
 *	cache.
 *
819
 * \li	If the #DNS_DBFIND_FORCENSEC3 option is set, then we are looking
820 821 822
 *	in the NSEC3 tree and not the main tree.  Without this option being
 *	set NSEC3 records will not be found.
 *
Mark Andrews's avatar
Mark Andrews committed
823
 * \li	To respond to a query for SIG records, the caller should create a
824 825
 *	rdataset iterator and extract the signatures from each rdataset.
 *
Mark Andrews's avatar
Mark Andrews committed
826
 * \li	Making queries of type ANY with #DNS_DBFIND_GLUEOK is not recommended,
Bob Halley's avatar
Bob Halley committed
827 828 829
 *	because the burden of determining whether a given rdataset is valid
 *	glue or not falls upon the caller.
 *
Mark Andrews's avatar
Mark Andrews committed
830
 * \li	The 'now' field is ignored if 'db' is a zone database.  If 'db' is a
831 832 833 834 835
 *	cache database, an rdataset will not be found unless it expires after
 *	'now'.  Any ANY query will not match unless at least one rdataset at
 *	the node expires after 'now'.  If 'now' is zero, then the current time
 *	will be used.
 *
836 837
 * Requires:
 *
Mark Andrews's avatar
Mark Andrews committed
838
 * \li	'db' is a valid database.
839
 *
Mark Andrews's avatar
Mark Andrews committed
840
 * \li	'type' is not SIG, or a meta-RR type other than 'ANY' (e.g. 'OPT').
841
 *
Mark Andrews's avatar
Mark Andrews committed
842
 * \li	'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL.
843
 *
Mark Andrews's avatar
Mark Andrews committed
844
 * \li	'foundname' is a valid name with a dedicated buffer.
845
 *
Mark Andrews's avatar
Mark Andrews committed
846
 * \li	'rdataset' is NULL, or is a valid unassociated rdataset.
847
 *
848 849
 * Ensures,
 *	on a non-error completion:
850
 *
851
 *	\li	If nodep != NULL, then it is bound to the found node.
852
 *
853
 *	\li	If foundname != NULL, then it contains the full name of the
854 855
 *		found node.
 *
856
 *	\li	If rdataset != NULL and type != dns_rdatatype_any, then
857 858 859 860
 *		rdataset is bound to the found rdataset.
 *
 *	Non-error results are:
 *
Mark Andrews's avatar
Mark Andrews committed
861
 *	\li	#ISC_R_SUCCESS			The desired node and type were
862
 *						found.
863
 *
Mark Andrews's avatar
Mark Andrews committed
864
 *	\li	#DNS_R_WILDCARD			The desired node and type were
865 866 867
 *						found after performing
 *						wildcard matching.  This is
 *						only returned if the
868
 *						#DNS_DBFIND_INDICATEWILD
869
 *						option is set; otherwise
870
 *						#ISC_R_SUCCESS is returned.
871
 *
Mark Andrews's avatar
Mark Andrews committed
872
 *	\li	#DNS_R_GLUE			The desired node and type were
873 874 875 876 877