PageRenderTime 49ms CodeModel.GetById 15ms app.highlight 25ms RepoModel.GetById 1ms app.codeStats 0ms

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

https://bitbucket.org/freebsd/freebsd-head/
C++ Header | 1535 lines | 299 code | 80 blank | 1156 comment | 0 complexity | 4c37c0cfbacd8363bfd27aa81457d9ae MD5 | raw file
   1/*
   2 * Copyright (C) 2004-2009, 2011, 2012  Internet Systems Consortium, Inc. ("ISC")
   3 * Copyright (C) 1999-2003  Internet Software Consortium.
   4 *
   5 * Permission to use, copy, modify, and/or distribute this software for any
   6 * purpose with or without fee is hereby granted, provided that the above
   7 * copyright notice and this permission notice appear in all copies.
   8 *
   9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15 * PERFORMANCE OF THIS SOFTWARE.
  16 */
  17
  18/* $Id$ */
  19
  20#ifndef DNS_DB_H
  21#define DNS_DB_H 1
  22
  23/*****
  24 ***** Module Info
  25 *****/
  26
  27/*! \file dns/db.h
  28 * \brief
  29 * The DNS DB interface allows named rdatasets to be stored and retrieved.
  30 *
  31 * The dns_db_t type is like a "virtual class".  To actually use
  32 * DBs, an implementation of the class is required.
  33 *
  34 * XXX more XXX
  35 *
  36 * MP:
  37 * \li	The module ensures appropriate synchronization of data structures it
  38 *	creates and manipulates.
  39 *
  40 * Reliability:
  41 * \li	No anticipated impact.
  42 *
  43 * Resources:
  44 * \li	TBS
  45 *
  46 * Security:
  47 * \li	No anticipated impact.
  48 *
  49 * Standards:
  50 * \li	None.
  51 */
  52
  53/*****
  54 ***** Imports
  55 *****/
  56
  57#include <isc/lang.h>
  58#include <isc/magic.h>
  59#include <isc/ondestroy.h>
  60#include <isc/stdtime.h>
  61
  62#include <dns/fixedname.h>
  63#include <dns/name.h>
  64#include <dns/rdata.h>
  65#include <dns/rdataset.h>
  66#include <dns/rpz.h>
  67#include <dns/types.h>
  68
  69ISC_LANG_BEGINDECLS
  70
  71/*****
  72 ***** Types
  73 *****/
  74
  75typedef struct dns_dbmethods {
  76	void		(*attach)(dns_db_t *source, dns_db_t **targetp);
  77	void		(*detach)(dns_db_t **dbp);
  78	isc_result_t	(*beginload)(dns_db_t *db, dns_addrdatasetfunc_t *addp,
  79				     dns_dbload_t **dbloadp);
  80	isc_result_t	(*endload)(dns_db_t *db, dns_dbload_t **dbloadp);
  81	isc_result_t	(*dump)(dns_db_t *db, dns_dbversion_t *version,
  82				const char *filename,
  83				dns_masterformat_t masterformat);
  84	void		(*currentversion)(dns_db_t *db,
  85					  dns_dbversion_t **versionp);
  86	isc_result_t	(*newversion)(dns_db_t *db,
  87				      dns_dbversion_t **versionp);
  88	void		(*attachversion)(dns_db_t *db, dns_dbversion_t *source,
  89					 dns_dbversion_t **targetp);
  90	void		(*closeversion)(dns_db_t *db,
  91					dns_dbversion_t **versionp,
  92					isc_boolean_t commit);
  93	isc_result_t	(*findnode)(dns_db_t *db, dns_name_t *name,
  94				    isc_boolean_t create,
  95				    dns_dbnode_t **nodep);
  96	isc_result_t	(*find)(dns_db_t *db, dns_name_t *name,
  97				dns_dbversion_t *version,
  98				dns_rdatatype_t type, unsigned int options,
  99				isc_stdtime_t now,
 100				dns_dbnode_t **nodep, dns_name_t *foundname,
 101				dns_rdataset_t *rdataset,
 102				dns_rdataset_t *sigrdataset);
 103	isc_result_t	(*findzonecut)(dns_db_t *db, dns_name_t *name,
 104				       unsigned int options, isc_stdtime_t now,
 105				       dns_dbnode_t **nodep,
 106				       dns_name_t *foundname,
 107				       dns_rdataset_t *rdataset,
 108				       dns_rdataset_t *sigrdataset);
 109	void		(*attachnode)(dns_db_t *db,
 110				      dns_dbnode_t *source,
 111				      dns_dbnode_t **targetp);
 112	void		(*detachnode)(dns_db_t *db,
 113				      dns_dbnode_t **targetp);
 114	isc_result_t	(*expirenode)(dns_db_t *db, dns_dbnode_t *node,
 115				      isc_stdtime_t now);
 116	void		(*printnode)(dns_db_t *db, dns_dbnode_t *node,
 117				     FILE *out);
 118	isc_result_t 	(*createiterator)(dns_db_t *db, unsigned int options,
 119					  dns_dbiterator_t **iteratorp);
 120	isc_result_t	(*findrdataset)(dns_db_t *db, dns_dbnode_t *node,
 121					dns_dbversion_t *version,
 122					dns_rdatatype_t type,
 123					dns_rdatatype_t covers,
 124					isc_stdtime_t now,
 125					dns_rdataset_t *rdataset,
 126					dns_rdataset_t *sigrdataset);
 127	isc_result_t	(*allrdatasets)(dns_db_t *db, dns_dbnode_t *node,
 128					dns_dbversion_t *version,
 129					isc_stdtime_t now,
 130					dns_rdatasetiter_t **iteratorp);
 131	isc_result_t	(*addrdataset)(dns_db_t *db, dns_dbnode_t *node,
 132				       dns_dbversion_t *version,
 133				       isc_stdtime_t now,
 134				       dns_rdataset_t *rdataset,
 135				       unsigned int options,
 136				       dns_rdataset_t *addedrdataset);
 137	isc_result_t	(*subtractrdataset)(dns_db_t *db, dns_dbnode_t *node,
 138					    dns_dbversion_t *version,
 139					    dns_rdataset_t *rdataset,
 140					    unsigned int options,
 141					    dns_rdataset_t *newrdataset);
 142	isc_result_t	(*deleterdataset)(dns_db_t *db, dns_dbnode_t *node,
 143					  dns_dbversion_t *version,
 144					  dns_rdatatype_t type,
 145					  dns_rdatatype_t covers);
 146	isc_boolean_t	(*issecure)(dns_db_t *db);
 147	unsigned int	(*nodecount)(dns_db_t *db);
 148	isc_boolean_t	(*ispersistent)(dns_db_t *db);
 149	void		(*overmem)(dns_db_t *db, isc_boolean_t overmem);
 150	void		(*settask)(dns_db_t *db, isc_task_t *);
 151	isc_result_t	(*getoriginnode)(dns_db_t *db, dns_dbnode_t **nodep);
 152	void		(*transfernode)(dns_db_t *db, dns_dbnode_t **sourcep,
 153					dns_dbnode_t **targetp);
 154	isc_result_t    (*getnsec3parameters)(dns_db_t *db,
 155					      dns_dbversion_t *version,
 156					      dns_hash_t *hash,
 157					      isc_uint8_t *flags,
 158					      isc_uint16_t *iterations,
 159					      unsigned char *salt,
 160					      size_t *salt_len);
 161	isc_result_t    (*findnsec3node)(dns_db_t *db, dns_name_t *name,
 162					 isc_boolean_t create,
 163					 dns_dbnode_t **nodep);
 164	isc_result_t	(*setsigningtime)(dns_db_t *db,
 165					  dns_rdataset_t *rdataset,
 166					  isc_stdtime_t resign);
 167	isc_result_t	(*getsigningtime)(dns_db_t *db,
 168					  dns_rdataset_t *rdataset,
 169					  dns_name_t *name);
 170	void		(*resigned)(dns_db_t *db, dns_rdataset_t *rdataset,
 171					   dns_dbversion_t *version);
 172	isc_boolean_t	(*isdnssec)(dns_db_t *db);
 173	dns_stats_t	*(*getrrsetstats)(dns_db_t *db);
 174	void		(*rpz_enabled)(dns_db_t *db, dns_rpz_st_t *st);
 175	isc_result_t	(*rpz_findips)(dns_rpz_zone_t *rpz,
 176				       dns_rpz_type_t rpz_type,
 177				       dns_zone_t *zone, dns_db_t *db,
 178				       dns_dbversion_t *version,
 179				       dns_rdataset_t *ardataset,
 180				       dns_rpz_st_t *st,
 181				       dns_name_t *query_qname);
 182} dns_dbmethods_t;
 183
 184typedef isc_result_t
 185(*dns_dbcreatefunc_t)(isc_mem_t *mctx, dns_name_t *name,
 186		      dns_dbtype_t type, dns_rdataclass_t rdclass,
 187		      unsigned int argc, char *argv[], void *driverarg,
 188		      dns_db_t **dbp);
 189
 190#define DNS_DB_MAGIC		ISC_MAGIC('D','N','S','D')
 191#define DNS_DB_VALID(db)	ISC_MAGIC_VALID(db, DNS_DB_MAGIC)
 192
 193/*%
 194 * This structure is actually just the common prefix of a DNS db
 195 * implementation's version of a dns_db_t.
 196 * \brief
 197 * Direct use of this structure by clients is forbidden.  DB implementations
 198 * may change the structure.  'magic' must be DNS_DB_MAGIC for any of the
 199 * dns_db_ routines to work.  DB implementations must maintain all DB
 200 * invariants.
 201 */
 202struct dns_db {
 203	unsigned int			magic;
 204	unsigned int			impmagic;
 205	dns_dbmethods_t *		methods;
 206	isc_uint16_t			attributes;
 207	dns_rdataclass_t		rdclass;
 208	dns_name_t			origin;
 209	isc_ondestroy_t			ondest;
 210	isc_mem_t *			mctx;
 211};
 212
 213#define DNS_DBATTR_CACHE		0x01
 214#define DNS_DBATTR_STUB			0x02
 215
 216/*@{*/
 217/*%
 218 * Options that can be specified for dns_db_find().
 219 */
 220#define DNS_DBFIND_GLUEOK		0x0001
 221#define DNS_DBFIND_VALIDATEGLUE		0x0002
 222#define DNS_DBFIND_NOWILD		0x0004
 223#define DNS_DBFIND_PENDINGOK		0x0008
 224#define DNS_DBFIND_NOEXACT		0x0010
 225#define DNS_DBFIND_FORCENSEC		0x0020
 226#define DNS_DBFIND_COVERINGNSEC		0x0040
 227#define DNS_DBFIND_FORCENSEC3		0x0080
 228#define DNS_DBFIND_ADDITIONALOK		0x0100
 229/*@}*/
 230
 231/*@{*/
 232/*%
 233 * Options that can be specified for dns_db_addrdataset().
 234 */
 235#define DNS_DBADD_MERGE			0x01
 236#define DNS_DBADD_FORCE			0x02
 237#define DNS_DBADD_EXACT			0x04
 238#define DNS_DBADD_EXACTTTL		0x08
 239/*@}*/
 240
 241/*%
 242 * Options that can be specified for dns_db_subtractrdataset().
 243 */
 244#define DNS_DBSUB_EXACT			0x01
 245
 246/*@{*/
 247/*%
 248 * Iterator options
 249 */
 250#define DNS_DB_RELATIVENAMES	0x1
 251#define DNS_DB_NSEC3ONLY	0x2
 252#define DNS_DB_NONSEC3		0x4
 253/*@}*/
 254
 255/*****
 256 ***** Methods
 257 *****/
 258
 259/***
 260 *** Basic DB Methods
 261 ***/
 262
 263isc_result_t
 264dns_db_create(isc_mem_t *mctx, const char *db_type, dns_name_t *origin,
 265	      dns_dbtype_t type, dns_rdataclass_t rdclass,
 266	      unsigned int argc, char *argv[], dns_db_t **dbp);
 267/*%<
 268 * Create a new database using implementation 'db_type'.
 269 *
 270 * Notes:
 271 * \li	All names in the database must be subdomains of 'origin' and in class
 272 *	'rdclass'.  The database makes its own copy of the origin, so the
 273 *	caller may do whatever they like with 'origin' and its storage once the
 274 *	call returns.
 275 *
 276 * \li	DB implementation-specific parameters are passed using argc and argv.
 277 *
 278 * Requires:
 279 *
 280 * \li	dbp != NULL and *dbp == NULL
 281 *
 282 * \li	'origin' is a valid absolute domain name.
 283 *
 284 * \li	mctx is a valid memory context
 285 *
 286 * Ensures:
 287 *
 288 * \li	A copy of 'origin' has been made for the databases use, and the
 289 *	caller is free to do whatever they want with the name and storage
 290 *	associated with 'origin'.
 291 *
 292 * Returns:
 293 *
 294 * \li	#ISC_R_SUCCESS
 295 * \li	#ISC_R_NOMEMORY
 296 * \li	#ISC_R_NOTFOUND				db_type not found
 297 *
 298 * \li	Many other errors are possible, depending on what db_type was
 299 *	specified.
 300 */
 301
 302void
 303dns_db_attach(dns_db_t *source, dns_db_t **targetp);
 304/*%<
 305 * Attach *targetp to source.
 306 *
 307 * Requires:
 308 *
 309 * \li	'source' is a valid database.
 310 *
 311 * \li	'targetp' points to a NULL dns_db_t *.
 312 *
 313 * Ensures:
 314 *
 315 * \li	*targetp is attached to source.
 316 */
 317
 318void
 319dns_db_detach(dns_db_t **dbp);
 320/*%<
 321 * Detach *dbp from its database.
 322 *
 323 * Requires:
 324 *
 325 * \li	'dbp' points to a valid database.
 326 *
 327 * Ensures:
 328 *
 329 * \li	*dbp is NULL.
 330 *
 331 * \li	If '*dbp' is the last reference to the database,
 332 *		all resources used by the database will be freed
 333 */
 334
 335isc_result_t
 336dns_db_ondestroy(dns_db_t *db, isc_task_t *task, isc_event_t **eventp);
 337/*%<
 338 * Causes 'eventp' to be sent to be sent to 'task' when the database is
 339 * destroyed.
 340 *
 341 * Note; ownership of the eventp is taken from the caller (and *eventp is
 342 * set to NULL). The sender field of the event is set to 'db' before it is
 343 * sent to the task.
 344 */
 345
 346isc_boolean_t
 347dns_db_iscache(dns_db_t *db);
 348/*%<
 349 * Does 'db' have cache semantics?
 350 *
 351 * Requires:
 352 *
 353 * \li	'db' is a valid database.
 354 *
 355 * Returns:
 356 * \li	#ISC_TRUE	'db' has cache semantics
 357 * \li	#ISC_FALSE	otherwise
 358 */
 359
 360isc_boolean_t
 361dns_db_iszone(dns_db_t *db);
 362/*%<
 363 * Does 'db' have zone semantics?
 364 *
 365 * Requires:
 366 *
 367 * \li	'db' is a valid database.
 368 *
 369 * Returns:
 370 * \li	#ISC_TRUE	'db' has zone semantics
 371 * \li	#ISC_FALSE	otherwise
 372 */
 373
 374isc_boolean_t
 375dns_db_isstub(dns_db_t *db);
 376/*%<
 377 * Does 'db' have stub semantics?
 378 *
 379 * Requires:
 380 *
 381 * \li	'db' is a valid database.
 382 *
 383 * Returns:
 384 * \li	#ISC_TRUE	'db' has zone semantics
 385 * \li	#ISC_FALSE	otherwise
 386 */
 387
 388isc_boolean_t
 389dns_db_issecure(dns_db_t *db);
 390/*%<
 391 * Is 'db' secure?
 392 *
 393 * Requires:
 394 *
 395 * \li	'db' is a valid database with zone semantics.
 396 *
 397 * Returns:
 398 * \li	#ISC_TRUE	'db' is secure.
 399 * \li	#ISC_FALSE	'db' is not secure.
 400 */
 401
 402isc_boolean_t
 403dns_db_isdnssec(dns_db_t *db);
 404/*%<
 405 * Is 'db' secure or partially secure?
 406 *
 407 * Requires:
 408 *
 409 * \li	'db' is a valid database with zone semantics.
 410 *
 411 * Returns:
 412 * \li	#ISC_TRUE	'db' is secure or is partially.
 413 * \li	#ISC_FALSE	'db' is not secure.
 414 */
 415
 416dns_name_t *
 417dns_db_origin(dns_db_t *db);
 418/*%<
 419 * The origin of the database.
 420 *
 421 * Note: caller must not try to change this name.
 422 *
 423 * Requires:
 424 *
 425 * \li	'db' is a valid database.
 426 *
 427 * Returns:
 428 *
 429 * \li	The origin of the database.
 430 */
 431
 432dns_rdataclass_t
 433dns_db_class(dns_db_t *db);
 434/*%<
 435 * The class of the database.
 436 *
 437 * Requires:
 438 *
 439 * \li	'db' is a valid database.
 440 *
 441 * Returns:
 442 *
 443 * \li	The class of the database.
 444 */
 445
 446isc_result_t
 447dns_db_beginload(dns_db_t *db, dns_addrdatasetfunc_t *addp,
 448		 dns_dbload_t **dbloadp);
 449/*%<
 450 * Begin loading 'db'.
 451 *
 452 * Requires:
 453 *
 454 * \li	'db' is a valid database.
 455 *
 456 * \li	This is the first attempt to load 'db'.
 457 *
 458 * \li	addp != NULL && *addp == NULL
 459 *
 460 * \li	dbloadp != NULL && *dbloadp == NULL
 461 *
 462 * Ensures:
 463 *
 464 * \li	On success, *addp will be a valid dns_addrdatasetfunc_t suitable
 465 *	for loading 'db'.  *dbloadp will be a valid DB load context which
 466 *	should be used as 'arg' when *addp is called.
 467 *
 468 * Returns:
 469 *
 470 * \li	#ISC_R_SUCCESS
 471 * \li	#ISC_R_NOMEMORY
 472 *
 473 * \li	Other results are possible, depending upon the database
 474 *	implementation used, syntax errors in the master file, etc.
 475 */
 476
 477isc_result_t
 478dns_db_endload(dns_db_t *db, dns_dbload_t **dbloadp);
 479/*%<
 480 * Finish loading 'db'.
 481 *
 482 * Requires:
 483 *
 484 * \li	'db' is a valid database that is being loaded.
 485 *
 486 * \li	dbloadp != NULL and *dbloadp is a valid database load context.
 487 *
 488 * Ensures:
 489 *
 490 * \li	*dbloadp == NULL
 491 *
 492 * Returns:
 493 *
 494 * \li	#ISC_R_SUCCESS
 495 * \li	#ISC_R_NOMEMORY
 496 *
 497 * \li	Other results are possible, depending upon the database
 498 *	implementation used, syntax errors in the master file, etc.
 499 */
 500
 501isc_result_t
 502dns_db_load(dns_db_t *db, const char *filename);
 503
 504isc_result_t
 505dns_db_load2(dns_db_t *db, const char *filename, dns_masterformat_t format);
 506
 507isc_result_t
 508dns_db_load3(dns_db_t *db, const char *filename, dns_masterformat_t format,
 509	     unsigned int options);
 510/*%<
 511 * Load master file 'filename' into 'db'.
 512 *
 513 * Notes:
 514 * \li	This routine is equivalent to calling
 515 *
 516 *\code
 517 *		dns_db_beginload();
 518 *		dns_master_loadfile();
 519 *		dns_db_endload();
 520 *\endcode
 521 *
 522 * Requires:
 523 *
 524 * \li	'db' is a valid database.
 525 *
 526 * \li	This is the first attempt to load 'db'.
 527 *
 528 * Returns:
 529 *
 530 * \li	#ISC_R_SUCCESS
 531 * \li	#ISC_R_NOMEMORY
 532 *
 533 * \li	Other results are possible, depending upon the database
 534 *	implementation used, syntax errors in the master file, etc.
 535 */
 536
 537isc_result_t
 538dns_db_dump(dns_db_t *db, dns_dbversion_t *version, const char *filename);
 539
 540isc_result_t
 541dns_db_dump2(dns_db_t *db, dns_dbversion_t *version, const char *filename,
 542	     dns_masterformat_t masterformat);
 543/*%<
 544 * Dump version 'version' of 'db' to master file 'filename'.
 545 *
 546 * Requires:
 547 *
 548 * \li	'db' is a valid database.
 549 *
 550 * \li	'version' is a valid version.
 551 *
 552 * Returns:
 553 *
 554 * \li	#ISC_R_SUCCESS
 555 * \li	#ISC_R_NOMEMORY
 556 *
 557 * \li	Other results are possible, depending upon the database
 558 *	implementation used, OS file errors, etc.
 559 */
 560
 561/***
 562 *** Version Methods
 563 ***/
 564
 565void
 566dns_db_currentversion(dns_db_t *db, dns_dbversion_t **versionp);
 567/*%<
 568 * Open the current version for reading.
 569 *
 570 * Requires:
 571 *
 572 * \li	'db' is a valid database with zone semantics.
 573 *
 574 * \li	versionp != NULL && *verisonp == NULL
 575 *
 576 * Ensures:
 577 *
 578 * \li	On success, '*versionp' is attached to the current version.
 579 *
 580 */
 581
 582isc_result_t
 583dns_db_newversion(dns_db_t *db, dns_dbversion_t **versionp);
 584/*%<
 585 * Open a new version for reading and writing.
 586 *
 587 * Requires:
 588 *
 589 * \li	'db' is a valid database with zone semantics.
 590 *
 591 * \li	versionp != NULL && *verisonp == NULL
 592 *
 593 * Ensures:
 594 *
 595 * \li	On success, '*versionp' is attached to the current version.
 596 *
 597 * Returns:
 598 *
 599 * \li	#ISC_R_SUCCESS
 600 * \li	#ISC_R_NOMEMORY
 601 *
 602 * \li	Other results are possible, depending upon the database
 603 *	implementation used.
 604 */
 605
 606void
 607dns_db_attachversion(dns_db_t *db, dns_dbversion_t *source,
 608		     dns_dbversion_t **targetp);
 609/*%<
 610 * Attach '*targetp' to 'source'.
 611 *
 612 * Requires:
 613 *
 614 * \li	'db' is a valid database with zone semantics.
 615 *
 616 * \li	source is a valid open version
 617 *
 618 * \li	targetp != NULL && *targetp == NULL
 619 *
 620 * Ensures:
 621 *
 622 * \li	'*targetp' is attached to source.
 623 */
 624
 625void
 626dns_db_closeversion(dns_db_t *db, dns_dbversion_t **versionp,
 627		    isc_boolean_t commit);
 628/*%<
 629 * Close version '*versionp'.
 630 *
 631 * Note: if '*versionp' is a read-write version and 'commit' is ISC_TRUE,
 632 * then all changes made in the version will take effect, otherwise they
 633 * will be rolled back.  The value of 'commit' is ignored for read-only
 634 * versions.
 635 *
 636 * Requires:
 637 *
 638 * \li	'db' is a valid database with zone semantics.
 639 *
 640 * \li	'*versionp' refers to a valid version.
 641 *
 642 * \li	If committing a writable version, then there must be no other
 643 *	outstanding references to the version (e.g. an active rdataset
 644 *	iterator).
 645 *
 646 * Ensures:
 647 *
 648 * \li	*versionp == NULL
 649 *
 650 * \li	If *versionp is a read-write version, and commit is ISC_TRUE, then
 651 *	the version will become the current version.  If !commit, then all
 652 *	changes made in the version will be undone, and the version will
 653 *	not become the current version.
 654 */
 655
 656/***
 657 *** Node Methods
 658 ***/
 659
 660isc_result_t
 661dns_db_findnode(dns_db_t *db, dns_name_t *name, isc_boolean_t create,
 662		dns_dbnode_t **nodep);
 663/*%<
 664 * Find the node with name 'name'.
 665 *
 666 * Notes:
 667 * \li	If 'create' is ISC_TRUE and no node with name 'name' exists, then
 668 *	such a node will be created.
 669 *
 670 * \li	This routine is for finding or creating a node with the specified
 671 *	name.  There are no partial matches.  It is not suitable for use
 672 *	in building responses to ordinary DNS queries; clients which wish
 673 *	to do that should use dns_db_find() instead.
 674 *
 675 * Requires:
 676 *
 677 * \li	'db' is a valid database.
 678 *
 679 * \li	'name' is a valid, non-empty, absolute name.
 680 *
 681 * \li	nodep != NULL && *nodep == NULL
 682 *
 683 * Ensures:
 684 *
 685 * \li	On success, *nodep is attached to the node with name 'name'.
 686 *
 687 * Returns:
 688 *
 689 * \li	#ISC_R_SUCCESS
 690 * \li	#ISC_R_NOTFOUND			If !create and name not found.
 691 * \li	#ISC_R_NOMEMORY			Can only happen if create is ISC_TRUE.
 692 *
 693 * \li	Other results are possible, depending upon the database
 694 *	implementation used.
 695 */
 696
 697isc_result_t
 698dns_db_find(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version,
 699	    dns_rdatatype_t type, unsigned int options, isc_stdtime_t now,
 700	    dns_dbnode_t **nodep, dns_name_t *foundname,
 701	    dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
 702/*%<
 703 * Find the best match for 'name' and 'type' in version 'version' of 'db'.
 704 *
 705 * Notes:
 706 *
 707 * \li	If type == dns_rdataset_any, then rdataset will not be bound.
 708 *
 709 * \li	If 'options' does not have #DNS_DBFIND_GLUEOK set, then no glue will
 710 *	be returned.  For zone databases, glue is as defined in RFC2181.
 711 *	For cache databases, glue is any rdataset with a trust of
 712 *	dns_trust_glue.
 713 *
 714 * \li	If 'options' does not have #DNS_DBFIND_ADDITIONALOK set, then no
 715 *	additional records will be returned.  Only caches can have
 716 *	rdataset with trust dns_trust_additional.
 717 *
 718 * \li	If 'options' does not have #DNS_DBFIND_PENDINGOK set, then no
 719 *	pending data will be returned.  This option is only meaningful for
 720 *	cache databases.
 721 *
 722 * \li	If the #DNS_DBFIND_NOWILD option is set, then wildcard matching will
 723 *	be disabled.  This option is only meaningful for zone databases.
 724 *
 725 * \li	If the #DNS_DBFIND_FORCENSEC option is set, the database is assumed to
 726 *	have NSEC records, and these will be returned when appropriate.  This
 727 *	is only necessary when querying a database that was not secure
 728 *	when created.
 729 *
 730 * \li	If the DNS_DBFIND_COVERINGNSEC option is set, then look for a
 731 *	NSEC record that potentially covers 'name' if a answer cannot
 732 *	be found.  Note the returned NSEC needs to be checked to ensure
 733 *	that it is correct.  This only affects answers returned from the
 734 *	cache.
 735 *
 736 * \li	To respond to a query for SIG records, the caller should create a
 737 *	rdataset iterator and extract the signatures from each rdataset.
 738 *
 739 * \li	Making queries of type ANY with #DNS_DBFIND_GLUEOK is not recommended,
 740 *	because the burden of determining whether a given rdataset is valid
 741 *	glue or not falls upon the caller.
 742 *
 743 * \li	The 'now' field is ignored if 'db' is a zone database.  If 'db' is a
 744 *	cache database, an rdataset will not be found unless it expires after
 745 *	'now'.  Any ANY query will not match unless at least one rdataset at
 746 *	the node expires after 'now'.  If 'now' is zero, then the current time
 747 *	will be used.
 748 *
 749 * Requires:
 750 *
 751 * \li	'db' is a valid database.
 752 *
 753 * \li	'type' is not SIG, or a meta-RR type other than 'ANY' (e.g. 'OPT').
 754 *
 755 * \li	'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL.
 756 *
 757 * \li	'foundname' is a valid name with a dedicated buffer.
 758 *
 759 * \li	'rdataset' is NULL, or is a valid unassociated rdataset.
 760 *
 761 * Ensures,
 762 *	on a non-error completion:
 763 *
 764 *	\li	If nodep != NULL, then it is bound to the found node.
 765 *
 766 *	\li	If foundname != NULL, then it contains the full name of the
 767 *		found node.
 768 *
 769 *	\li	If rdataset != NULL and type != dns_rdatatype_any, then
 770 *		rdataset is bound to the found rdataset.
 771 *
 772 *	Non-error results are:
 773 *
 774 *	\li	#ISC_R_SUCCESS			The desired node and type were
 775 *						found.
 776 *
 777 *	\li	#DNS_R_WILDCARD			The desired node and type were
 778 *						found after performing
 779 *						wildcard matching.  This is
 780 *						only returned if the
 781 *						#DNS_DBFIND_INDICATEWILD
 782 *						option is set; otherwise
 783 *						#ISC_R_SUCCESS is returned.
 784 *
 785 *	\li	#DNS_R_GLUE			The desired node and type were
 786 *						found, but are glue.  This
 787 *						result can only occur if
 788 *						the DNS_DBFIND_GLUEOK option
 789 *						is set.  This result can only
 790 *						occur if 'db' is a zone
 791 *						database.  If type ==
 792 *						dns_rdatatype_any, then the
 793 *						node returned may contain, or
 794 *						consist entirely of invalid
 795 *						glue (i.e. data occluded by a
 796 *						zone cut).  The caller must
 797 *						take care not to return invalid
 798 *						glue to a client.
 799 *
 800 *	\li	#DNS_R_DELEGATION		The data requested is beneath
 801 *						a zone cut.  node, foundname,
 802 *						and rdataset reference the
 803 *						NS RRset of the zone cut.
 804 *						If 'db' is a cache database,
 805 *						then this is the deepest known
 806 *						delegation.
 807 *
 808 *	\li	#DNS_R_ZONECUT			type == dns_rdatatype_any, and
 809 *						the desired node is a zonecut.
 810 *						The caller must take care not
 811 *						to return inappropriate glue
 812 *						to a client.  This result can
 813 *						only occur if 'db' is a zone
 814 *						database and DNS_DBFIND_GLUEOK
 815 *						is set.
 816 *
 817 *	\li	#DNS_R_DNAME			The data requested is beneath
 818 *						a DNAME.  node, foundname,
 819 *						and rdataset reference the
 820 *						DNAME RRset.
 821 *
 822 *	\li	#DNS_R_CNAME			The rdataset requested was not
 823 *						found, but there is a CNAME
 824 *						at the desired name.  node,
 825 *						foundname, and rdataset
 826 *						reference the CNAME RRset.
 827 *
 828 *	\li	#DNS_R_NXDOMAIN			The desired name does not
 829 *						exist.
 830 *
 831 *	\li	#DNS_R_NXRRSET			The desired name exists, but
 832 *						the desired type does not.
 833 *
 834 *	\li	#ISC_R_NOTFOUND			The desired name does not
 835 *						exist, and no delegation could
 836 *						be found.  This result can only
 837 *						occur if 'db' is a cache
 838 *						database.  The caller should
 839 *						use its nameserver(s) of last
 840 *						resort (e.g. root hints).
 841 *
 842 *	\li	#DNS_R_NCACHENXDOMAIN		The desired name does not
 843 *						exist.  'node' is bound to the
 844 *						cache node with the desired
 845 *						name, and 'rdataset' contains
 846 *						the negative caching proof.
 847 *
 848 *	\li	#DNS_R_NCACHENXRRSET		The desired type does not
 849 *						exist.  'node' is bound to the
 850 *						cache node with the desired
 851 *						name, and 'rdataset' contains
 852 *						the negative caching proof.
 853 *
 854 *	\li	#DNS_R_EMPTYNAME		The name exists but there is
 855 *						no data at the name.
 856 *
 857 *	\li	#DNS_R_COVERINGNSEC		The returned data is a NSEC
 858 *						that potentially covers 'name'.
 859 *
 860 *	\li	#DNS_R_EMPTYWILD		The name is a wildcard without
 861 *						resource records.
 862 *
 863 *	Error results:
 864 *
 865 *	\li	#ISC_R_NOMEMORY
 866 *
 867 *	\li	#DNS_R_BADDB			Data that is required to be
 868 *						present in the DB, e.g. an NSEC
 869 *						record in a secure zone, is not
 870 *						present.
 871 *
 872 *	\li	Other results are possible, and should all be treated as
 873 *		errors.
 874 */
 875
 876isc_result_t
 877dns_db_findzonecut(dns_db_t *db, dns_name_t *name,
 878		   unsigned int options, isc_stdtime_t now,
 879		   dns_dbnode_t **nodep, dns_name_t *foundname,
 880		   dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
 881/*%<
 882 * Find the deepest known zonecut which encloses 'name' in 'db'.
 883 *
 884 * Notes:
 885 *
 886 * \li	If the #DNS_DBFIND_NOEXACT option is set, then the zonecut returned
 887 *	(if any) will be the deepest known ancestor of 'name'.
 888 *
 889 * \li	If 'now' is zero, then the current time will be used.
 890 *
 891 * Requires:
 892 *
 893 * \li	'db' is a valid database with cache semantics.
 894 *
 895 * \li	'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL.
 896 *
 897 * \li	'foundname' is a valid name with a dedicated buffer.
 898 *
 899 * \li	'rdataset' is NULL, or is a valid unassociated rdataset.
 900 *
 901 * Ensures, on a non-error completion:
 902 *
 903 * \li	If nodep != NULL, then it is bound to the found node.
 904 *
 905 * \li	If foundname != NULL, then it contains the full name of the
 906 *	found node.
 907 *
 908 * \li	If rdataset != NULL and type != dns_rdatatype_any, then
 909 *	rdataset is bound to the found rdataset.
 910 *
 911 * Non-error results are:
 912 *
 913 * \li	#ISC_R_SUCCESS
 914 *
 915 * \li	#ISC_R_NOTFOUND
 916 *
 917 * \li	Other results are possible, and should all be treated as
 918 *	errors.
 919 */
 920
 921void
 922dns_db_attachnode(dns_db_t *db, dns_dbnode_t *source, dns_dbnode_t **targetp);
 923/*%<
 924 * Attach *targetp to source.
 925 *
 926 * Requires:
 927 *
 928 * \li	'db' is a valid database.
 929 *
 930 * \li	'source' is a valid node.
 931 *
 932 * \li	'targetp' points to a NULL dns_dbnode_t *.
 933 *
 934 * Ensures:
 935 *
 936 * \li	*targetp is attached to source.
 937 */
 938
 939void
 940dns_db_detachnode(dns_db_t *db, dns_dbnode_t **nodep);
 941/*%<
 942 * Detach *nodep from its node.
 943 *
 944 * Requires:
 945 *
 946 * \li	'db' is a valid database.
 947 *
 948 * \li	'nodep' points to a valid node.
 949 *
 950 * Ensures:
 951 *
 952 * \li	*nodep is NULL.
 953 */
 954
 955void
 956dns_db_transfernode(dns_db_t *db, dns_dbnode_t **sourcep,
 957		    dns_dbnode_t **targetp);
 958/*%<
 959 * Transfer a node between pointer.
 960 *
 961 * This is equivalent to calling dns_db_attachnode() then dns_db_detachnode().
 962 *
 963 * Requires:
 964 *
 965 * \li	'db' is a valid database.
 966 *
 967 * \li	'*sourcep' is a valid node.
 968 *
 969 * \li	'targetp' points to a NULL dns_dbnode_t *.
 970 *
 971 * Ensures:
 972 *
 973 * \li	'*sourcep' is NULL.
 974 */
 975
 976isc_result_t
 977dns_db_expirenode(dns_db_t *db, dns_dbnode_t *node, isc_stdtime_t now);
 978/*%<
 979 * Mark as stale all records at 'node' which expire at or before 'now'.
 980 *
 981 * Note: if 'now' is zero, then the current time will be used.
 982 *
 983 * Requires:
 984 *
 985 * \li	'db' is a valid cache database.
 986 *
 987 * \li	'node' is a valid node.
 988 */
 989
 990void
 991dns_db_printnode(dns_db_t *db, dns_dbnode_t *node, FILE *out);
 992/*%<
 993 * Print a textual representation of the contents of the node to
 994 * 'out'.
 995 *
 996 * Note: this function is intended for debugging, not general use.
 997 *
 998 * Requires:
 999 *
1000 * \li	'db' is a valid database.
1001 *
1002 * \li	'node' is a valid node.
1003 */
1004
1005/***
1006 *** DB Iterator Creation
1007 ***/
1008
1009isc_result_t
1010dns_db_createiterator(dns_db_t *db, unsigned int options,
1011		      dns_dbiterator_t **iteratorp);
1012/*%<
1013 * Create an iterator for version 'version' of 'db'.
1014 *
1015 * Notes:
1016 *
1017 * \li	One or more of the following options can be set.
1018 *	#DNS_DB_RELATIVENAMES
1019 *	#DNS_DB_NSEC3ONLY
1020 *	#DNS_DB_NONSEC3
1021 *
1022 * Requires:
1023 *
1024 * \li	'db' is a valid database.
1025 *
1026 * \li	iteratorp != NULL && *iteratorp == NULL
1027 *
1028 * Ensures:
1029 *
1030 * \li	On success, *iteratorp will be a valid database iterator.
1031 *
1032 * Returns:
1033 *
1034 * \li	#ISC_R_SUCCESS
1035 * \li	#ISC_R_NOMEMORY
1036 */
1037
1038/***
1039 *** Rdataset Methods
1040 ***/
1041
1042/*
1043 * XXXRTH  Should we check for glue and pending data in dns_db_findrdataset()?
1044 */
1045
1046isc_result_t
1047dns_db_findrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
1048		    dns_rdatatype_t type, dns_rdatatype_t covers,
1049		    isc_stdtime_t now, dns_rdataset_t *rdataset,
1050		    dns_rdataset_t *sigrdataset);
1051/*%<
1052 * Search for an rdataset of type 'type' at 'node' that are in version
1053 * 'version' of 'db'.  If found, make 'rdataset' refer to it.
1054 *
1055 * Notes:
1056 *
1057 * \li	If 'version' is NULL, then the current version will be used.
1058 *
1059 * \li	Care must be used when using this routine to build a DNS response:
1060 *	'node' should have been found with dns_db_find(), not
1061 *	dns_db_findnode().  No glue checking is done.  No checking for
1062 *	pending data is done.
1063 *
1064 * \li	The 'now' field is ignored if 'db' is a zone database.  If 'db' is a
1065 *	cache database, an rdataset will not be found unless it expires after
1066 *	'now'.  If 'now' is zero, then the current time will be used.
1067 *
1068 * Requires:
1069 *
1070 * \li	'db' is a valid database.
1071 *
1072 * \li	'node' is a valid node.
1073 *
1074 * \li	'rdataset' is a valid, disassociated rdataset.
1075 *
1076 * \li	'sigrdataset' is a valid, disassociated rdataset, or it is NULL.
1077 *
1078 * \li	If 'covers' != 0, 'type' must be SIG.
1079 *
1080 * \li	'type' is not a meta-RR type such as 'ANY' or 'OPT'.
1081 *
1082 * Ensures:
1083 *
1084 * \li	On success, 'rdataset' is associated with the found rdataset.
1085 *
1086 * Returns:
1087 *
1088 * \li	#ISC_R_SUCCESS
1089 * \li	#ISC_R_NOTFOUND
1090 *
1091 * \li	Other results are possible, depending upon the database
1092 *	implementation used.
1093 */
1094
1095isc_result_t
1096dns_db_allrdatasets(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
1097		    isc_stdtime_t now, dns_rdatasetiter_t **iteratorp);
1098/*%<
1099 * Make '*iteratorp' an rdataset iterator for all rdatasets at 'node' in
1100 * version 'version' of 'db'.
1101 *
1102 * Notes:
1103 *
1104 * \li	If 'version' is NULL, then the current version will be used.
1105 *
1106 * \li	The 'now' field is ignored if 'db' is a zone database.  If 'db' is a
1107 *	cache database, an rdataset will not be found unless it expires after
1108 *	'now'.  Any ANY query will not match unless at least one rdataset at
1109 *	the node expires after 'now'.  If 'now' is zero, then the current time
1110 *	will be used.
1111 *
1112 * Requires:
1113 *
1114 * \li	'db' is a valid database.
1115 *
1116 * \li	'node' is a valid node.
1117 *
1118 * \li	iteratorp != NULL && *iteratorp == NULL
1119 *
1120 * Ensures:
1121 *
1122 * \li	On success, '*iteratorp' is a valid rdataset iterator.
1123 *
1124 * Returns:
1125 *
1126 * \li	#ISC_R_SUCCESS
1127 * \li	#ISC_R_NOTFOUND
1128 *
1129 * \li	Other results are possible, depending upon the database
1130 *	implementation used.
1131 */
1132
1133isc_result_t
1134dns_db_addrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
1135		   isc_stdtime_t now, dns_rdataset_t *rdataset,
1136		   unsigned int options, dns_rdataset_t *addedrdataset);
1137/*%<
1138 * Add 'rdataset' to 'node' in version 'version' of 'db'.
1139 *
1140 * Notes:
1141 *
1142 * \li	If the database has zone semantics, the #DNS_DBADD_MERGE option is set,
1143 *	and an rdataset of the same type as 'rdataset' already exists at
1144 *	'node' then the contents of 'rdataset' will be merged with the existing
1145 *	rdataset.  If the option is not set, then rdataset will replace any
1146 *	existing rdataset of the same type.  If not merging and the
1147 *	#DNS_DBADD_FORCE option is set, then the data will update the database
1148 *	without regard to trust levels.  If not forcing the data, then the
1149 *	rdataset will only be added if its trust level is >= the trust level of
1150 *	any existing rdataset.  Forcing is only meaningful for cache databases.
1151 *	If #DNS_DBADD_EXACT is set then there must be no rdata in common between
1152 *	the old and new rdata sets.  If #DNS_DBADD_EXACTTTL is set then both
1153 *	the old and new rdata sets must have the same ttl.
1154 *
1155 * \li	The 'now' field is ignored if 'db' is a zone database.  If 'db' is
1156 *	a cache database, then the added rdataset will expire no later than
1157 *	now + rdataset->ttl.
1158 *
1159 * \li	If 'addedrdataset' is not NULL, then it will be attached to the
1160 *	resulting new rdataset in the database, or to the existing data if
1161 *	the existing data was better.
1162 *
1163 * Requires:
1164 *
1165 * \li	'db' is a valid database.
1166 *
1167 * \li	'node' is a valid node.
1168 *
1169 * \li	'rdataset' is a valid, associated rdataset with the same class
1170 *	as 'db'.
1171 *
1172 * \li	'addedrdataset' is NULL, or a valid, unassociated rdataset.
1173 *
1174 * \li	The database has zone semantics and 'version' is a valid
1175 *	read-write version, or the database has cache semantics
1176 *	and version is NULL.
1177 *
1178 * \li	If the database has cache semantics, the #DNS_DBADD_MERGE option must
1179 *	not be set.
1180 *
1181 * Returns:
1182 *
1183 * \li	#ISC_R_SUCCESS
1184 * \li	#DNS_R_UNCHANGED			The operation did not change anything.
1185 * \li	#ISC_R_NOMEMORY
1186 * \li	#DNS_R_NOTEXACT
1187 *
1188 * \li	Other results are possible, depending upon the database
1189 *	implementation used.
1190 */
1191
1192isc_result_t
1193dns_db_subtractrdataset(dns_db_t *db, dns_dbnode_t *node,
1194			dns_dbversion_t *version, dns_rdataset_t *rdataset,
1195			unsigned int options, dns_rdataset_t *newrdataset);
1196/*%<
1197 * Remove any rdata in 'rdataset' from 'node' in version 'version' of
1198 * 'db'.
1199 *
1200 * Notes:
1201 *
1202 * \li	If 'newrdataset' is not NULL, then it will be attached to the
1203 *	resulting new rdataset in the database, unless the rdataset has
1204 *	become nonexistent.  If DNS_DBSUB_EXACT is set then all elements
1205 *	of 'rdataset' must exist at 'node'.
1206 *
1207 * Requires:
1208 *
1209 * \li	'db' is a valid database.
1210 *
1211 * \li	'node' is a valid node.
1212 *
1213 * \li	'rdataset' is a valid, associated rdataset with the same class
1214 *	as 'db'.
1215 *
1216 * \li	'newrdataset' is NULL, or a valid, unassociated rdataset.
1217 *
1218 * \li	The database has zone semantics and 'version' is a valid
1219 *	read-write version.
1220 *
1221 * Returns:
1222 *
1223 * \li	#ISC_R_SUCCESS
1224 * \li	#DNS_R_UNCHANGED			The operation did not change anything.
1225 * \li	#DNS_R_NXRRSET			All rdata of the same type as those
1226 *					in 'rdataset' have been deleted.
1227 * \li	#DNS_R_NOTEXACT			Some part of 'rdataset' did not
1228 *					exist and DNS_DBSUB_EXACT was set.
1229 *
1230 * \li	Other results are possible, depending upon the database
1231 *	implementation used.
1232 */
1233
1234isc_result_t
1235dns_db_deleterdataset(dns_db_t *db, dns_dbnode_t *node,
1236		      dns_dbversion_t *version, dns_rdatatype_t type,
1237		      dns_rdatatype_t covers);
1238/*%<
1239 * Make it so that no rdataset of type 'type' exists at 'node' in version
1240 * version 'version' of 'db'.
1241 *
1242 * Notes:
1243 *
1244 * \li	If 'type' is dns_rdatatype_any, then no rdatasets will exist in
1245 *	'version' (provided that the dns_db_deleterdataset() isn't followed
1246 *	by one or more dns_db_addrdataset() calls).
1247 *
1248 * Requires:
1249 *
1250 * \li	'db' is a valid database.
1251 *
1252 * \li	'node' is a valid node.
1253 *
1254 * \li	The database has zone semantics and 'version' is a valid
1255 *	read-write version, or the database has cache semantics
1256 *	and version is NULL.
1257 *
1258 * \li	'type' is not a meta-RR type, except for dns_rdatatype_any, which is
1259 *	allowed.
1260 *
1261 * \li	If 'covers' != 0, 'type' must be SIG.
1262 *
1263 * Returns:
1264 *
1265 * \li	#ISC_R_SUCCESS
1266 * \li	#DNS_R_UNCHANGED			No rdatasets of 'type' existed before
1267 *					the operation was attempted.
1268 *
1269 * \li	Other results are possible, depending upon the database
1270 *	implementation used.
1271 */
1272
1273isc_result_t
1274dns_db_getsoaserial(dns_db_t *db, dns_dbversion_t *ver, isc_uint32_t *serialp);
1275/*%<
1276 * Get the current SOA serial number from a zone database.
1277 *
1278 * Requires:
1279 * \li	'db' is a valid database with zone semantics.
1280 * \li	'ver' is a valid version.
1281 */
1282
1283void
1284dns_db_overmem(dns_db_t *db, isc_boolean_t overmem);
1285/*%<
1286 * Enable / disable aggressive cache cleaning.
1287 */
1288
1289unsigned int
1290dns_db_nodecount(dns_db_t *db);
1291/*%<
1292 * Count the number of nodes in 'db'.
1293 *
1294 * Requires:
1295 *
1296 * \li	'db' is a valid database.
1297 *
1298 * Returns:
1299 * \li	The number of nodes in the database
1300 */
1301
1302void
1303dns_db_settask(dns_db_t *db, isc_task_t *task);
1304/*%<
1305 * If task is set then the final detach maybe performed asynchronously.
1306 *
1307 * Requires:
1308 * \li	'db' is a valid database.
1309 * \li	'task' to be valid or NULL.
1310 */
1311
1312isc_boolean_t
1313dns_db_ispersistent(dns_db_t *db);
1314/*%<
1315 * Is 'db' persistent?  A persistent database does not need to be loaded
1316 * from disk or written to disk.
1317 *
1318 * Requires:
1319 *
1320 * \li	'db' is a valid database.
1321 *
1322 * Returns:
1323 * \li	#ISC_TRUE	'db' is persistent.
1324 * \li	#ISC_FALSE	'db' is not persistent.
1325 */
1326
1327isc_result_t
1328dns_db_register(const char *name, dns_dbcreatefunc_t create, void *driverarg,
1329		isc_mem_t *mctx, dns_dbimplementation_t **dbimp);
1330
1331/*%<
1332 * Register a new database implementation and add it to the list of
1333 * supported implementations.
1334 *
1335 * Requires:
1336 *
1337 * \li 	'name' is not NULL
1338 * \li	'order' is a valid function pointer
1339 * \li	'mctx' is a valid memory context
1340 * \li	dbimp != NULL && *dbimp == NULL
1341 *
1342 * Returns:
1343 * \li	#ISC_R_SUCCESS	The registration succeeded
1344 * \li	#ISC_R_NOMEMORY	Out of memory
1345 * \li	#ISC_R_EXISTS	A database implementation with the same name exists
1346 *
1347 * Ensures:
1348 *
1349 * \li	*dbimp points to an opaque structure which must be passed to
1350 *	dns_db_unregister().
1351 */
1352
1353void
1354dns_db_unregister(dns_dbimplementation_t **dbimp);
1355/*%<
1356 * Remove a database implementation from the list of supported
1357 * implementations.  No databases of this type can be active when this
1358 * is called.
1359 *
1360 * Requires:
1361 * \li 	dbimp != NULL && *dbimp == NULL
1362 *
1363 * Ensures:
1364 *
1365 * \li	Any memory allocated in *dbimp will be freed.
1366 */
1367
1368isc_result_t
1369dns_db_getoriginnode(dns_db_t *db, dns_dbnode_t **nodep);
1370/*%<
1371 * Get the origin DB node corresponding to the DB's zone.  This function
1372 * should typically succeed unless the underlying DB implementation doesn't
1373 * support the feature.
1374 *
1375 * Requires:
1376 *
1377 * \li	'db' is a valid zone database.
1378 * \li	'nodep' != NULL && '*nodep' == NULL
1379 *
1380 * Ensures:
1381 * \li	On success, '*nodep' will point to the DB node of the zone's origin.
1382 *
1383 * Returns:
1384 * \li	#ISC_R_SUCCESS
1385 * \li	#ISC_R_NOTFOUND - the DB implementation does not support this feature.
1386 */
1387
1388isc_result_t
1389dns_db_getnsec3parameters(dns_db_t *db, dns_dbversion_t *version,
1390			  dns_hash_t *hash, isc_uint8_t *flags,
1391			  isc_uint16_t *interations,
1392			  unsigned char *salt, size_t *salt_length);
1393/*%<
1394 * Get the NSEC3 parameters that are associated with this zone.
1395 *
1396 * Requires:
1397 * \li	'db' is a valid zone database.
1398 *
1399 * Returns:
1400 * \li	#ISC_R_SUCCESS
1401 * \li	#ISC_R_NOTFOUND - the DB implementation does not support this feature
1402 *			  or this zone does not have NSEC3 records.
1403 */
1404
1405isc_result_t
1406dns_db_findnsec3node(dns_db_t *db, dns_name_t *name,
1407		     isc_boolean_t create, dns_dbnode_t **nodep);
1408/*%<
1409 * Find the NSEC3 node with name 'name'.
1410 *
1411 * Notes:
1412 * \li	If 'create' is ISC_TRUE and no node with name 'name' exists, then
1413 *	such a node will be created.
1414 *
1415 * Requires:
1416 *
1417 * \li	'db' is a valid database.
1418 *
1419 * \li	'name' is a valid, non-empty, absolute name.
1420 *
1421 * \li	nodep != NULL && *nodep == NULL
1422 *
1423 * Ensures:
1424 *
1425 * \li	On success, *nodep is attached to the node with name 'name'.
1426 *
1427 * Returns:
1428 *
1429 * \li	#ISC_R_SUCCESS
1430 * \li	#ISC_R_NOTFOUND			If !create and name not found.
1431 * \li	#ISC_R_NOMEMORY			Can only happen if create is ISC_TRUE.
1432 *
1433 * \li	Other results are possible, depending upon the database
1434 *	implementation used.
1435 */
1436
1437isc_result_t
1438dns_db_setsigningtime(dns_db_t *db, dns_rdataset_t *rdataset,
1439		      isc_stdtime_t resign);
1440/*%<
1441 * Sets the re-signing time associated with 'rdataset' to 'resign'.
1442 *
1443 * Requires:
1444 * \li	'db' is a valid zone database.
1445 * \li	'rdataset' is or is to be associated with 'db'.
1446 * \li  'rdataset' is not pending removed from the heap via an
1447 *       uncommitted call to dns_db_resigned().
1448 *
1449 * Returns:
1450 * \li	#ISC_R_SUCCESS
1451 * \li	#ISC_R_NOMEMORY
1452 * \li	#ISC_R_NOTIMPLEMENTED - Not supported by this DB implementation.
1453 */
1454
1455isc_result_t
1456dns_db_getsigningtime(dns_db_t *db, dns_rdataset_t *rdataset, dns_name_t *name);
1457/*%<
1458 * Return the rdataset with the earliest signing time in the zone.
1459 * Note: the rdataset is version agnostic.
1460 *
1461 * Requires:
1462 * \li	'db' is a valid zone database.
1463 * \li	'rdataset' to be initialized but not associated.
1464 * \li	'name' to be NULL or have a buffer associated with it.
1465 *
1466 * Returns:
1467 * \li	#ISC_R_SUCCESS
1468 * \li	#ISC_R_NOTFOUND - No dataset exists.
1469 */
1470
1471void
1472dns_db_resigned(dns_db_t *db, dns_rdataset_t *rdataset,
1473		dns_dbversion_t *version);
1474/*%<
1475 * Mark 'rdataset' as not being available to be returned by
1476 * dns_db_getsigningtime().  If the changes associated with 'version'
1477 * are committed this will be permanent.  If the version is not committed
1478 * this change will be rolled back when the version is closed.  Until
1479 * 'version' is either committed or rolled back, 'rdataset' can no longer
1480 * be acted upon by dns_db_setsigningtime().
1481 *
1482 * Requires:
1483 * \li	'db' is a valid zone database.
1484 * \li	'rdataset' to be associated with 'db'.
1485 * \li	'version' to be open for writing.
1486 */
1487
1488dns_stats_t *
1489dns_db_getrrsetstats(dns_db_t *db);
1490/*%<
1491 * Get statistics information counting RRsets stored in the DB, when available.
1492 * The statistics may not be available depending on the DB implementation.
1493 *
1494 * Requires:
1495 *
1496 * \li	'db' is a valid database (zone or cache).
1497 *
1498 * Returns:
1499 * \li	when available, a pointer to a statistics object created by
1500 *	dns_rdatasetstats_create(); otherwise NULL.
1501 */
1502
1503void
1504dns_db_rpz_enabled(dns_db_t *db, dns_rpz_st_t *st);
1505/*%<
1506 * See if a policy database has DNS_RPZ_TYPE_IP, DNS_RPZ_TYPE_NSIP, or
1507 * DNS_RPZ_TYPE_NSDNAME records.
1508 */
1509
1510isc_result_t
1511dns_db_rpz_findips(dns_rpz_zone_t *rpz, dns_rpz_type_t rpz_type,
1512		   dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *version,
1513		   dns_rdataset_t *ardataset, dns_rpz_st_t *st,
1514		   dns_name_t *query_qname);
1515/*%<
1516 * Search the CDIR block tree of a response policy tree of trees for the best
1517 * match to any of the IP addresses in an A or AAAA rdataset.
1518 *
1519 * Requires:
1520 * \li	search in policy zone 'rpz' for a match of 'rpz_type' either
1521 *	    DNS_RPZ_TYPE_IP or DNS_RPZ_TYPE_NSIP
1522 * \li	'zone' and 'db' are the database corresponding to 'rpz'
1523 * \li	'version' is the required version of the database
1524 * \li	'ardataset' is an A or AAAA rdataset of addresses to check
1525 * \li	'found' specifies the previous best match if any or
1526 *	    or NULL, an empty name, 0, DNS_RPZ_POLICY_MISS, and 0
1527 *
1528 * Returns:
1529 * \li	#ISC_R_SUCCESS
1530 * \li	#ISC_R_UNEXPECTED
1531 */
1532
1533ISC_LANG_ENDDECLS
1534
1535#endif /* DNS_DB_H */