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

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