00001 /* 00002 * Portions Copyright (C) 2005-2007, 2009-2012 Internet Systems Consortium, Inc. ("ISC") 00003 * Portions Copyright (C) 1999-2001 Internet Software Consortium. 00004 * 00005 * Permission to use, copy, modify, and/or distribute this software for any 00006 * purpose with or without fee is hereby granted, provided that the above 00007 * copyright notice and this permission notice appear in all copies. 00008 * 00009 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 00010 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 00011 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 00012 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 00013 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 00014 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 00015 * PERFORMANCE OF THIS SOFTWARE. 00016 */ 00017 00018 /* 00019 * Copyright (C) 2002 Stichting NLnet, Netherlands, stichting@nlnet.nl. 00020 * 00021 * Permission to use, copy, modify, and distribute this software for any 00022 * purpose with or without fee is hereby granted, provided that the 00023 * above copyright notice and this permission notice appear in all 00024 * copies. 00025 * 00026 * THE SOFTWARE IS PROVIDED "AS IS" AND STICHTING NLNET 00027 * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL 00028 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL 00029 * STICHTING NLNET BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR 00030 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS 00031 * OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 00032 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE 00033 * USE OR PERFORMANCE OF THIS SOFTWARE. 00034 * 00035 * The development of Dynamically Loadable Zones (DLZ) for Bind 9 was 00036 * conceived and contributed by Rob Butler. 00037 * 00038 * Permission to use, copy, modify, and distribute this software for any 00039 * purpose with or without fee is hereby granted, provided that the 00040 * above copyright notice and this permission notice appear in all 00041 * copies. 00042 * 00043 * THE SOFTWARE IS PROVIDED "AS IS" AND ROB BUTLER 00044 * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL 00045 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL 00046 * ROB BUTLER BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR 00047 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS 00048 * OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 00049 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE 00050 * USE OR PERFORMANCE OF THIS SOFTWARE. 00051 */ 00052 00053 /* $Id$ */ 00054 00055 /*! \file dns/sdlz.h */ 00056 00057 #ifndef SDLZ_H 00058 #define SDLZ_H 1 00059 00060 #include <dns/clientinfo.h> 00061 #include <dns/dlz.h> 00062 00063 ISC_LANG_BEGINDECLS 00064 00065 #define DNS_SDLZFLAG_THREADSAFE 0x00000001U 00066 #define DNS_SDLZFLAG_RELATIVEOWNER 0x00000002U 00067 #define DNS_SDLZFLAG_RELATIVERDATA 0x00000004U 00068 00069 /* A simple DLZ database. */ 00070 typedef struct dns_sdlz_db dns_sdlz_db_t; 00071 00072 /* A simple DLZ database lookup in progress. */ 00073 typedef struct dns_sdlzlookup dns_sdlzlookup_t; 00074 00075 /* A simple DLZ database traversal in progress. */ 00076 typedef struct dns_sdlzallnodes dns_sdlzallnodes_t; 00077 00078 typedef isc_result_t (*dns_sdlzallnodesfunc_t)(const char *zone, 00079 void *driverarg, 00080 void *dbdata, 00081 dns_sdlzallnodes_t *allnodes); 00082 /*%< 00083 * Method prototype. Drivers implementing the SDLZ interface may 00084 * supply an all nodes method. This method is called when the DNS 00085 * server is performing a zone transfer query, after the allow zone 00086 * transfer method has been called. This method is only called if the 00087 * allow zone transfer method returned ISC_R_SUCCESS. This method and 00088 * the allow zone transfer method are both required for zone transfers 00089 * to be supported. If the driver generates data dynamically (instead 00090 * of searching in a database for it) it should not implement this 00091 * function as a zone transfer would be meaningless. A SDLZ driver 00092 * does not have to implement an all nodes method. 00093 */ 00094 00095 typedef isc_result_t (*dns_sdlzallowzonexfr_t)(void *driverarg, 00096 void *dbdata, const char *name, 00097 const char *client); 00098 00099 /*%< 00100 * Method prototype. Drivers implementing the SDLZ interface may 00101 * supply an allow zone transfer method. This method is called when 00102 * the DNS server is performing a zone transfer query, before the all 00103 * nodes method can be called. This method and the all node method 00104 * are both required for zone transfers to be supported. If the 00105 * driver generates data dynamically (instead of searching in a 00106 * database for it) it should not implement this function as a zone 00107 * transfer would be meaningless. A SDLZ driver does not have to 00108 * implement an allow zone transfer method. 00109 * 00110 * This method should return ISC_R_SUCCESS if the zone is supported by 00111 * the database and a zone transfer is allowed for the specified 00112 * client. If the zone is supported by the database, but zone 00113 * transfers are not allowed for the specified client this method 00114 * should return ISC_R_NOPERM.. Lastly the method should return 00115 * ISC_R_NOTFOUND if the zone is not supported by the database. If an 00116 * error occurs it should return a result code indicating the type of 00117 * error. 00118 */ 00119 00120 typedef isc_result_t (*dns_sdlzauthorityfunc_t)(const char *zone, 00121 void *driverarg, void *dbdata, 00122 dns_sdlzlookup_t *lookup); 00123 00124 /*%< 00125 * Method prototype. Drivers implementing the SDLZ interface may 00126 * supply an authority method. This method is called when the DNS 00127 * server is performing a query, after both the find zone and lookup 00128 * methods have been called. This method is required if the lookup 00129 * function does not supply authority information for the dns 00130 * record. A SDLZ driver does not have to implement an authority 00131 * method. 00132 */ 00133 00134 typedef isc_result_t (*dns_sdlzcreate_t)(const char *dlzname, 00135 unsigned int argc, char *argv[], 00136 void *driverarg, void **dbdata); 00137 00138 /*%< 00139 * Method prototype. Drivers implementing the SDLZ interface may 00140 * supply a create method. This method is called when the DNS server 00141 * is starting up and creating drivers for use later. A SDLZ driver 00142 * does not have to implement a create method. 00143 */ 00144 00145 typedef void (*dns_sdlzdestroy_t)(void *driverarg, void *dbdata); 00146 00147 /*%< 00148 * Method prototype. Drivers implementing the SDLZ interface may 00149 * supply a destroy method. This method is called when the DNS server 00150 * is shutting down and no longer needs the driver. A SDLZ driver does 00151 * not have to implement a destroy method. 00152 */ 00153 00154 typedef isc_result_t 00155 (*dns_sdlzfindzone_t)(void *driverarg, void *dbdata, const char *name, 00156 dns_clientinfomethods_t *methods, 00157 dns_clientinfo_t *clientinfo); 00158 /*%< 00159 * Method prototype. Drivers implementing the SDLZ interface MUST 00160 * supply a find zone method. This method is called when the DNS 00161 * server is performing a query to to determine if 'name' is a 00162 * supported dns zone. The find zone method will be called with the 00163 * longest possible name first, and continue to be called with 00164 * successively shorter domain names, until any of the following 00165 * occur: 00166 * 00167 * \li 1) the function returns (ISC_R_SUCCESS) indicating a zone name 00168 * match. 00169 * 00170 * \li 2) a problem occurs, and the functions returns anything other than 00171 * (ISC_R_NOTFOUND) 00172 * 00173 * \li 3) we run out of domain name labels. I.E. we have tried the 00174 * shortest domain name 00175 * 00176 * \li 4) the number of labels in the domain name is less than min_labels 00177 * for dns_dlzfindzone 00178 * 00179 * The driver's find zone method should return ISC_R_SUCCESS if the 00180 * zone is supported by the database. Otherwise it should return 00181 * ISC_R_NOTFOUND, if the zone is not supported. If an error occurs 00182 * it should return a result code indicating the type of error. 00183 */ 00184 00185 typedef isc_result_t 00186 (*dns_sdlzlookupfunc_t)(const char *zone, const char *name, void *driverarg, 00187 void *dbdata, dns_sdlzlookup_t *lookup, 00188 dns_clientinfomethods_t *methods, 00189 dns_clientinfo_t *clientinfo); 00190 00191 /*%< 00192 * Method prototype. Drivers implementing the SDLZ interface MUST 00193 * supply a lookup method. This method is called when the 00194 * DNS server is performing a query, after the find zone and before any 00195 * other methods have been called. This function returns DNS record 00196 * information using the dns_sdlz_putrr and dns_sdlz_putsoa functions. 00197 * If this function supplies authority information for the DNS record 00198 * the authority method is not required. If it does not, the 00199 * authority function is required. 00200 * 00201 * The 'methods' and 'clientinfo' args allow an SDLZ driver to retrieve 00202 * information about the querying client (such as source IP address) 00203 * from the caller. 00204 */ 00205 00206 typedef isc_result_t (*dns_sdlznewversion_t)(const char *zone, 00207 void *driverarg, void *dbdata, 00208 void **versionp); 00209 /*%< 00210 * Method prototype. Drivers implementing the SDLZ interface may 00211 * supply a newversion method. This method is called to start a 00212 * write transaction on a zone and should only be implemented by 00213 * writeable backends. 00214 * When implemented, the driver should create a new transaction, and 00215 * fill *versionp with a pointer to the transaction state. The 00216 * closeversion function will be called to close the transaction. 00217 */ 00218 00219 typedef void (*dns_sdlzcloseversion_t)(const char *zone, isc_boolean_t commit, 00220 void *driverarg, void *dbdata, 00221 void **versionp); 00222 /*%< 00223 * Method prototype. Drivers implementing the SDLZ interface must 00224 * supply a closeversion method if they supply a newversion method. 00225 * When implemented, the driver should close the given transaction, 00226 * committing changes if 'commit' is ISC_TRUE. If 'commit' is not true 00227 * then all changes should be discarded and the database rolled back. 00228 * If the call is successful then *versionp should be set to NULL 00229 */ 00230 00231 typedef isc_result_t (*dns_sdlzconfigure_t)(dns_view_t *view, 00232 dns_dlzdb_t *dlzdb, 00233 void *driverarg, void *dbdata); 00234 /*%< 00235 * Method prototype. Drivers implementing the SDLZ interface may 00236 * supply a configure method. When supplied, it will be called 00237 * immediately after the create method to give the driver a chance 00238 * to configure writeable zones 00239 */ 00240 00241 00242 typedef isc_boolean_t (*dns_sdlzssumatch_t)(const char *signer, 00243 const char *name, 00244 const char *tcpaddr, 00245 const char *type, 00246 const char *key, 00247 isc_uint32_t keydatalen, 00248 unsigned char *keydata, 00249 void *driverarg, 00250 void *dbdata); 00251 00252 /*%< 00253 * Method prototype. Drivers implementing the SDLZ interface may 00254 * supply a ssumatch method. If supplied, then ssumatch will be 00255 * called to authorize any zone updates. The driver should return 00256 * ISC_TRUE to allow the update, and ISC_FALSE to deny it. For a DLZ 00257 * controlled zone, this is the only access control on updates. 00258 */ 00259 00260 00261 typedef isc_result_t (*dns_sdlzmodrdataset_t)(const char *name, 00262 const char *rdatastr, 00263 void *driverarg, void *dbdata, 00264 void *version); 00265 /*%< 00266 * Method prototype. Drivers implementing the SDLZ interface may 00267 * supply addrdataset and subtractrdataset methods. If supplied, then these 00268 * will be called when rdatasets are added/subtracted during 00269 * updates. The version parameter comes from a call to the sdlz 00270 * newversion() method from the driver. The rdataset parameter is a 00271 * linearise string representation of the rdataset change. The format 00272 * is the same as used by dig when displaying records. The fields are 00273 * tab delimited. 00274 */ 00275 00276 typedef isc_result_t (*dns_sdlzdelrdataset_t)(const char *name, 00277 const char *type, 00278 void *driverarg, void *dbdata, 00279 void *version); 00280 /*%< 00281 * Method prototype. Drivers implementing the SDLZ interface may 00282 * supply a delrdataset method. If supplied, then this 00283 * function will be called when rdatasets are deleted during 00284 * updates. The call should remove all rdatasets of the given type for 00285 * the specified name. 00286 */ 00287 00288 typedef struct dns_sdlzmethods { 00289 dns_sdlzcreate_t create; 00290 dns_sdlzdestroy_t destroy; 00291 dns_sdlzfindzone_t findzone; 00292 dns_sdlzlookupfunc_t lookup; 00293 dns_sdlzauthorityfunc_t authority; 00294 dns_sdlzallnodesfunc_t allnodes; 00295 dns_sdlzallowzonexfr_t allowzonexfr; 00296 dns_sdlznewversion_t newversion; 00297 dns_sdlzcloseversion_t closeversion; 00298 dns_sdlzconfigure_t configure; 00299 dns_sdlzssumatch_t ssumatch; 00300 dns_sdlzmodrdataset_t addrdataset; 00301 dns_sdlzmodrdataset_t subtractrdataset; 00302 dns_sdlzdelrdataset_t delrdataset; 00303 } dns_sdlzmethods_t; 00304 00305 isc_result_t 00306 dns_sdlzregister(const char *drivername, const dns_sdlzmethods_t *methods, 00307 void *driverarg, unsigned int flags, isc_mem_t *mctx, 00308 dns_sdlzimplementation_t **sdlzimp); 00309 /*%< 00310 * Register a dynamically loadable zones (dlz) driver for the database 00311 * type 'drivername', implemented by the functions in '*methods'. 00312 * 00313 * sdlzimp must point to a NULL dns_sdlzimplementation_t pointer. 00314 * That is, sdlzimp != NULL && *sdlzimp == NULL. It will be assigned 00315 * a value that will later be used to identify the driver when 00316 * deregistering it. 00317 */ 00318 00319 void 00320 dns_sdlzunregister(dns_sdlzimplementation_t **sdlzimp); 00321 00322 /*%< 00323 * Removes the sdlz driver from the list of registered sdlz drivers. 00324 * There must be no active sdlz drivers of this type when this 00325 * function is called. 00326 */ 00327 00328 typedef isc_result_t dns_sdlz_putnamedrr_t(dns_sdlzallnodes_t *allnodes, 00329 const char *name, 00330 const char *type, 00331 dns_ttl_t ttl, 00332 const char *data); 00333 dns_sdlz_putnamedrr_t dns_sdlz_putnamedrr; 00334 00335 /*%< 00336 * Add a single resource record to the allnodes structure to be later 00337 * parsed into a zone transfer response. 00338 */ 00339 00340 typedef isc_result_t dns_sdlz_putrr_t(dns_sdlzlookup_t *lookup, 00341 const char *type, 00342 dns_ttl_t ttl, 00343 const char *data); 00344 dns_sdlz_putrr_t dns_sdlz_putrr; 00345 /*%< 00346 * Add a single resource record to the lookup structure to be later 00347 * parsed into a query response. 00348 */ 00349 00350 typedef isc_result_t dns_sdlz_putsoa_t(dns_sdlzlookup_t *lookup, 00351 const char *mname, 00352 const char *rname, 00353 isc_uint32_t serial); 00354 dns_sdlz_putsoa_t dns_sdlz_putsoa; 00355 /*%< 00356 * This function may optionally be called from the 'authority' 00357 * callback to simplify construction of the SOA record for 'zone'. It 00358 * will provide a SOA listing 'mname' as as the master server and 00359 * 'rname' as the responsible person mailbox. It is the 00360 * responsibility of the driver to increment the serial number between 00361 * responses if necessary. All other SOA fields will have reasonable 00362 * default values. 00363 */ 00364 00365 00366 typedef isc_result_t dns_sdlz_setdb_t(dns_dlzdb_t *dlzdatabase, 00367 dns_rdataclass_t rdclass, 00368 dns_name_t *name, 00369 dns_db_t **dbp); 00370 dns_sdlz_setdb_t dns_sdlz_setdb; 00371 /*%< 00372 * Create the database pointers for a writeable SDLZ zone 00373 */ 00374 00375 00376 ISC_LANG_ENDDECLS 00377 00378 #endif /* SDLZ_H */