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/dlz.h> 61 62ISC_LANG_BEGINDECLS 63 64#define DNS_SDLZFLAG_THREADSAFE 0x00000001U 65#define DNS_SDLZFLAG_RELATIVEOWNER 0x00000002U 66#define DNS_SDLZFLAG_RELATIVERDATA 0x00000004U 67 68 /* A simple DLZ database. */ 69typedef struct dns_sdlz_db dns_sdlz_db_t; 70 71 /* A simple DLZ database lookup in progress. */ 72typedef struct dns_sdlzlookup dns_sdlzlookup_t; 73 74 /* A simple DLZ database traversal in progress. */ 75typedef struct dns_sdlzallnodes dns_sdlzallnodes_t; 76 77typedef isc_result_t (*dns_sdlzallnodesfunc_t)(const char *zone, 78 void *driverarg, 79 void *dbdata, 80 dns_sdlzallnodes_t *allnodes); 81/*%< 82 * Method prototype. Drivers implementing the SDLZ interface may 83 * supply an all nodes method. This method is called when the DNS 84 * server is performing a zone transfer query, after the allow zone 85 * transfer method has been called. This method is only called if the 86 * allow zone transfer method returned ISC_R_SUCCESS. This method and 87 * the allow zone transfer method are both required for zone transfers 88 * to be supported. If the driver generates data dynamically (instead 89 * of searching in a database for it) it should not implement this 90 * function as a zone transfer would be meaningless. A SDLZ driver 91 * does not have to implement an all nodes method. 92 */ 93 94typedef isc_result_t (*dns_sdlzallowzonexfr_t)(void *driverarg, 95 void *dbdata, const char *name, 96 const char *client); 97 98/*%< 99 * Method prototype. Drivers implementing the SDLZ interface may 100 * supply an allow zone transfer method. This method is called when 101 * the DNS server is performing a zone transfer query, before the all 102 * nodes method can be called. This method and the all node method 103 * are both required for zone transfers to be supported. If the 104 * driver generates data dynamically (instead of searching in a 105 * database for it) it should not implement this function as a zone 106 * transfer would be meaningless. A SDLZ driver does not have to 107 * implement an allow zone transfer method. 108 * 109 * This method should return ISC_R_SUCCESS if the zone is supported by 110 * the database and a zone transfer is allowed for the specified 111 * client. If the zone is supported by the database, but zone 112 * transfers are not allowed for the specified client this method 113 * should return ISC_R_NOPERM.. Lastly the method should return 114 * ISC_R_NOTFOUND if the zone is not supported by the database. If an 115 * error occurs it should return a result code indicating the type of 116 * error. 117 */ 118 119typedef isc_result_t (*dns_sdlzauthorityfunc_t)(const char *zone, 120 void *driverarg, void *dbdata, 121 dns_sdlzlookup_t *lookup); 122 123/*%< 124 * Method prototype. Drivers implementing the SDLZ interface may 125 * supply an authority method. This method is called when the DNS 126 * server is performing a query, after both the find zone and lookup 127 * methods have been called. This method is required if the lookup 128 * function does not supply authority information for the dns 129 * record. A SDLZ driver does not have to implement an authority 130 * method. 131 */ 132 133typedef isc_result_t (*dns_sdlzcreate_t)(const char *dlzname, 134 unsigned int argc, char *argv[], 135 void *driverarg, void **dbdata); 136 137/*%< 138 * Method prototype. Drivers implementing the SDLZ interface may 139 * supply a create method. This method is called when the DNS server 140 * is starting up and creating drivers for use later. A SDLZ driver 141 * does not have to implement a create method. 142 */ 143 144typedef void (*dns_sdlzdestroy_t)(void *driverarg, void *dbdata); 145 146/*%< 147 * Method prototype. Drivers implementing the SDLZ interface may 148 * supply a destroy method. This method is called when the DNS server 149 * is shutting down and no longer needs the driver. A SDLZ driver does 150 * not have to implement a destroy method. 151 */ 152 153typedef isc_result_t 154(*dns_sdlzfindzone_t)(void *driverarg, void *dbdata, const char *name); 155 156/*%< 157 * Method prototype. Drivers implementing the SDLZ interface MUST 158 * supply a find zone method. This method is called when the DNS 159 * server is performing a query to to determine if 'name' is a 160 * supported dns zone. The find zone method will be called with the 161 * longest possible name first, and continue to be called with 162 * successively shorter domain names, until any of the following 163 * occur: 164 * 165 * \li 1) the function returns (ISC_R_SUCCESS) indicating a zone name 166 * match. 167 * 168 * \li 2) a problem occurs, and the functions returns anything other than 169 * (ISC_R_NOTFOUND) 170 * 171 * \li 3) we run out of domain name labels. I.E. we have tried the 172 * shortest domain name 173 * 174 * \li 4) the number of labels in the domain name is less than min_labels 175 * for dns_dlzfindzone 176 * 177 * The driver's find zone method should return ISC_R_SUCCESS if the 178 * zone is supported by the database. Otherwise it should return 179 * ISC_R_NOTFOUND, if the zone is not supported. If an error occurs 180 * it should return a result code indicating the type of error. 181 */ 182 183typedef isc_result_t 184(*dns_sdlzlookupfunc_t)(const char *zone, const char *name, void *driverarg, 185 void *dbdata, dns_sdlzlookup_t *lookup); 186 187/*%< 188 * Method prototype. Drivers implementing the SDLZ interface MUST 189 * supply a lookup method. This method is called when the DNS server 190 * is performing a query, after the find zone and before any other 191 * methods have been called. This function returns record DNS record 192 * information using the dns_sdlz_putrr and dns_sdlz_putsoa functions. 193 * If this function supplies authority information for the DNS record 194 * the authority method is not required. If it does not, the 195 * authority function is required. A SDLZ driver must implement a 196 * lookup method. 197 */ 198 199typedef isc_result_t (*dns_sdlznewversion_t)(const char *zone, 200 void *driverarg, void *dbdata, 201 void **versionp); 202/*%< 203 * Method prototype. Drivers implementing the SDLZ interface may 204 * supply a newversion method. This method is called to start a 205 * write transaction on a zone and should only be implemented by 206 * writeable backends. 207 * When implemented, the driver should create a new transaction, and 208 * fill *versionp with a pointer to the transaction state. The 209 * closeversion function will be called to close the transaction. 210 */ 211 212typedef void (*dns_sdlzcloseversion_t)(const char *zone, isc_boolean_t commit, 213 void *driverarg, void *dbdata, 214 void **versionp); 215/*%< 216 * Method prototype. Drivers implementing the SDLZ interface must 217 * supply a closeversion method if they supply a newversion method. 218 * When implemented, the driver should close the given transaction, 219 * committing changes if 'commit' is ISC_TRUE. If 'commit' is not true 220 * then all changes should be discarded and the database rolled back. 221 * If the call is successful then *versionp should be set to NULL 222 */ 223 224typedef isc_result_t (*dns_sdlzconfigure_t)(dns_view_t *view, void *driverarg, 225 void *dbdata); 226/*%< 227 * Method prototype. Drivers implementing the SDLZ interface may 228 * supply a configure method. When supplied, it will be called 229 * immediately after the create method to give the driver a chance 230 * to configure writeable zones 231 */ 232 233 234typedef isc_boolean_t (*dns_sdlzssumatch_t)(const char *signer, 235 const char *name, 236 const char *tcpaddr, 237 const char *type, 238 const char *key, 239 isc_uint32_t keydatalen, 240 unsigned char *keydata, 241 void *driverarg, 242 void *dbdata); 243 244/*%< 245 * Method prototype. Drivers implementing the SDLZ interface may 246 * supply a ssumatch method. If supplied, then ssumatch will be 247 * called to authorize any zone updates. The driver should return 248 * ISC_TRUE to allow the update, and ISC_FALSE to deny it. For a DLZ 249 * controlled zone, this is the only access control on updates. 250 */ 251 252 253typedef isc_result_t (*dns_sdlzmodrdataset_t)(const char *name, 254 const char *rdatastr, 255 void *driverarg, void *dbdata, 256 void *version); 257/*%< 258 * Method prototype. Drivers implementing the SDLZ interface may 259 * supply addrdataset and subtractrdataset methods. If supplied, then these 260 * will be called when rdatasets are added/subtracted during 261 * updates. The version parameter comes from a call to the sdlz 262 * newversion() method from the driver. The rdataset parameter is a 263 * linearise string representation of the rdataset change. The format 264 * is the same as used by dig when displaying records. The fields are 265 * tab delimited. 266 */ 267 268typedef isc_result_t (*dns_sdlzdelrdataset_t)(const char *name, 269 const char *type, 270 void *driverarg, void *dbdata, 271 void *version); 272/*%< 273 * Method prototype. Drivers implementing the SDLZ interface may 274 * supply a delrdataset method. If supplied, then this 275 * function will be called when rdatasets are deleted during 276 * updates. The call should remove all rdatasets of the given type for 277 * the specified name. 278 */ 279 280typedef struct dns_sdlzmethods { 281 dns_sdlzcreate_t create; 282 dns_sdlzdestroy_t destroy; 283 dns_sdlzfindzone_t findzone; 284 dns_sdlzlookupfunc_t lookup; 285 dns_sdlzauthorityfunc_t authority; 286 dns_sdlzallnodesfunc_t allnodes; 287 dns_sdlzallowzonexfr_t allowzonexfr; 288 dns_sdlznewversion_t newversion; 289 dns_sdlzcloseversion_t closeversion; 290 dns_sdlzconfigure_t configure; 291 dns_sdlzssumatch_t ssumatch; 292 dns_sdlzmodrdataset_t addrdataset; 293 dns_sdlzmodrdataset_t subtractrdataset; 294 dns_sdlzdelrdataset_t delrdataset; 295} dns_sdlzmethods_t; 296 297isc_result_t 298dns_sdlzregister(const char *drivername, const dns_sdlzmethods_t *methods, 299 void *driverarg, unsigned int flags, isc_mem_t *mctx, 300 dns_sdlzimplementation_t **sdlzimp); 301/*%< 302 * Register a dynamically loadable zones (dlz) driver for the database 303 * type 'drivername', implemented by the functions in '*methods'. 304 * 305 * sdlzimp must point to a NULL dns_sdlzimplementation_t pointer. 306 * That is, sdlzimp != NULL && *sdlzimp == NULL. It will be assigned 307 * a value that will later be used to identify the driver when 308 * deregistering it. 309 */ 310 311void 312dns_sdlzunregister(dns_sdlzimplementation_t **sdlzimp); 313 314/*%< 315 * Removes the sdlz driver from the list of registered sdlz drivers. 316 * There must be no active sdlz drivers of this type when this 317 * function is called. 318 */ 319 320typedef isc_result_t dns_sdlz_putnamedrr_t(dns_sdlzallnodes_t *allnodes, 321 const char *name, 322 const char *type, 323 dns_ttl_t ttl, 324 const char *data); 325dns_sdlz_putnamedrr_t dns_sdlz_putnamedrr; 326 327/*%< 328 * Add a single resource record to the allnodes structure to be later 329 * parsed into a zone transfer response. 330 */ 331 332typedef isc_result_t dns_sdlz_putrr_t(dns_sdlzlookup_t *lookup, 333 const char *type, 334 dns_ttl_t ttl, 335 const char *data); 336dns_sdlz_putrr_t dns_sdlz_putrr; 337/*%< 338 * Add a single resource record to the lookup structure to be later 339 * parsed into a query response. 340 */ 341 342typedef isc_result_t dns_sdlz_putsoa_t(dns_sdlzlookup_t *lookup, 343 const char *mname, 344 const char *rname, 345 isc_uint32_t serial); 346dns_sdlz_putsoa_t dns_sdlz_putsoa; 347/*%< 348 * This function may optionally be called from the 'authority' 349 * callback to simplify construction of the SOA record for 'zone'. It 350 * will provide a SOA listing 'mname' as as the master server and 351 * 'rname' as the responsible person mailbox. It is the 352 * responsibility of the driver to increment the serial number between 353 * responses if necessary. All other SOA fields will have reasonable 354 * default values. 355 */ 356 357 358typedef isc_result_t dns_sdlz_setdb_t(dns_dlzdb_t *dlzdatabase, 359 dns_rdataclass_t rdclass, 360 dns_name_t *name, 361 dns_db_t **dbp); 362dns_sdlz_setdb_t dns_sdlz_setdb; 363/*%< 364 * Create the database pointers for a writeable SDLZ zone 365 */ 366 367 368ISC_LANG_ENDDECLS 369 370#endif /* SDLZ_H */ 371