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