Edit File: rdataset.h
/* * Copyright (C) Internet Systems Consortium, Inc. ("ISC") * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. * * See the COPYRIGHT file distributed with this work for additional * information regarding copyright ownership. */ #ifndef DNS_RDATASET_H #define DNS_RDATASET_H 1 /***** ***** Module Info *****/ /*! \file dns/rdataset.h * \brief * A DNS rdataset is a handle that can be associated with a collection of * rdata all having a common owner name, class, and type. * * The dns_rdataset_t type is like a "virtual class". To actually use * rdatasets, an implementation of the method suite (e.g. "slabbed rdata") is * required. * * XXX <more> XXX * * MP: *\li Clients of this module must impose any required synchronization. * * Reliability: *\li No anticipated impact. * * Resources: *\li TBS * * Security: *\li No anticipated impact. * * Standards: *\li None. */ #include <isc/lang.h> #include <isc/magic.h> #include <isc/stdtime.h> #include <dns/types.h> #include <dns/rdatastruct.h> #define DNS_RDATASET_MAXADDITIONAL 13 ISC_LANG_BEGINDECLS typedef enum { dns_rdatasetadditional_fromauth, dns_rdatasetadditional_fromcache, dns_rdatasetadditional_fromglue } dns_rdatasetadditional_t; typedef struct dns_rdatasetmethods { void (*disassociate)(dns_rdataset_t *rdataset); isc_result_t (*first)(dns_rdataset_t *rdataset); isc_result_t (*next)(dns_rdataset_t *rdataset); void (*current)(dns_rdataset_t *rdataset, dns_rdata_t *rdata); void (*clone)(dns_rdataset_t *source, dns_rdataset_t *target); unsigned int (*count)(dns_rdataset_t *rdataset); isc_result_t (*addnoqname)(dns_rdataset_t *rdataset, dns_name_t *name); isc_result_t (*getnoqname)(dns_rdataset_t *rdataset, dns_name_t *name, dns_rdataset_t *neg, dns_rdataset_t *negsig); isc_result_t (*addclosest)(dns_rdataset_t *rdataset, dns_name_t *name); isc_result_t (*getclosest)(dns_rdataset_t *rdataset, dns_name_t *name, dns_rdataset_t *neg, dns_rdataset_t *negsig); isc_result_t (*getadditional)(dns_rdataset_t *rdataset, dns_rdatasetadditional_t type, dns_rdatatype_t qtype, dns_acache_t *acache, dns_zone_t **zonep, dns_db_t **dbp, dns_dbversion_t **versionp, dns_dbnode_t **nodep, dns_name_t *fname, dns_message_t *msg, isc_stdtime_t now); isc_result_t (*setadditional)(dns_rdataset_t *rdataset, dns_rdatasetadditional_t type, dns_rdatatype_t qtype, dns_acache_t *acache, dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *version, dns_dbnode_t *node, dns_name_t *fname); isc_result_t (*putadditional)(dns_acache_t *acache, dns_rdataset_t *rdataset, dns_rdatasetadditional_t type, dns_rdatatype_t qtype); void (*settrust)(dns_rdataset_t *rdataset, dns_trust_t trust); void (*expire)(dns_rdataset_t *rdataset); void (*clearprefetch)(dns_rdataset_t *rdataset); void (*setownercase)(dns_rdataset_t *rdataset, const dns_name_t *name); void (*getownercase)(const dns_rdataset_t *rdataset, dns_name_t *name); } dns_rdatasetmethods_t; #define DNS_RDATASET_MAGIC ISC_MAGIC('D','N','S','R') #define DNS_RDATASET_VALID(set) ISC_MAGIC_VALID(set, DNS_RDATASET_MAGIC) /*% * Direct use of this structure by clients is strongly discouraged, except * for the 'link' field which may be used however the client wishes. The * 'private', 'current', and 'index' fields MUST NOT be changed by clients. * rdataset implementations may change any of the fields. */ struct dns_rdataset { unsigned int magic; /* XXX ? */ dns_rdatasetmethods_t * methods; ISC_LINK(dns_rdataset_t) link; /* * XXX do we need these, or should they be retrieved by methods? * Leaning towards the latter, since they are not frequently required * once you have the rdataset. */ dns_rdataclass_t rdclass; dns_rdatatype_t type; dns_ttl_t ttl; dns_trust_t trust; dns_rdatatype_t covers; /* * attributes */ unsigned int attributes; /*% * the counter provides the starting point in the "cyclic" order. * The value ISC_UINT32_MAX has a special meaning of "picking up a * random value." in order to take care of databases that do not * increment the counter. */ isc_uint32_t count; /* * This RRSIG RRset should be re-generated around this time. * Only valid if DNS_RDATASETATTR_RESIGN is set in attributes. */ isc_stdtime_t resign; /*@{*/ /*% * These are for use by the rdataset implementation, and MUST NOT * be changed by clients. */ void * private1; void * private2; void * private3; unsigned int privateuint4; void * private5; void * private6; void * private7; /*@}*/ }; /*! * \def DNS_RDATASETATTR_RENDERED * Used by message.c to indicate that the rdataset was rendered. * * \def DNS_RDATASETATTR_TTLADJUSTED * Used by message.c to indicate that the rdataset's rdata had differing * TTL values, and the rdataset->ttl holds the smallest. * * \def DNS_RDATASETATTR_LOADORDER * Output the RRset in load order. */ #define DNS_RDATASETATTR_QUESTION 0x00000001 #define DNS_RDATASETATTR_RENDERED 0x00000002 /*%< Used by message.c */ #define DNS_RDATASETATTR_ANSWERED 0x00000004 /*%< Used by server. */ #define DNS_RDATASETATTR_CACHE 0x00000008 /*%< Used by resolver. */ #define DNS_RDATASETATTR_ANSWER 0x00000010 /*%< Used by resolver. */ #define DNS_RDATASETATTR_ANSWERSIG 0x00000020 /*%< Used by resolver. */ #define DNS_RDATASETATTR_EXTERNAL 0x00000040 /*%< Used by resolver. */ #define DNS_RDATASETATTR_NCACHE 0x00000080 /*%< Used by resolver. */ #define DNS_RDATASETATTR_CHAINING 0x00000100 /*%< Used by resolver. */ #define DNS_RDATASETATTR_TTLADJUSTED 0x00000200 /*%< Used by message.c */ #define DNS_RDATASETATTR_FIXEDORDER 0x00000400 #define DNS_RDATASETATTR_RANDOMIZE 0x00000800 #define DNS_RDATASETATTR_CHASE 0x00001000 /*%< Used by resolver. */ #define DNS_RDATASETATTR_NXDOMAIN 0x00002000 #define DNS_RDATASETATTR_NOQNAME 0x00004000 #define DNS_RDATASETATTR_CHECKNAMES 0x00008000 /*%< Used by resolver. */ #define DNS_RDATASETATTR_REQUIRED 0x00010000 #define DNS_RDATASETATTR_REQUIREDGLUE DNS_RDATASETATTR_REQUIRED #define DNS_RDATASETATTR_LOADORDER 0x00020000 #define DNS_RDATASETATTR_RESIGN 0x00040000 #define DNS_RDATASETATTR_CLOSEST 0x00080000 #define DNS_RDATASETATTR_OPTOUT 0x00100000 /*%< OPTOUT proof */ #define DNS_RDATASETATTR_NEGATIVE 0x00200000 #define DNS_RDATASETATTR_PREFETCH 0x00400000 /*% * _OMITDNSSEC: * Omit DNSSEC records when rendering ncache records. */ #define DNS_RDATASETTOWIRE_OMITDNSSEC 0x0001 void dns_rdataset_init(dns_rdataset_t *rdataset); /*%< * Make 'rdataset' a valid, disassociated rdataset. * * Requires: *\li 'rdataset' is not NULL. * * Ensures: *\li 'rdataset' is a valid, disassociated rdataset. */ void dns_rdataset_invalidate(dns_rdataset_t *rdataset); /*%< * Invalidate 'rdataset'. * * Requires: *\li 'rdataset' is a valid, disassociated rdataset. * * Ensures: *\li If assertion checking is enabled, future attempts to use 'rdataset' * without initializing it will cause an assertion failure. */ void dns_rdataset_disassociate(dns_rdataset_t *rdataset); /*%< * Disassociate 'rdataset' from its rdata, allowing it to be reused. * * Notes: *\li The client must ensure it has no references to rdata in the rdataset * before disassociating. * * Requires: *\li 'rdataset' is a valid, associated rdataset. * * Ensures: *\li 'rdataset' is a valid, disassociated rdataset. */ isc_boolean_t dns_rdataset_isassociated(dns_rdataset_t *rdataset); /*%< * Is 'rdataset' associated? * * Requires: *\li 'rdataset' is a valid rdataset. * * Returns: *\li #ISC_TRUE 'rdataset' is associated. *\li #ISC_FALSE 'rdataset' is not associated. */ void dns_rdataset_makequestion(dns_rdataset_t *rdataset, dns_rdataclass_t rdclass, dns_rdatatype_t type); /*%< * Make 'rdataset' a valid, associated, question rdataset, with a * question class of 'rdclass' and type 'type'. * * Notes: *\li Question rdatasets have a class and type, but no rdata. * * Requires: *\li 'rdataset' is a valid, disassociated rdataset. * * Ensures: *\li 'rdataset' is a valid, associated, question rdataset. */ void dns_rdataset_clone(dns_rdataset_t *source, dns_rdataset_t *target); /*%< * Make 'target' refer to the same rdataset as 'source'. * * Requires: *\li 'source' is a valid, associated rdataset. * *\li 'target' is a valid, dissociated rdataset. * * Ensures: *\li 'target' references the same rdataset as 'source'. */ unsigned int dns_rdataset_count(dns_rdataset_t *rdataset); /*%< * Return the number of records in 'rdataset'. * * Requires: *\li 'rdataset' is a valid, associated rdataset. * * Returns: *\li The number of records in 'rdataset'. */ isc_result_t dns_rdataset_first(dns_rdataset_t *rdataset); /*%< * Move the rdata cursor to the first rdata in the rdataset (if any). * * Requires: *\li 'rdataset' is a valid, associated rdataset. * * Returns: *\li #ISC_R_SUCCESS *\li #ISC_R_NOMORE There are no rdata in the set. */ isc_result_t dns_rdataset_next(dns_rdataset_t *rdataset); /*%< * Move the rdata cursor to the next rdata in the rdataset (if any). * * Requires: *\li 'rdataset' is a valid, associated rdataset. * * Returns: *\li #ISC_R_SUCCESS *\li #ISC_R_NOMORE There are no more rdata in the set. */ void dns_rdataset_current(dns_rdataset_t *rdataset, dns_rdata_t *rdata); /*%< * Make 'rdata' refer to the current rdata. * * Notes: * *\li The data returned in 'rdata' is valid for the life of the * rdataset; in particular, subsequent changes in the cursor position * do not invalidate 'rdata'. * * Requires: *\li 'rdataset' is a valid, associated rdataset. * *\li The rdata cursor of 'rdataset' is at a valid location (i.e. the * result of last call to a cursor movement command was ISC_R_SUCCESS). * * Ensures: *\li 'rdata' refers to the rdata at the rdata cursor location of *\li 'rdataset'. */ isc_result_t dns_rdataset_totext(dns_rdataset_t *rdataset, dns_name_t *owner_name, isc_boolean_t omit_final_dot, isc_boolean_t question, isc_buffer_t *target); /*%< * Convert 'rdataset' to text format, storing the result in 'target'. * * Notes: *\li The rdata cursor position will be changed. * *\li The 'question' flag should normally be #ISC_FALSE. If it is * #ISC_TRUE, the TTL and rdata fields are not printed. This is * for use when printing an rdata representing a question section. * *\li This interface is deprecated; use dns_master_rdatasettottext() * and/or dns_master_questiontotext() instead. * * Requires: *\li 'rdataset' is a valid rdataset. * *\li 'rdataset' is not empty. */ isc_result_t dns_rdataset_towire(dns_rdataset_t *rdataset, dns_name_t *owner_name, dns_compress_t *cctx, isc_buffer_t *target, unsigned int options, unsigned int *countp); /*%< * Convert 'rdataset' to wire format, compressing names as specified * in 'cctx', and storing the result in 'target'. * * Notes: *\li The rdata cursor position will be changed. * *\li The number of RRs added to target will be added to *countp. * * Requires: *\li 'rdataset' is a valid rdataset. * *\li 'rdataset' is not empty. * *\li 'countp' is a valid pointer. * * Ensures: *\li On a return of ISC_R_SUCCESS, 'target' contains a wire format * for the data contained in 'rdataset'. Any error return leaves * the buffer unchanged. * *\li *countp has been incremented by the number of RRs added to * target. * * Returns: *\li #ISC_R_SUCCESS - all ok *\li #ISC_R_NOSPACE - 'target' doesn't have enough room * *\li Any error returned by dns_rdata_towire(), dns_rdataset_next(), * dns_name_towire(). */ isc_result_t dns_rdataset_towiresorted(dns_rdataset_t *rdataset, const dns_name_t *owner_name, dns_compress_t *cctx, isc_buffer_t *target, dns_rdatasetorderfunc_t order, const void *order_arg, unsigned int options, unsigned int *countp); /*%< * Like dns_rdataset_towire(), but sorting the rdatasets according to * the integer value returned by 'order' when called with the rdataset * and 'order_arg' as arguments. * * Requires: *\li All the requirements of dns_rdataset_towire(), and * that order_arg is NULL if and only if order is NULL. */ isc_result_t dns_rdataset_towirepartial(dns_rdataset_t *rdataset, const dns_name_t *owner_name, dns_compress_t *cctx, isc_buffer_t *target, dns_rdatasetorderfunc_t order, const void *order_arg, unsigned int options, unsigned int *countp, void **state); /*%< * Like dns_rdataset_towiresorted() except that a partial rdataset * may be written. * * Requires: *\li All the requirements of dns_rdataset_towiresorted(). * If 'state' is non NULL then the current position in the * rdataset will be remembered if the rdataset in not * completely written and should be passed on on subsequent * calls (NOT CURRENTLY IMPLEMENTED). * * Returns: *\li #ISC_R_SUCCESS if all of the records were written. *\li #ISC_R_NOSPACE if unable to fit in all of the records. *countp * will be updated to reflect the number of records * written. */ isc_result_t dns_rdataset_additionaldata(dns_rdataset_t *rdataset, dns_additionaldatafunc_t add, void *arg); /*%< * For each rdata in rdataset, call 'add' for each name and type in the * rdata which is subject to additional section processing. * * Requires: * *\li 'rdataset' is a valid, non-question rdataset. * *\li 'add' is a valid dns_additionaldatafunc_t * * Ensures: * *\li If successful, dns_rdata_additionaldata() will have been called for * each rdata in 'rdataset'. * *\li If a call to dns_rdata_additionaldata() is not successful, the * result returned will be the result of dns_rdataset_additionaldata(). * *\li If 'limit' is non-zero and the number of the rdatasets is larger * than 'limit', no additional data will be processed. * * Returns: * *\li #ISC_R_SUCCESS * *\li #DNS_R_TOOMANYRECORDS in case rdataset count is larger than 'limit' * *\li Any error that dns_rdata_additionaldata() can return. */ isc_result_t dns_rdataset_additionaldata2(dns_rdataset_t *rdataset, dns_additionaldatafunc_t add, void *arg, size_t limit); isc_result_t dns_rdataset_getnoqname(dns_rdataset_t *rdataset, dns_name_t *name, dns_rdataset_t *neg, dns_rdataset_t *negsig); /*%< * Return the noqname proof for this record. * * Requires: *\li 'rdataset' to be valid and #DNS_RDATASETATTR_NOQNAME to be set. *\li 'name' to be valid. *\li 'neg' and 'negsig' to be valid and not associated. */ isc_result_t dns_rdataset_addnoqname(dns_rdataset_t *rdataset, dns_name_t *name); /*%< * Associate a noqname proof with this record. * Sets #DNS_RDATASETATTR_NOQNAME if successful. * Adjusts the 'rdataset->ttl' to minimum of the 'rdataset->ttl' and * the 'nsec'/'nsec3' and 'rrsig(nsec)'/'rrsig(nsec3)' ttl. * * Requires: *\li 'rdataset' to be valid and #DNS_RDATASETATTR_NOQNAME to be set. *\li 'name' to be valid and have NSEC or NSEC3 and associated RRSIG * rdatasets. */ isc_result_t dns_rdataset_getclosest(dns_rdataset_t *rdataset, dns_name_t *name, dns_rdataset_t *nsec, dns_rdataset_t *nsecsig); /*%< * Return the closest encloser for this record. * * Requires: *\li 'rdataset' to be valid and #DNS_RDATASETATTR_CLOSEST to be set. *\li 'name' to be valid. *\li 'nsec' and 'nsecsig' to be valid and not associated. */ isc_result_t dns_rdataset_addclosest(dns_rdataset_t *rdataset, dns_name_t *name); /*%< * Associate a closest encloset proof with this record. * Sets #DNS_RDATASETATTR_CLOSEST if successful. * Adjusts the 'rdataset->ttl' to minimum of the 'rdataset->ttl' and * the 'nsec' and 'rrsig(nsec)' ttl. * * Requires: *\li 'rdataset' to be valid and #DNS_RDATASETATTR_CLOSEST to be set. *\li 'name' to be valid and have NSEC3 and RRSIG(NSEC3) rdatasets. */ isc_result_t dns_rdataset_getadditional(dns_rdataset_t *rdataset, dns_rdatasetadditional_t type, dns_rdatatype_t qtype, dns_acache_t *acache, dns_zone_t **zonep, dns_db_t **dbp, dns_dbversion_t **versionp, dns_dbnode_t **nodep, dns_name_t *fname, dns_message_t *msg, isc_stdtime_t now); /*%< * Get cached additional information from the DB node for a particular * 'rdataset.' 'type' is one of dns_rdatasetadditional_fromauth, * dns_rdatasetadditional_fromcache, and dns_rdatasetadditional_fromglue, * which specifies the origin of the information. 'qtype' is intended to * be used for specifying a particular rdata type in the cached information. * * Requires: * \li 'rdataset' is a valid rdataset. * \li 'acache' can be NULL, in which case this function will simply return * ISC_R_FAILURE. * \li For the other pointers, see dns_acache_getentry(). * * Ensures: * \li See dns_acache_getentry(). * * Returns: * \li #ISC_R_SUCCESS * \li #ISC_R_FAILURE - additional information caching is not supported. * \li #ISC_R_NOTFOUND - the corresponding DB node has not cached additional * information for 'rdataset.' * \li Any error that dns_acache_getentry() can return. */ isc_result_t dns_rdataset_setadditional(dns_rdataset_t *rdataset, dns_rdatasetadditional_t type, dns_rdatatype_t qtype, dns_acache_t *acache, dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *version, dns_dbnode_t *node, dns_name_t *fname); /*%< * Set cached additional information to the DB node for a particular * 'rdataset.' See dns_rdataset_getadditional for the semantics of 'type' * and 'qtype'. * * Requires: * \li 'rdataset' is a valid rdataset. * \li 'acache' can be NULL, in which case this function will simply return * ISC_R_FAILURE. * \li For the other pointers, see dns_acache_setentry(). * * Ensures: * \li See dns_acache_setentry(). * * Returns: * \li #ISC_R_SUCCESS * \li #ISC_R_FAILURE - additional information caching is not supported. * \li #ISC_R_NOMEMORY * \li Any error that dns_acache_setentry() can return. */ isc_result_t dns_rdataset_putadditional(dns_acache_t *acache, dns_rdataset_t *rdataset, dns_rdatasetadditional_t type, dns_rdatatype_t qtype); /*%< * Discard cached additional information stored in the DB node for a particular * 'rdataset.' See dns_rdataset_getadditional for the semantics of 'type' * and 'qtype'. * * Requires: * \li 'rdataset' is a valid rdataset. * \li 'acache' can be NULL, in which case this function will simply return * ISC_R_FAILURE. * * Ensures: * \li See dns_acache_cancelentry(). * * Returns: * \li #ISC_R_SUCCESS * \li #ISC_R_FAILURE - additional information caching is not supported. * \li #ISC_R_NOTFOUND - the corresponding DB node has not cached additional * information for 'rdataset.' */ void dns_rdataset_settrust(dns_rdataset_t *rdataset, dns_trust_t trust); /*%< * Set the trust of the 'rdataset' to trust in any in the backing database. * The local trust level of 'rdataset' is also set. */ void dns_rdataset_expire(dns_rdataset_t *rdataset); /*%< * Mark the rdataset to be expired in the backing database. */ void dns_rdataset_clearprefetch(dns_rdataset_t *rdataset); /*%< * Clear the PREFETCH attribute for the given rdataset in the * underlying database. * * In the cache database, this signals that the rdataset is not * eligible to be prefetched when the TTL is close to expiring. * It has no function in other databases. */ void dns_rdataset_setownercase(dns_rdataset_t *rdataset, const dns_name_t *name); /*%< * Store the casing of 'name', the owner name of 'rdataset', into * a bitfield so that the name can be capitalized the same when when * the rdataset is used later. This sets the CASESET attribute. */ void dns_rdataset_getownercase(const dns_rdataset_t *rdataset, dns_name_t *name); /*%< * If the CASESET attribute is set, retrieve the case bitfield that was * previously stored by dns_rdataset_getownername(), and capitalize 'name' * according to it. If CASESET is not set, do nothing. */ void dns_rdataset_trimttl(dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset, dns_rdata_rrsig_t *rrsig, isc_stdtime_t now, isc_boolean_t acceptexpired); /*%< * Trim the ttl of 'rdataset' and 'sigrdataset' so that they will expire * at or before 'rrsig->expiretime'. If 'acceptexpired' is true and the * signature has expired or will expire in the next 120 seconds, limit * the ttl to be no more than 120 seconds. * * The ttl is further limited by the original ttl as stored in 'rrsig' * and the original ttl values of 'rdataset' and 'sigrdataset'. * * Requires: * \li 'rdataset' is a valid rdataset. * \li 'sigrdataset' is a valid rdataset. * \li 'rrsig' is non NULL. */ const char * dns_trust_totext(dns_trust_t trust); /*%< * Display trust in textual form. */ ISC_LANG_ENDDECLS #endif /* DNS_RDATASET_H */