contrib/bind9/lib/dns/include/dns/db.h

   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 */