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

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