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