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

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 1535 lines · 299 code · 80 blank · 1156 comment · 0 complexity · 4c37c0cfbacd8363bfd27aa81457d9ae MD5 · raw file

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