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