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