1 /* 2 * Portions Copyright (C) 2005-2007, 2009-2012 Internet Systems Consortium, Inc. ("ISC") 3 * Portions Copyright (C) 1999-2001 Internet Software Consortium. 4 * 5 * Permission to use, copy, modify, and/or distribute this software for any 6 * purpose with or without fee is hereby granted, provided that the above 7 * copyright notice and this permission notice appear in all copies. 8 * 9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15 * PERFORMANCE OF THIS SOFTWARE. 16 */ 17 18 /* 19 * Copyright (C) 2002 Stichting NLnet, Netherlands, stichting@nlnet.nl. 20 * 21 * Permission to use, copy, modify, and distribute this software for any 22 * purpose with or without fee is hereby granted, provided that the 23 * above copyright notice and this permission notice appear in all 24 * copies. 25 * 26 * THE SOFTWARE IS PROVIDED "AS IS" AND STICHTING NLNET 27 * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL 28 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL 29 * STICHTING NLNET BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR 30 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS 31 * OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 32 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE 33 * USE OR PERFORMANCE OF THIS SOFTWARE. 34 * 35 * The development of Dynamically Loadable Zones (DLZ) for Bind 9 was 36 * conceived and contributed by Rob Butler. 37 * 38 * Permission to use, copy, modify, and distribute this software for any 39 * purpose with or without fee is hereby granted, provided that the 40 * above copyright notice and this permission notice appear in all 41 * copies. 42 * 43 * THE SOFTWARE IS PROVIDED "AS IS" AND ROB BUTLER 44 * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL 45 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL 46 * ROB BUTLER BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR 47 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS 48 * OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 49 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE 50 * USE OR PERFORMANCE OF THIS SOFTWARE. 51 */ 52 53 /* $Id$ */ 54 55 /*! \file dns/sdlz.h */ 56 57 #ifndef SDLZ_H 58 #define SDLZ_H 1 59 60 #include <dns/clientinfo.h> 61 #include <dns/dlz.h> 62 63 ISC_LANG_BEGINDECLS 64 65 #define DNS_SDLZFLAG_THREADSAFE 0x00000001U 66 #define DNS_SDLZFLAG_RELATIVEOWNER 0x00000002U 67 #define DNS_SDLZFLAG_RELATIVERDATA 0x00000004U 68 69 /* A simple DLZ database. */ 70 typedef struct dns_sdlz_db dns_sdlz_db_t; 71 72 /* A simple DLZ database lookup in progress. */ 73 typedef struct dns_sdlzlookup dns_sdlzlookup_t; 74 75 /* A simple DLZ database traversal in progress. */ 76 typedef struct dns_sdlzallnodes dns_sdlzallnodes_t; 77 78 typedef isc_result_t (*dns_sdlzallnodesfunc_t)(const char *zone, 79 void *driverarg, 80 void *dbdata, 81 dns_sdlzallnodes_t *allnodes); 82 /*%< 83 * Method prototype. Drivers implementing the SDLZ interface may 84 * supply an all nodes method. This method is called when the DNS 85 * server is performing a zone transfer query, after the allow zone 86 * transfer method has been called. This method is only called if the 87 * allow zone transfer method returned ISC_R_SUCCESS. This method and 88 * the allow zone transfer method are both required for zone transfers 89 * to be supported. If the driver generates data dynamically (instead 90 * of searching in a database for it) it should not implement this 91 * function as a zone transfer would be meaningless. A SDLZ driver 92 * does not have to implement an all nodes method. 93 */ 94 95 typedef isc_result_t (*dns_sdlzallowzonexfr_t)(void *driverarg, 96 void *dbdata, const char *name, 97 const char *client); 98 99 /*%< 100 * Method prototype. Drivers implementing the SDLZ interface may 101 * supply an allow zone transfer method. This method is called when 102 * the DNS server is performing a zone transfer query, before the all 103 * nodes method can be called. This method and the all node method 104 * are both required for zone transfers to be supported. If the 105 * driver generates data dynamically (instead of searching in a 106 * database for it) it should not implement this function as a zone 107 * transfer would be meaningless. A SDLZ driver does not have to 108 * implement an allow zone transfer method. 109 * 110 * This method should return ISC_R_SUCCESS if the zone is supported by 111 * the database and a zone transfer is allowed for the specified 112 * client. If the zone is supported by the database, but zone 113 * transfers are not allowed for the specified client this method 114 * should return ISC_R_NOPERM.. Lastly the method should return 115 * ISC_R_NOTFOUND if the zone is not supported by the database. If an 116 * error occurs it should return a result code indicating the type of 117 * error. 118 */ 119 120 typedef isc_result_t (*dns_sdlzauthorityfunc_t)(const char *zone, 121 void *driverarg, void *dbdata, 122 dns_sdlzlookup_t *lookup); 123 124 /*%< 125 * Method prototype. Drivers implementing the SDLZ interface may 126 * supply an authority method. This method is called when the DNS 127 * server is performing a query, after both the find zone and lookup 128 * methods have been called. This method is required if the lookup 129 * function does not supply authority information for the dns 130 * record. A SDLZ driver does not have to implement an authority 131 * method. 132 */ 133 134 typedef isc_result_t (*dns_sdlzcreate_t)(const char *dlzname, 135 unsigned int argc, char *argv[], 136 void *driverarg, void **dbdata); 137 138 /*%< 139 * Method prototype. Drivers implementing the SDLZ interface may 140 * supply a create method. This method is called when the DNS server 141 * is starting up and creating drivers for use later. A SDLZ driver 142 * does not have to implement a create method. 143 */ 144 145 typedef void (*dns_sdlzdestroy_t)(void *driverarg, void *dbdata); 146 147 /*%< 148 * Method prototype. Drivers implementing the SDLZ interface may 149 * supply a destroy method. This method is called when the DNS server 150 * is shutting down and no longer needs the driver. A SDLZ driver does 151 * not have to implement a destroy method. 152 */ 153 154 typedef isc_result_t 155 (*dns_sdlzfindzone_t)(void *driverarg, void *dbdata, const char *name); 156 157 /*%< 158 * Method prototype. Drivers implementing the SDLZ interface MUST 159 * supply a find zone method. This method is called when the DNS 160 * server is performing a query to to determine if 'name' is a 161 * supported dns zone. The find zone method will be called with the 162 * longest possible name first, and continue to be called with 163 * successively shorter domain names, until any of the following 164 * occur: 165 * 166 * \li 1) the function returns (ISC_R_SUCCESS) indicating a zone name 167 * match. 168 * 169 * \li 2) a problem occurs, and the functions returns anything other than 170 * (ISC_R_NOTFOUND) 171 * 172 * \li 3) we run out of domain name labels. I.E. we have tried the 173 * shortest domain name 174 * 175 * \li 4) the number of labels in the domain name is less than min_labels 176 * for dns_dlzfindzone 177 * 178 * The driver's find zone method should return ISC_R_SUCCESS if the 179 * zone is supported by the database. Otherwise it should return 180 * ISC_R_NOTFOUND, if the zone is not supported. If an error occurs 181 * it should return a result code indicating the type of error. 182 */ 183 184 typedef isc_result_t 185 (*dns_sdlzlookupfunc_t)(const char *zone, const char *name, void *driverarg, 186 void *dbdata, dns_sdlzlookup_t *lookup, 187 dns_clientinfomethods_t *methods, 188 dns_clientinfo_t *clientinfo); 189 190 /*%< 191 * Method prototype. Drivers implementing the SDLZ interface MUST 192 * supply a lookup method. This method is called when the 193 * DNS server is performing a query, after the find zone and before any 194 * other methods have been called. This function returns DNS record 195 * information using the dns_sdlz_putrr and dns_sdlz_putsoa functions. 196 * If this function supplies authority information for the DNS record 197 * the authority method is not required. If it does not, the 198 * authority function is required. 199 * 200 * The 'methods' and 'clientinfo' args allow an SDLZ driver to retrieve 201 * information about the querying client (such as source IP address) 202 * from the caller. 203 */ 204 205 typedef isc_result_t (*dns_sdlznewversion_t)(const char *zone, 206 void *driverarg, void *dbdata, 207 void **versionp); 208 /*%< 209 * Method prototype. Drivers implementing the SDLZ interface may 210 * supply a newversion method. This method is called to start a 211 * write transaction on a zone and should only be implemented by 212 * writeable backends. 213 * When implemented, the driver should create a new transaction, and 214 * fill *versionp with a pointer to the transaction state. The 215 * closeversion function will be called to close the transaction. 216 */ 217 218 typedef void (*dns_sdlzcloseversion_t)(const char *zone, isc_boolean_t commit, 219 void *driverarg, void *dbdata, 220 void **versionp); 221 /*%< 222 * Method prototype. Drivers implementing the SDLZ interface must 223 * supply a closeversion method if they supply a newversion method. 224 * When implemented, the driver should close the given transaction, 225 * committing changes if 'commit' is ISC_TRUE. If 'commit' is not true 226 * then all changes should be discarded and the database rolled back. 227 * If the call is successful then *versionp should be set to NULL 228 */ 229 230 typedef isc_result_t (*dns_sdlzconfigure_t)(dns_view_t *view, void *driverarg, 231 void *dbdata); 232 /*%< 233 * Method prototype. Drivers implementing the SDLZ interface may 234 * supply a configure method. When supplied, it will be called 235 * immediately after the create method to give the driver a chance 236 * to configure writeable zones 237 */ 238 239 240 typedef isc_boolean_t (*dns_sdlzssumatch_t)(const char *signer, 241 const char *name, 242 const char *tcpaddr, 243 const char *type, 244 const char *key, 245 isc_uint32_t keydatalen, 246 unsigned char *keydata, 247 void *driverarg, 248 void *dbdata); 249 250 /*%< 251 * Method prototype. Drivers implementing the SDLZ interface may 252 * supply a ssumatch method. If supplied, then ssumatch will be 253 * called to authorize any zone updates. The driver should return 254 * ISC_TRUE to allow the update, and ISC_FALSE to deny it. For a DLZ 255 * controlled zone, this is the only access control on updates. 256 */ 257 258 259 typedef isc_result_t (*dns_sdlzmodrdataset_t)(const char *name, 260 const char *rdatastr, 261 void *driverarg, void *dbdata, 262 void *version); 263 /*%< 264 * Method prototype. Drivers implementing the SDLZ interface may 265 * supply addrdataset and subtractrdataset methods. If supplied, then these 266 * will be called when rdatasets are added/subtracted during 267 * updates. The version parameter comes from a call to the sdlz 268 * newversion() method from the driver. The rdataset parameter is a 269 * linearise string representation of the rdataset change. The format 270 * is the same as used by dig when displaying records. The fields are 271 * tab delimited. 272 */ 273 274 typedef isc_result_t (*dns_sdlzdelrdataset_t)(const char *name, 275 const char *type, 276 void *driverarg, void *dbdata, 277 void *version); 278 /*%< 279 * Method prototype. Drivers implementing the SDLZ interface may 280 * supply a delrdataset method. If supplied, then this 281 * function will be called when rdatasets are deleted during 282 * updates. The call should remove all rdatasets of the given type for 283 * the specified name. 284 */ 285 286 typedef struct dns_sdlzmethods { 287 dns_sdlzcreate_t create; 288 dns_sdlzdestroy_t destroy; 289 dns_sdlzfindzone_t findzone; 290 dns_sdlzlookupfunc_t lookup; 291 dns_sdlzauthorityfunc_t authority; 292 dns_sdlzallnodesfunc_t allnodes; 293 dns_sdlzallowzonexfr_t allowzonexfr; 294 dns_sdlznewversion_t newversion; 295 dns_sdlzcloseversion_t closeversion; 296 dns_sdlzconfigure_t configure; 297 dns_sdlzssumatch_t ssumatch; 298 dns_sdlzmodrdataset_t addrdataset; 299 dns_sdlzmodrdataset_t subtractrdataset; 300 dns_sdlzdelrdataset_t delrdataset; 301 } dns_sdlzmethods_t; 302 303 isc_result_t 304 dns_sdlzregister(const char *drivername, const dns_sdlzmethods_t *methods, 305 void *driverarg, unsigned int flags, isc_mem_t *mctx, 306 dns_sdlzimplementation_t **sdlzimp); 307 /*%< 308 * Register a dynamically loadable zones (dlz) driver for the database 309 * type 'drivername', implemented by the functions in '*methods'. 310 * 311 * sdlzimp must point to a NULL dns_sdlzimplementation_t pointer. 312 * That is, sdlzimp != NULL && *sdlzimp == NULL. It will be assigned 313 * a value that will later be used to identify the driver when 314 * deregistering it. 315 */ 316 317 void 318 dns_sdlzunregister(dns_sdlzimplementation_t **sdlzimp); 319 320 /*%< 321 * Removes the sdlz driver from the list of registered sdlz drivers. 322 * There must be no active sdlz drivers of this type when this 323 * function is called. 324 */ 325 326 typedef isc_result_t dns_sdlz_putnamedrr_t(dns_sdlzallnodes_t *allnodes, 327 const char *name, 328 const char *type, 329 dns_ttl_t ttl, 330 const char *data); 331 dns_sdlz_putnamedrr_t dns_sdlz_putnamedrr; 332 333 /*%< 334 * Add a single resource record to the allnodes structure to be later 335 * parsed into a zone transfer response. 336 */ 337 338 typedef isc_result_t dns_sdlz_putrr_t(dns_sdlzlookup_t *lookup, 339 const char *type, 340 dns_ttl_t ttl, 341 const char *data); 342 dns_sdlz_putrr_t dns_sdlz_putrr; 343 /*%< 344 * Add a single resource record to the lookup structure to be later 345 * parsed into a query response. 346 */ 347 348 typedef isc_result_t dns_sdlz_putsoa_t(dns_sdlzlookup_t *lookup, 349 const char *mname, 350 const char *rname, 351 isc_uint32_t serial); 352 dns_sdlz_putsoa_t dns_sdlz_putsoa; 353 /*%< 354 * This function may optionally be called from the 'authority' 355 * callback to simplify construction of the SOA record for 'zone'. It 356 * will provide a SOA listing 'mname' as as the master server and 357 * 'rname' as the responsible person mailbox. It is the 358 * responsibility of the driver to increment the serial number between 359 * responses if necessary. All other SOA fields will have reasonable 360 * default values. 361 */ 362 363 364 typedef isc_result_t dns_sdlz_setdb_t(dns_dlzdb_t *dlzdatabase, 365 dns_rdataclass_t rdclass, 366 dns_name_t *name, 367 dns_db_t **dbp); 368 dns_sdlz_setdb_t dns_sdlz_setdb; 369 /*%< 370 * Create the database pointers for a writeable SDLZ zone 371 */ 372 373 374 ISC_LANG_ENDDECLS 375 376 #endif /* SDLZ_H */ 377