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