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