2 * Copyright (C) 2004-2009, 2011-2013 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2003 Internet Software Consortium.
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.
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.
18 /* $Id: db.h,v 1.107.4.1 2011/10/23 20:12:08 vjs Exp $ */
29 * The DNS DB interface allows named rdatasets to be stored and retrieved.
31 * The dns_db_t type is like a "virtual class". To actually use
32 * DBs, an implementation of the class is required.
37 * \li The module ensures appropriate synchronization of data structures it
38 * creates and manipulates.
41 * \li No anticipated impact.
47 * \li No anticipated impact.
58 #include <isc/magic.h>
59 #include <isc/ondestroy.h>
60 #include <isc/stdtime.h>
62 #include <dns/clientinfo.h>
63 #include <dns/fixedname.h>
65 #include <dns/rdata.h>
66 #include <dns/rdataset.h>
68 #include <dns/types.h>
76 typedef struct dns_dbmethods {
77 void (*attach)(dns_db_t *source, dns_db_t **targetp);
78 void (*detach)(dns_db_t **dbp);
79 isc_result_t (*beginload)(dns_db_t *db, dns_addrdatasetfunc_t *addp,
80 dns_dbload_t **dbloadp);
81 isc_result_t (*endload)(dns_db_t *db, dns_dbload_t **dbloadp);
82 isc_result_t (*dump)(dns_db_t *db, dns_dbversion_t *version,
84 dns_masterformat_t masterformat);
85 void (*currentversion)(dns_db_t *db,
86 dns_dbversion_t **versionp);
87 isc_result_t (*newversion)(dns_db_t *db,
88 dns_dbversion_t **versionp);
89 void (*attachversion)(dns_db_t *db, dns_dbversion_t *source,
90 dns_dbversion_t **targetp);
91 void (*closeversion)(dns_db_t *db,
92 dns_dbversion_t **versionp,
93 isc_boolean_t commit);
94 isc_result_t (*findnode)(dns_db_t *db, dns_name_t *name,
96 dns_dbnode_t **nodep);
97 isc_result_t (*find)(dns_db_t *db, dns_name_t *name,
98 dns_dbversion_t *version,
99 dns_rdatatype_t type, unsigned int options,
101 dns_dbnode_t **nodep, dns_name_t *foundname,
102 dns_rdataset_t *rdataset,
103 dns_rdataset_t *sigrdataset);
104 isc_result_t (*findzonecut)(dns_db_t *db, dns_name_t *name,
105 unsigned int options, isc_stdtime_t now,
106 dns_dbnode_t **nodep,
107 dns_name_t *foundname,
108 dns_rdataset_t *rdataset,
109 dns_rdataset_t *sigrdataset);
110 void (*attachnode)(dns_db_t *db,
111 dns_dbnode_t *source,
112 dns_dbnode_t **targetp);
113 void (*detachnode)(dns_db_t *db,
114 dns_dbnode_t **targetp);
115 isc_result_t (*expirenode)(dns_db_t *db, dns_dbnode_t *node,
117 void (*printnode)(dns_db_t *db, dns_dbnode_t *node,
119 isc_result_t (*createiterator)(dns_db_t *db, unsigned int options,
120 dns_dbiterator_t **iteratorp);
121 isc_result_t (*findrdataset)(dns_db_t *db, dns_dbnode_t *node,
122 dns_dbversion_t *version,
123 dns_rdatatype_t type,
124 dns_rdatatype_t covers,
126 dns_rdataset_t *rdataset,
127 dns_rdataset_t *sigrdataset);
128 isc_result_t (*allrdatasets)(dns_db_t *db, dns_dbnode_t *node,
129 dns_dbversion_t *version,
131 dns_rdatasetiter_t **iteratorp);
132 isc_result_t (*addrdataset)(dns_db_t *db, dns_dbnode_t *node,
133 dns_dbversion_t *version,
135 dns_rdataset_t *rdataset,
136 unsigned int options,
137 dns_rdataset_t *addedrdataset);
138 isc_result_t (*subtractrdataset)(dns_db_t *db, dns_dbnode_t *node,
139 dns_dbversion_t *version,
140 dns_rdataset_t *rdataset,
141 unsigned int options,
142 dns_rdataset_t *newrdataset);
143 isc_result_t (*deleterdataset)(dns_db_t *db, dns_dbnode_t *node,
144 dns_dbversion_t *version,
145 dns_rdatatype_t type,
146 dns_rdatatype_t covers);
147 isc_boolean_t (*issecure)(dns_db_t *db);
148 unsigned int (*nodecount)(dns_db_t *db);
149 isc_boolean_t (*ispersistent)(dns_db_t *db);
150 void (*overmem)(dns_db_t *db, isc_boolean_t overmem);
151 void (*settask)(dns_db_t *db, isc_task_t *);
152 isc_result_t (*getoriginnode)(dns_db_t *db, dns_dbnode_t **nodep);
153 void (*transfernode)(dns_db_t *db, dns_dbnode_t **sourcep,
154 dns_dbnode_t **targetp);
155 isc_result_t (*getnsec3parameters)(dns_db_t *db,
156 dns_dbversion_t *version,
159 isc_uint16_t *iterations,
162 isc_result_t (*findnsec3node)(dns_db_t *db, dns_name_t *name,
163 isc_boolean_t create,
164 dns_dbnode_t **nodep);
165 isc_result_t (*setsigningtime)(dns_db_t *db,
166 dns_rdataset_t *rdataset,
167 isc_stdtime_t resign);
168 isc_result_t (*getsigningtime)(dns_db_t *db,
169 dns_rdataset_t *rdataset,
171 void (*resigned)(dns_db_t *db, dns_rdataset_t *rdataset,
172 dns_dbversion_t *version);
173 isc_boolean_t (*isdnssec)(dns_db_t *db);
174 dns_stats_t *(*getrrsetstats)(dns_db_t *db);
175 isc_result_t (*rpz_enabled)(dns_db_t *db, dns_rpz_st_t *st);
176 void (*rpz_findips)(dns_rpz_zone_t *rpz,
177 dns_rpz_type_t rpz_type,
178 dns_zone_t *zone, dns_db_t *db,
179 dns_dbversion_t *version,
180 dns_rdataset_t *ardataset,
182 dns_name_t *query_qname);
183 isc_result_t (*findnodeext)(dns_db_t *db, dns_name_t *name,
184 isc_boolean_t create,
185 dns_clientinfomethods_t *methods,
186 dns_clientinfo_t *clientinfo,
187 dns_dbnode_t **nodep);
188 isc_result_t (*findext)(dns_db_t *db, dns_name_t *name,
189 dns_dbversion_t *version,
190 dns_rdatatype_t type, unsigned int options,
192 dns_dbnode_t **nodep, dns_name_t *foundname,
193 dns_clientinfomethods_t *methods,
194 dns_clientinfo_t *clientinfo,
195 dns_rdataset_t *rdataset,
196 dns_rdataset_t *sigrdataset);
200 (*dns_dbcreatefunc_t)(isc_mem_t *mctx, dns_name_t *name,
201 dns_dbtype_t type, dns_rdataclass_t rdclass,
202 unsigned int argc, char *argv[], void *driverarg,
205 #define DNS_DB_MAGIC ISC_MAGIC('D','N','S','D')
206 #define DNS_DB_VALID(db) ISC_MAGIC_VALID(db, DNS_DB_MAGIC)
209 * This structure is actually just the common prefix of a DNS db
210 * implementation's version of a dns_db_t.
212 * Direct use of this structure by clients is forbidden. DB implementations
213 * may change the structure. 'magic' must be DNS_DB_MAGIC for any of the
214 * dns_db_ routines to work. DB implementations must maintain all DB
219 unsigned int impmagic;
220 dns_dbmethods_t * methods;
221 isc_uint16_t attributes;
222 dns_rdataclass_t rdclass;
224 isc_ondestroy_t ondest;
228 #define DNS_DBATTR_CACHE 0x01
229 #define DNS_DBATTR_STUB 0x02
233 * Options that can be specified for dns_db_find().
235 #define DNS_DBFIND_GLUEOK 0x0001
236 #define DNS_DBFIND_VALIDATEGLUE 0x0002
237 #define DNS_DBFIND_NOWILD 0x0004
238 #define DNS_DBFIND_PENDINGOK 0x0008
239 #define DNS_DBFIND_NOEXACT 0x0010
240 #define DNS_DBFIND_FORCENSEC 0x0020
241 #define DNS_DBFIND_COVERINGNSEC 0x0040
242 #define DNS_DBFIND_FORCENSEC3 0x0080
243 #define DNS_DBFIND_ADDITIONALOK 0x0100
248 * Options that can be specified for dns_db_addrdataset().
250 #define DNS_DBADD_MERGE 0x01
251 #define DNS_DBADD_FORCE 0x02
252 #define DNS_DBADD_EXACT 0x04
253 #define DNS_DBADD_EXACTTTL 0x08
257 * Options that can be specified for dns_db_subtractrdataset().
259 #define DNS_DBSUB_EXACT 0x01
265 #define DNS_DB_RELATIVENAMES 0x1
266 #define DNS_DB_NSEC3ONLY 0x2
267 #define DNS_DB_NONSEC3 0x4
279 dns_db_create(isc_mem_t *mctx, const char *db_type, dns_name_t *origin,
280 dns_dbtype_t type, dns_rdataclass_t rdclass,
281 unsigned int argc, char *argv[], dns_db_t **dbp);
283 * Create a new database using implementation 'db_type'.
286 * \li All names in the database must be subdomains of 'origin' and in class
287 * 'rdclass'. The database makes its own copy of the origin, so the
288 * caller may do whatever they like with 'origin' and its storage once the
291 * \li DB implementation-specific parameters are passed using argc and argv.
295 * \li dbp != NULL and *dbp == NULL
297 * \li 'origin' is a valid absolute domain name.
299 * \li mctx is a valid memory context
303 * \li A copy of 'origin' has been made for the databases use, and the
304 * caller is free to do whatever they want with the name and storage
305 * associated with 'origin'.
310 * \li #ISC_R_NOMEMORY
311 * \li #ISC_R_NOTFOUND db_type not found
313 * \li Many other errors are possible, depending on what db_type was
318 dns_db_attach(dns_db_t *source, dns_db_t **targetp);
320 * Attach *targetp to source.
324 * \li 'source' is a valid database.
326 * \li 'targetp' points to a NULL dns_db_t *.
330 * \li *targetp is attached to source.
334 dns_db_detach(dns_db_t **dbp);
336 * Detach *dbp from its database.
340 * \li 'dbp' points to a valid database.
346 * \li If '*dbp' is the last reference to the database,
347 * all resources used by the database will be freed
351 dns_db_ondestroy(dns_db_t *db, isc_task_t *task, isc_event_t **eventp);
353 * Causes 'eventp' to be sent to be sent to 'task' when the database is
356 * Note; ownership of the eventp is taken from the caller (and *eventp is
357 * set to NULL). The sender field of the event is set to 'db' before it is
362 dns_db_iscache(dns_db_t *db);
364 * Does 'db' have cache semantics?
368 * \li 'db' is a valid database.
371 * \li #ISC_TRUE 'db' has cache semantics
372 * \li #ISC_FALSE otherwise
376 dns_db_iszone(dns_db_t *db);
378 * Does 'db' have zone semantics?
382 * \li 'db' is a valid database.
385 * \li #ISC_TRUE 'db' has zone semantics
386 * \li #ISC_FALSE otherwise
390 dns_db_isstub(dns_db_t *db);
392 * Does 'db' have stub semantics?
396 * \li 'db' is a valid database.
399 * \li #ISC_TRUE 'db' has zone semantics
400 * \li #ISC_FALSE otherwise
404 dns_db_issecure(dns_db_t *db);
410 * \li 'db' is a valid database with zone semantics.
413 * \li #ISC_TRUE 'db' is secure.
414 * \li #ISC_FALSE 'db' is not secure.
418 dns_db_isdnssec(dns_db_t *db);
420 * Is 'db' secure or partially secure?
424 * \li 'db' is a valid database with zone semantics.
427 * \li #ISC_TRUE 'db' is secure or is partially.
428 * \li #ISC_FALSE 'db' is not secure.
432 dns_db_origin(dns_db_t *db);
434 * The origin of the database.
436 * Note: caller must not try to change this name.
440 * \li 'db' is a valid database.
444 * \li The origin of the database.
448 dns_db_class(dns_db_t *db);
450 * The class of the database.
454 * \li 'db' is a valid database.
458 * \li The class of the database.
462 dns_db_beginload(dns_db_t *db, dns_addrdatasetfunc_t *addp,
463 dns_dbload_t **dbloadp);
465 * Begin loading 'db'.
469 * \li 'db' is a valid database.
471 * \li This is the first attempt to load 'db'.
473 * \li addp != NULL && *addp == NULL
475 * \li dbloadp != NULL && *dbloadp == NULL
479 * \li On success, *addp will be a valid dns_addrdatasetfunc_t suitable
480 * for loading 'db'. *dbloadp will be a valid DB load context which
481 * should be used as 'arg' when *addp is called.
486 * \li #ISC_R_NOMEMORY
488 * \li Other results are possible, depending upon the database
489 * implementation used, syntax errors in the master file, etc.
493 dns_db_endload(dns_db_t *db, dns_dbload_t **dbloadp);
495 * Finish loading 'db'.
499 * \li 'db' is a valid database that is being loaded.
501 * \li dbloadp != NULL and *dbloadp is a valid database load context.
505 * \li *dbloadp == NULL
510 * \li #ISC_R_NOMEMORY
512 * \li Other results are possible, depending upon the database
513 * implementation used, syntax errors in the master file, etc.
517 dns_db_load(dns_db_t *db, const char *filename);
520 dns_db_load2(dns_db_t *db, const char *filename, dns_masterformat_t format);
523 dns_db_load3(dns_db_t *db, const char *filename, dns_masterformat_t format,
524 unsigned int options);
526 * Load master file 'filename' into 'db'.
529 * \li This routine is equivalent to calling
532 * dns_db_beginload();
533 * dns_master_loadfile();
539 * \li 'db' is a valid database.
541 * \li This is the first attempt to load 'db'.
546 * \li #ISC_R_NOMEMORY
548 * \li Other results are possible, depending upon the database
549 * implementation used, syntax errors in the master file, etc.
553 dns_db_dump(dns_db_t *db, dns_dbversion_t *version, const char *filename);
556 dns_db_dump2(dns_db_t *db, dns_dbversion_t *version, const char *filename,
557 dns_masterformat_t masterformat);
559 * Dump version 'version' of 'db' to master file 'filename'.
563 * \li 'db' is a valid database.
565 * \li 'version' is a valid version.
570 * \li #ISC_R_NOMEMORY
572 * \li Other results are possible, depending upon the database
573 * implementation used, OS file errors, etc.
581 dns_db_currentversion(dns_db_t *db, dns_dbversion_t **versionp);
583 * Open the current version for reading.
587 * \li 'db' is a valid database with zone semantics.
589 * \li versionp != NULL && *verisonp == NULL
593 * \li On success, '*versionp' is attached to the current version.
598 dns_db_newversion(dns_db_t *db, dns_dbversion_t **versionp);
600 * Open a new version for reading and writing.
604 * \li 'db' is a valid database with zone semantics.
606 * \li versionp != NULL && *verisonp == NULL
610 * \li On success, '*versionp' is attached to the current version.
615 * \li #ISC_R_NOMEMORY
617 * \li Other results are possible, depending upon the database
618 * implementation used.
622 dns_db_attachversion(dns_db_t *db, dns_dbversion_t *source,
623 dns_dbversion_t **targetp);
625 * Attach '*targetp' to 'source'.
629 * \li 'db' is a valid database with zone semantics.
631 * \li source is a valid open version
633 * \li targetp != NULL && *targetp == NULL
637 * \li '*targetp' is attached to source.
641 dns_db_closeversion(dns_db_t *db, dns_dbversion_t **versionp,
642 isc_boolean_t commit);
644 * Close version '*versionp'.
646 * Note: if '*versionp' is a read-write version and 'commit' is ISC_TRUE,
647 * then all changes made in the version will take effect, otherwise they
648 * will be rolled back. The value of 'commit' is ignored for read-only
653 * \li 'db' is a valid database with zone semantics.
655 * \li '*versionp' refers to a valid version.
657 * \li If committing a writable version, then there must be no other
658 * outstanding references to the version (e.g. an active rdataset
663 * \li *versionp == NULL
665 * \li If *versionp is a read-write version, and commit is ISC_TRUE, then
666 * the version will become the current version. If !commit, then all
667 * changes made in the version will be undone, and the version will
668 * not become the current version.
676 dns_db_findnode(dns_db_t *db, dns_name_t *name, isc_boolean_t create,
677 dns_dbnode_t **nodep);
680 dns_db_findnodeext(dns_db_t *db, dns_name_t *name, isc_boolean_t create,
681 dns_clientinfomethods_t *methods,
682 dns_clientinfo_t *clientinfo, dns_dbnode_t **nodep);
684 * Find the node with name 'name'.
686 * dns_db_findnodeext() (findnode extended) also accepts parameters
687 * 'methods' and 'clientinfo', which, when provided, enable the database to
688 * retreive information about the client from the caller, and modify its
689 * response on the basis of that information.
692 * \li If 'create' is ISC_TRUE and no node with name 'name' exists, then
693 * such a node will be created.
695 * \li This routine is for finding or creating a node with the specified
696 * name. There are no partial matches. It is not suitable for use
697 * in building responses to ordinary DNS queries; clients which wish
698 * to do that should use dns_db_find() instead.
702 * \li 'db' is a valid database.
704 * \li 'name' is a valid, non-empty, absolute name.
706 * \li nodep != NULL && *nodep == NULL
710 * \li On success, *nodep is attached to the node with name 'name'.
715 * \li #ISC_R_NOTFOUND If !create and name not found.
716 * \li #ISC_R_NOMEMORY Can only happen if create is ISC_TRUE.
718 * \li Other results are possible, depending upon the database
719 * implementation used.
723 dns_db_find(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version,
724 dns_rdatatype_t type, unsigned int options, isc_stdtime_t now,
725 dns_dbnode_t **nodep, dns_name_t *foundname,
726 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
729 dns_db_findext(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version,
730 dns_rdatatype_t type, unsigned int options, isc_stdtime_t now,
731 dns_dbnode_t **nodep, dns_name_t *foundname,
732 dns_clientinfomethods_t *methods, dns_clientinfo_t *clientinfo,
733 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
735 * Find the best match for 'name' and 'type' in version 'version' of 'db'.
737 * dns_db_findext() (find extended) also accepts parameters 'methods'
738 * and 'clientinfo', which when provided enable the database to retreive
739 * information about the client from the caller, and modify its response
740 * on the basis of this information.
744 * \li If type == dns_rdataset_any, then rdataset will not be bound.
746 * \li If 'options' does not have #DNS_DBFIND_GLUEOK set, then no glue will
747 * be returned. For zone databases, glue is as defined in RFC2181.
748 * For cache databases, glue is any rdataset with a trust of
751 * \li If 'options' does not have #DNS_DBFIND_ADDITIONALOK set, then no
752 * additional records will be returned. Only caches can have
753 * rdataset with trust dns_trust_additional.
755 * \li If 'options' does not have #DNS_DBFIND_PENDINGOK set, then no
756 * pending data will be returned. This option is only meaningful for
759 * \li If the #DNS_DBFIND_NOWILD option is set, then wildcard matching will
760 * be disabled. This option is only meaningful for zone databases.
762 * \li If the #DNS_DBFIND_FORCENSEC option is set, the database is assumed to
763 * have NSEC records, and these will be returned when appropriate. This
764 * is only necessary when querying a database that was not secure
767 * \li If the DNS_DBFIND_COVERINGNSEC option is set, then look for a
768 * NSEC record that potentially covers 'name' if a answer cannot
769 * be found. Note the returned NSEC needs to be checked to ensure
770 * that it is correct. This only affects answers returned from the
773 * \li In the #DNS_DBFIND_FORCENSEC3 option is set, then we are looking
774 * in the NSEC3 tree and not the main tree. Without this option being
775 * set NSEC3 records will not be found.
777 * \li To respond to a query for SIG records, the caller should create a
778 * rdataset iterator and extract the signatures from each rdataset.
780 * \li Making queries of type ANY with #DNS_DBFIND_GLUEOK is not recommended,
781 * because the burden of determining whether a given rdataset is valid
782 * glue or not falls upon the caller.
784 * \li The 'now' field is ignored if 'db' is a zone database. If 'db' is a
785 * cache database, an rdataset will not be found unless it expires after
786 * 'now'. Any ANY query will not match unless at least one rdataset at
787 * the node expires after 'now'. If 'now' is zero, then the current time
792 * \li 'db' is a valid database.
794 * \li 'type' is not SIG, or a meta-RR type other than 'ANY' (e.g. 'OPT').
796 * \li 'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL.
798 * \li 'foundname' is a valid name with a dedicated buffer.
800 * \li 'rdataset' is NULL, or is a valid unassociated rdataset.
803 * on a non-error completion:
805 * \li If nodep != NULL, then it is bound to the found node.
807 * \li If foundname != NULL, then it contains the full name of the
810 * \li If rdataset != NULL and type != dns_rdatatype_any, then
811 * rdataset is bound to the found rdataset.
813 * Non-error results are:
815 * \li #ISC_R_SUCCESS The desired node and type were
818 * \li #DNS_R_WILDCARD The desired node and type were
819 * found after performing
820 * wildcard matching. This is
821 * only returned if the
822 * #DNS_DBFIND_INDICATEWILD
823 * option is set; otherwise
824 * #ISC_R_SUCCESS is returned.
826 * \li #DNS_R_GLUE The desired node and type were
827 * found, but are glue. This
828 * result can only occur if
829 * the DNS_DBFIND_GLUEOK option
830 * is set. This result can only
831 * occur if 'db' is a zone
832 * database. If type ==
833 * dns_rdatatype_any, then the
834 * node returned may contain, or
835 * consist entirely of invalid
836 * glue (i.e. data occluded by a
837 * zone cut). The caller must
838 * take care not to return invalid
841 * \li #DNS_R_DELEGATION The data requested is beneath
842 * a zone cut. node, foundname,
843 * and rdataset reference the
844 * NS RRset of the zone cut.
845 * If 'db' is a cache database,
846 * then this is the deepest known
849 * \li #DNS_R_ZONECUT type == dns_rdatatype_any, and
850 * the desired node is a zonecut.
851 * The caller must take care not
852 * to return inappropriate glue
853 * to a client. This result can
854 * only occur if 'db' is a zone
855 * database and DNS_DBFIND_GLUEOK
858 * \li #DNS_R_DNAME The data requested is beneath
859 * a DNAME. node, foundname,
860 * and rdataset reference the
863 * \li #DNS_R_CNAME The rdataset requested was not
864 * found, but there is a CNAME
865 * at the desired name. node,
866 * foundname, and rdataset
867 * reference the CNAME RRset.
869 * \li #DNS_R_NXDOMAIN The desired name does not
872 * \li #DNS_R_NXRRSET The desired name exists, but
873 * the desired type does not.
875 * \li #ISC_R_NOTFOUND The desired name does not
876 * exist, and no delegation could
877 * be found. This result can only
878 * occur if 'db' is a cache
879 * database. The caller should
880 * use its nameserver(s) of last
881 * resort (e.g. root hints).
883 * \li #DNS_R_NCACHENXDOMAIN The desired name does not
884 * exist. 'node' is bound to the
885 * cache node with the desired
886 * name, and 'rdataset' contains
887 * the negative caching proof.
889 * \li #DNS_R_NCACHENXRRSET The desired type does not
890 * exist. 'node' is bound to the
891 * cache node with the desired
892 * name, and 'rdataset' contains
893 * the negative caching proof.
895 * \li #DNS_R_EMPTYNAME The name exists but there is
896 * no data at the name.
898 * \li #DNS_R_COVERINGNSEC The returned data is a NSEC
899 * that potentially covers 'name'.
901 * \li #DNS_R_EMPTYWILD The name is a wildcard without
906 * \li #ISC_R_NOMEMORY
908 * \li #DNS_R_BADDB Data that is required to be
909 * present in the DB, e.g. an NSEC
910 * record in a secure zone, is not
913 * \li Other results are possible, and should all be treated as
918 dns_db_findzonecut(dns_db_t *db, dns_name_t *name,
919 unsigned int options, isc_stdtime_t now,
920 dns_dbnode_t **nodep, dns_name_t *foundname,
921 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
923 * Find the deepest known zonecut which encloses 'name' in 'db'.
927 * \li If the #DNS_DBFIND_NOEXACT option is set, then the zonecut returned
928 * (if any) will be the deepest known ancestor of 'name'.
930 * \li If 'now' is zero, then the current time will be used.
934 * \li 'db' is a valid database with cache semantics.
936 * \li 'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL.
938 * \li 'foundname' is a valid name with a dedicated buffer.
940 * \li 'rdataset' is NULL, or is a valid unassociated rdataset.
942 * Ensures, on a non-error completion:
944 * \li If nodep != NULL, then it is bound to the found node.
946 * \li If foundname != NULL, then it contains the full name of the
949 * \li If rdataset != NULL and type != dns_rdatatype_any, then
950 * rdataset is bound to the found rdataset.
952 * Non-error results are:
956 * \li #ISC_R_NOTFOUND
958 * \li Other results are possible, and should all be treated as
963 dns_db_attachnode(dns_db_t *db, dns_dbnode_t *source, dns_dbnode_t **targetp);
965 * Attach *targetp to source.
969 * \li 'db' is a valid database.
971 * \li 'source' is a valid node.
973 * \li 'targetp' points to a NULL dns_dbnode_t *.
977 * \li *targetp is attached to source.
981 dns_db_detachnode(dns_db_t *db, dns_dbnode_t **nodep);
983 * Detach *nodep from its node.
987 * \li 'db' is a valid database.
989 * \li 'nodep' points to a valid node.
993 * \li *nodep is NULL.
997 dns_db_transfernode(dns_db_t *db, dns_dbnode_t **sourcep,
998 dns_dbnode_t **targetp);
1000 * Transfer a node between pointer.
1002 * This is equivalent to calling dns_db_attachnode() then dns_db_detachnode().
1006 * \li 'db' is a valid database.
1008 * \li '*sourcep' is a valid node.
1010 * \li 'targetp' points to a NULL dns_dbnode_t *.
1014 * \li '*sourcep' is NULL.
1018 dns_db_expirenode(dns_db_t *db, dns_dbnode_t *node, isc_stdtime_t now);
1020 * Mark as stale all records at 'node' which expire at or before 'now'.
1022 * Note: if 'now' is zero, then the current time will be used.
1026 * \li 'db' is a valid cache database.
1028 * \li 'node' is a valid node.
1032 dns_db_printnode(dns_db_t *db, dns_dbnode_t *node, FILE *out);
1034 * Print a textual representation of the contents of the node to
1037 * Note: this function is intended for debugging, not general use.
1041 * \li 'db' is a valid database.
1043 * \li 'node' is a valid node.
1047 *** DB Iterator Creation
1051 dns_db_createiterator(dns_db_t *db, unsigned int options,
1052 dns_dbiterator_t **iteratorp);
1054 * Create an iterator for version 'version' of 'db'.
1058 * \li One or more of the following options can be set.
1059 * #DNS_DB_RELATIVENAMES
1065 * \li 'db' is a valid database.
1067 * \li iteratorp != NULL && *iteratorp == NULL
1071 * \li On success, *iteratorp will be a valid database iterator.
1075 * \li #ISC_R_SUCCESS
1076 * \li #ISC_R_NOMEMORY
1080 *** Rdataset Methods
1084 * XXXRTH Should we check for glue and pending data in dns_db_findrdataset()?
1088 dns_db_findrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
1089 dns_rdatatype_t type, dns_rdatatype_t covers,
1090 isc_stdtime_t now, dns_rdataset_t *rdataset,
1091 dns_rdataset_t *sigrdataset);
1094 * Search for an rdataset of type 'type' at 'node' that are in version
1095 * 'version' of 'db'. If found, make 'rdataset' refer to it.
1099 * \li If 'version' is NULL, then the current version will be used.
1101 * \li Care must be used when using this routine to build a DNS response:
1102 * 'node' should have been found with dns_db_find(), not
1103 * dns_db_findnode(). No glue checking is done. No checking for
1104 * pending data is done.
1106 * \li The 'now' field is ignored if 'db' is a zone database. If 'db' is a
1107 * cache database, an rdataset will not be found unless it expires after
1108 * 'now'. If 'now' is zero, then the current time will be used.
1112 * \li 'db' is a valid database.
1114 * \li 'node' is a valid node.
1116 * \li 'rdataset' is a valid, disassociated rdataset.
1118 * \li 'sigrdataset' is a valid, disassociated rdataset, or it is NULL.
1120 * \li If 'covers' != 0, 'type' must be SIG.
1122 * \li 'type' is not a meta-RR type such as 'ANY' or 'OPT'.
1126 * \li On success, 'rdataset' is associated with the found rdataset.
1130 * \li #ISC_R_SUCCESS
1131 * \li #ISC_R_NOTFOUND
1133 * \li Other results are possible, depending upon the database
1134 * implementation used.
1138 dns_db_allrdatasets(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
1139 isc_stdtime_t now, dns_rdatasetiter_t **iteratorp);
1141 * Make '*iteratorp' an rdataset iterator for all rdatasets at 'node' in
1142 * version 'version' of 'db'.
1146 * \li If 'version' is NULL, then the current version will be used.
1148 * \li The 'now' field is ignored if 'db' is a zone database. If 'db' is a
1149 * cache database, an rdataset will not be found unless it expires after
1150 * 'now'. Any ANY query will not match unless at least one rdataset at
1151 * the node expires after 'now'. If 'now' is zero, then the current time
1156 * \li 'db' is a valid database.
1158 * \li 'node' is a valid node.
1160 * \li iteratorp != NULL && *iteratorp == NULL
1164 * \li On success, '*iteratorp' is a valid rdataset iterator.
1168 * \li #ISC_R_SUCCESS
1169 * \li #ISC_R_NOTFOUND
1171 * \li Other results are possible, depending upon the database
1172 * implementation used.
1176 dns_db_addrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
1177 isc_stdtime_t now, dns_rdataset_t *rdataset,
1178 unsigned int options, dns_rdataset_t *addedrdataset);
1180 * Add 'rdataset' to 'node' in version 'version' of 'db'.
1184 * \li If the database has zone semantics, the #DNS_DBADD_MERGE option is set,
1185 * and an rdataset of the same type as 'rdataset' already exists at
1186 * 'node' then the contents of 'rdataset' will be merged with the existing
1187 * rdataset. If the option is not set, then rdataset will replace any
1188 * existing rdataset of the same type. If not merging and the
1189 * #DNS_DBADD_FORCE option is set, then the data will update the database
1190 * without regard to trust levels. If not forcing the data, then the
1191 * rdataset will only be added if its trust level is >= the trust level of
1192 * any existing rdataset. Forcing is only meaningful for cache databases.
1193 * If #DNS_DBADD_EXACT is set then there must be no rdata in common between
1194 * the old and new rdata sets. If #DNS_DBADD_EXACTTTL is set then both
1195 * the old and new rdata sets must have the same ttl.
1197 * \li The 'now' field is ignored if 'db' is a zone database. If 'db' is
1198 * a cache database, then the added rdataset will expire no later than
1199 * now + rdataset->ttl.
1201 * \li If 'addedrdataset' is not NULL, then it will be attached to the
1202 * resulting new rdataset in the database, or to the existing data if
1203 * the existing data was better.
1207 * \li 'db' is a valid database.
1209 * \li 'node' is a valid node.
1211 * \li 'rdataset' is a valid, associated rdataset with the same class
1214 * \li 'addedrdataset' is NULL, or a valid, unassociated rdataset.
1216 * \li The database has zone semantics and 'version' is a valid
1217 * read-write version, or the database has cache semantics
1218 * and version is NULL.
1220 * \li If the database has cache semantics, the #DNS_DBADD_MERGE option must
1225 * \li #ISC_R_SUCCESS
1226 * \li #DNS_R_UNCHANGED The operation did not change anything.
1227 * \li #ISC_R_NOMEMORY
1228 * \li #DNS_R_NOTEXACT
1230 * \li Other results are possible, depending upon the database
1231 * implementation used.
1235 dns_db_subtractrdataset(dns_db_t *db, dns_dbnode_t *node,
1236 dns_dbversion_t *version, dns_rdataset_t *rdataset,
1237 unsigned int options, dns_rdataset_t *newrdataset);
1239 * Remove any rdata in 'rdataset' from 'node' in version 'version' of
1244 * \li If 'newrdataset' is not NULL, then it will be attached to the
1245 * resulting new rdataset in the database, unless the rdataset has
1246 * become nonexistent. If DNS_DBSUB_EXACT is set then all elements
1247 * of 'rdataset' must exist at 'node'.
1251 * \li 'db' is a valid database.
1253 * \li 'node' is a valid node.
1255 * \li 'rdataset' is a valid, associated rdataset with the same class
1258 * \li 'newrdataset' is NULL, or a valid, unassociated rdataset.
1260 * \li The database has zone semantics and 'version' is a valid
1261 * read-write version.
1265 * \li #ISC_R_SUCCESS
1266 * \li #DNS_R_UNCHANGED The operation did not change anything.
1267 * \li #DNS_R_NXRRSET All rdata of the same type as those
1268 * in 'rdataset' have been deleted.
1269 * \li #DNS_R_NOTEXACT Some part of 'rdataset' did not
1270 * exist and DNS_DBSUB_EXACT was set.
1272 * \li Other results are possible, depending upon the database
1273 * implementation used.
1277 dns_db_deleterdataset(dns_db_t *db, dns_dbnode_t *node,
1278 dns_dbversion_t *version, dns_rdatatype_t type,
1279 dns_rdatatype_t covers);
1281 * Make it so that no rdataset of type 'type' exists at 'node' in version
1282 * version 'version' of 'db'.
1286 * \li If 'type' is dns_rdatatype_any, then no rdatasets will exist in
1287 * 'version' (provided that the dns_db_deleterdataset() isn't followed
1288 * by one or more dns_db_addrdataset() calls).
1292 * \li 'db' is a valid database.
1294 * \li 'node' is a valid node.
1296 * \li The database has zone semantics and 'version' is a valid
1297 * read-write version, or the database has cache semantics
1298 * and version is NULL.
1300 * \li 'type' is not a meta-RR type, except for dns_rdatatype_any, which is
1303 * \li If 'covers' != 0, 'type' must be SIG.
1307 * \li #ISC_R_SUCCESS
1308 * \li #DNS_R_UNCHANGED No rdatasets of 'type' existed before
1309 * the operation was attempted.
1311 * \li Other results are possible, depending upon the database
1312 * implementation used.
1316 dns_db_getsoaserial(dns_db_t *db, dns_dbversion_t *ver, isc_uint32_t *serialp);
1318 * Get the current SOA serial number from a zone database.
1321 * \li 'db' is a valid database with zone semantics.
1322 * \li 'ver' is a valid version.
1326 dns_db_overmem(dns_db_t *db, isc_boolean_t overmem);
1328 * Enable / disable aggressive cache cleaning.
1332 dns_db_nodecount(dns_db_t *db);
1334 * Count the number of nodes in 'db'.
1338 * \li 'db' is a valid database.
1341 * \li The number of nodes in the database
1345 dns_db_settask(dns_db_t *db, isc_task_t *task);
1347 * If task is set then the final detach maybe performed asynchronously.
1350 * \li 'db' is a valid database.
1351 * \li 'task' to be valid or NULL.
1355 dns_db_ispersistent(dns_db_t *db);
1357 * Is 'db' persistent? A persistent database does not need to be loaded
1358 * from disk or written to disk.
1362 * \li 'db' is a valid database.
1365 * \li #ISC_TRUE 'db' is persistent.
1366 * \li #ISC_FALSE 'db' is not persistent.
1370 dns_db_register(const char *name, dns_dbcreatefunc_t create, void *driverarg,
1371 isc_mem_t *mctx, dns_dbimplementation_t **dbimp);
1374 * Register a new database implementation and add it to the list of
1375 * supported implementations.
1379 * \li 'name' is not NULL
1380 * \li 'order' is a valid function pointer
1381 * \li 'mctx' is a valid memory context
1382 * \li dbimp != NULL && *dbimp == NULL
1385 * \li #ISC_R_SUCCESS The registration succeeded
1386 * \li #ISC_R_NOMEMORY Out of memory
1387 * \li #ISC_R_EXISTS A database implementation with the same name exists
1391 * \li *dbimp points to an opaque structure which must be passed to
1392 * dns_db_unregister().
1396 dns_db_unregister(dns_dbimplementation_t **dbimp);
1398 * Remove a database implementation from the list of supported
1399 * implementations. No databases of this type can be active when this
1403 * \li dbimp != NULL && *dbimp == NULL
1407 * \li Any memory allocated in *dbimp will be freed.
1411 dns_db_getoriginnode(dns_db_t *db, dns_dbnode_t **nodep);
1413 * Get the origin DB node corresponding to the DB's zone. This function
1414 * should typically succeed unless the underlying DB implementation doesn't
1415 * support the feature.
1419 * \li 'db' is a valid zone database.
1420 * \li 'nodep' != NULL && '*nodep' == NULL
1423 * \li On success, '*nodep' will point to the DB node of the zone's origin.
1426 * \li #ISC_R_SUCCESS
1427 * \li #ISC_R_NOTFOUND - the DB implementation does not support this feature.
1431 dns_db_getnsec3parameters(dns_db_t *db, dns_dbversion_t *version,
1432 dns_hash_t *hash, isc_uint8_t *flags,
1433 isc_uint16_t *interations,
1434 unsigned char *salt, size_t *salt_length);
1436 * Get the NSEC3 parameters that are associated with this zone.
1439 * \li 'db' is a valid zone database.
1442 * \li #ISC_R_SUCCESS
1443 * \li #ISC_R_NOTFOUND - the DB implementation does not support this feature
1444 * or this zone does not have NSEC3 records.
1448 dns_db_findnsec3node(dns_db_t *db, dns_name_t *name,
1449 isc_boolean_t create, dns_dbnode_t **nodep);
1451 * Find the NSEC3 node with name 'name'.
1454 * \li If 'create' is ISC_TRUE and no node with name 'name' exists, then
1455 * such a node will be created.
1459 * \li 'db' is a valid database.
1461 * \li 'name' is a valid, non-empty, absolute name.
1463 * \li nodep != NULL && *nodep == NULL
1467 * \li On success, *nodep is attached to the node with name 'name'.
1471 * \li #ISC_R_SUCCESS
1472 * \li #ISC_R_NOTFOUND If !create and name not found.
1473 * \li #ISC_R_NOMEMORY Can only happen if create is ISC_TRUE.
1475 * \li Other results are possible, depending upon the database
1476 * implementation used.
1480 dns_db_setsigningtime(dns_db_t *db, dns_rdataset_t *rdataset,
1481 isc_stdtime_t resign);
1483 * Sets the re-signing time associated with 'rdataset' to 'resign'.
1486 * \li 'db' is a valid zone database.
1487 * \li 'rdataset' is or is to be associated with 'db'.
1488 * \li 'rdataset' is not pending removed from the heap via an
1489 * uncommitted call to dns_db_resigned().
1492 * \li #ISC_R_SUCCESS
1493 * \li #ISC_R_NOMEMORY
1494 * \li #ISC_R_NOTIMPLEMENTED - Not supported by this DB implementation.
1498 dns_db_getsigningtime(dns_db_t *db, dns_rdataset_t *rdataset, dns_name_t *name);
1500 * Return the rdataset with the earliest signing time in the zone.
1501 * Note: the rdataset is version agnostic.
1504 * \li 'db' is a valid zone database.
1505 * \li 'rdataset' to be initialized but not associated.
1506 * \li 'name' to be NULL or have a buffer associated with it.
1509 * \li #ISC_R_SUCCESS
1510 * \li #ISC_R_NOTFOUND - No dataset exists.
1514 dns_db_resigned(dns_db_t *db, dns_rdataset_t *rdataset,
1515 dns_dbversion_t *version);
1517 * Mark 'rdataset' as not being available to be returned by
1518 * dns_db_getsigningtime(). If the changes associated with 'version'
1519 * are committed this will be permanent. If the version is not committed
1520 * this change will be rolled back when the version is closed. Until
1521 * 'version' is either committed or rolled back, 'rdataset' can no longer
1522 * be acted upon by dns_db_setsigningtime().
1525 * \li 'db' is a valid zone database.
1526 * \li 'rdataset' to be associated with 'db'.
1527 * \li 'version' to be open for writing.
1531 dns_db_getrrsetstats(dns_db_t *db);
1533 * Get statistics information counting RRsets stored in the DB, when available.
1534 * The statistics may not be available depending on the DB implementation.
1538 * \li 'db' is a valid database (zone or cache).
1541 * \li when available, a pointer to a statistics object created by
1542 * dns_rdatasetstats_create(); otherwise NULL.
1546 dns_db_rpz_enabled(dns_db_t *db, dns_rpz_st_t *st);
1548 * Mark a database for response policy rewriting
1549 * or find which RPZ data is available.
1553 dns_db_rpz_findips(dns_rpz_zone_t *rpz, dns_rpz_type_t rpz_type,
1554 dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *version,
1555 dns_rdataset_t *ardataset, dns_rpz_st_t *st,
1556 dns_name_t *query_qname);
1558 * Search the CDIR block tree of a response policy tree of trees for the best
1559 * match to any of the IP addresses in an A or AAAA rdataset.
1562 * \li search in policy zone 'rpz' for a match of 'rpz_type' either
1563 * DNS_RPZ_TYPE_IP or DNS_RPZ_TYPE_NSIP
1564 * \li 'zone' and 'db' are the database corresponding to 'rpz'
1565 * \li 'version' is the required version of the database
1566 * \li 'ardataset' is an A or AAAA rdataset of addresses to check
1567 * \li 'found' specifies the previous best match if any or
1568 * or NULL, an empty name, 0, DNS_RPZ_POLICY_MISS, and 0
1573 #endif /* DNS_DB_H */