1 /* $NetBSD: dlz.h,v 1.6 2014/12/10 04:37:58 christos Exp $ */ 2 3 /* 4 * Portions Copyright (C) 2005-2007, 2009-2013 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/dlz.h */ 58 59 #ifndef DLZ_H 60 #define DLZ_H 1 61 62 /***** 63 ***** Module Info 64 *****/ 65 66 /* 67 * DLZ Interface 68 * 69 * The DLZ interface allows zones to be looked up using a driver instead of 70 * Bind's default in memory zone table. 71 * 72 * 73 * Reliability: 74 * No anticipated impact. 75 * 76 * Resources: 77 * 78 * Security: 79 * No anticipated impact. 80 * 81 * Standards: 82 * None. 83 */ 84 85 /***** 86 ***** Imports 87 *****/ 88 89 #include <dns/clientinfo.h> 90 #include <dns/name.h> 91 #include <dns/types.h> 92 #include <dns/view.h> 93 #include <dst/dst.h> 94 95 #include <isc/lang.h> 96 97 ISC_LANG_BEGINDECLS 98 99 /*** 100 *** Types 101 ***/ 102 103 #define DNS_DLZ_MAGIC ISC_MAGIC('D','L','Z','D') 104 #define DNS_DLZ_VALID(dlz) ISC_MAGIC_VALID(dlz, DNS_DLZ_MAGIC) 105 106 typedef isc_result_t 107 (*dns_dlzallowzonexfr_t)(void *driverarg, void *dbdata, isc_mem_t *mctx, 108 dns_rdataclass_t rdclass, dns_name_t *name, 109 isc_sockaddr_t *clientaddr, 110 dns_db_t **dbp); 111 112 /*%< 113 * Method prototype. Drivers implementing the DLZ interface MUST 114 * supply an allow zone transfer method. This method is called when 115 * the DNS server is performing a zone transfer query. The driver's 116 * method should return ISC_R_SUCCESS and a database pointer to the 117 * name server if the zone is supported by the database, and zone 118 * transfer is allowed. Otherwise it will return ISC_R_NOTFOUND if 119 * the zone is not supported by the database, or ISC_R_NOPERM if zone 120 * transfers are not allowed. If an error occurs it should return a 121 * result code indicating the type of error. 122 */ 123 124 typedef isc_result_t 125 (*dns_dlzcreate_t)(isc_mem_t *mctx, const char *dlzname, unsigned int argc, 126 char *argv[], void *driverarg, void **dbdata); 127 128 /*%< 129 * Method prototype. Drivers implementing the DLZ interface MUST 130 * supply a create method. This method is called when the DNS server 131 * is starting up and creating drivers for use later. 132 */ 133 134 typedef void 135 (*dns_dlzdestroy_t)(void *driverarg, void **dbdata); 136 137 /*%< 138 * Method prototype. Drivers implementing the DLZ interface MUST 139 * supply a destroy method. This method is called when the DNS server 140 * is shutting down and no longer needs the driver. 141 */ 142 143 typedef isc_result_t 144 (*dns_dlzfindzone_t)(void *driverarg, void *dbdata, isc_mem_t *mctx, 145 dns_rdataclass_t rdclass, dns_name_t *name, 146 dns_clientinfomethods_t *methods, 147 dns_clientinfo_t *clientinfo, 148 dns_db_t **dbp); 149 150 /*%< 151 * Method prototype. Drivers implementing the DLZ interface MUST 152 * supply a find zone method. This method is called when the DNS 153 * server is performing a query. The find zone method will be called 154 * with the longest possible name first, and continue to be called 155 * with successively shorter domain names, until any of the following 156 * occur: 157 * 158 * \li 1) a match is found, and the function returns (ISC_R_SUCCESS) 159 * 160 * \li 2) a problem occurs, and the functions returns anything other 161 * than (ISC_R_NOTFOUND) 162 * \li 3) we run out of domain name labels. I.E. we have tried the 163 * shortest domain name 164 * \li 4) the number of labels in the domain name is less than 165 * min_labels for dns_dlzfindzone 166 * 167 * The driver's find zone method should return ISC_R_SUCCESS and a 168 * database pointer to the name server if the zone is supported by the 169 * database. Otherwise it will return ISC_R_NOTFOUND, and a null 170 * pointer if the zone is not supported. If an error occurs it should 171 * return a result code indicating the type of error. 172 */ 173 174 175 typedef isc_result_t 176 (*dns_dlzconfigure_t)(void *driverarg, void *dbdata, 177 dns_view_t *view, dns_dlzdb_t *dlzdb); 178 /*%< 179 * Method prototype. Drivers implementing the DLZ interface may 180 * optionally supply a configure method. If supplied, this will be 181 * called immediately after the create method is called. The driver 182 * may call configuration functions during the configure call 183 */ 184 185 186 typedef isc_boolean_t (*dns_dlzssumatch_t)(dns_name_t *signer, 187 dns_name_t *name, 188 isc_netaddr_t *tcpaddr, 189 dns_rdatatype_t type, 190 const dst_key_t *key, 191 void *driverarg, void *dbdata); 192 /*%< 193 * Method prototype. Drivers implementing the DLZ interface may 194 * optionally supply a ssumatch method. If supplied, this will be 195 * called to authorize update requests 196 */ 197 198 /*% the methods supplied by a DLZ driver */ 199 typedef struct dns_dlzmethods { 200 dns_dlzcreate_t create; 201 dns_dlzdestroy_t destroy; 202 dns_dlzfindzone_t findzone; 203 dns_dlzallowzonexfr_t allowzonexfr; 204 dns_dlzconfigure_t configure; 205 dns_dlzssumatch_t ssumatch; 206 } dns_dlzmethods_t; 207 208 /*% information about a DLZ driver */ 209 struct dns_dlzimplementation { 210 const char *name; 211 const dns_dlzmethods_t *methods; 212 isc_mem_t *mctx; 213 void *driverarg; 214 ISC_LINK(dns_dlzimplementation_t) link; 215 }; 216 217 typedef isc_result_t (*dlzconfigure_callback_t)(dns_view_t *, dns_dlzdb_t *, 218 dns_zone_t *); 219 220 /*% An instance of a DLZ driver */ 221 struct dns_dlzdb { 222 unsigned int magic; 223 isc_mem_t *mctx; 224 dns_dlzimplementation_t *implementation; 225 void *dbdata; 226 dlzconfigure_callback_t configure_callback; 227 isc_boolean_t search; 228 char *dlzname; 229 ISC_LINK(dns_dlzdb_t) link; 230 dns_ssutable_t *ssutable; 231 }; 232 233 234 /*** 235 *** Method declarations 236 ***/ 237 238 isc_result_t 239 dns_dlzallowzonexfr(dns_view_t *view, dns_name_t *name, 240 isc_sockaddr_t *clientaddr, dns_db_t **dbp); 241 242 /*%< 243 * This method is called when the DNS server is performing a zone 244 * transfer query. It will call the DLZ driver's allow zone transfer 245 * method. 246 */ 247 248 isc_result_t 249 dns_dlzcreate(isc_mem_t *mctx, const char *dlzname, 250 const char *drivername, unsigned int argc, 251 char *argv[], dns_dlzdb_t **dbp); 252 253 /*%< 254 * This method is called when the DNS server is starting up and 255 * creating drivers for use later. It will search the DLZ driver list 256 * for 'drivername' and return a DLZ driver via dbp if a match is 257 * found. If the DLZ driver supplies a create method, this function 258 * will call it. 259 */ 260 261 void 262 dns_dlzdestroy(dns_dlzdb_t **dbp); 263 264 /*%< 265 * This method is called when the DNS server is shutting down and no 266 * longer needs the driver. If the DLZ driver supplies a destroy 267 * methods, this function will call it. 268 */ 269 270 isc_result_t 271 dns_dlzregister(const char *drivername, const dns_dlzmethods_t *methods, 272 void *driverarg, isc_mem_t *mctx, 273 dns_dlzimplementation_t **dlzimp); 274 275 /*%< 276 * Register a dynamically loadable zones (DLZ) driver for the database 277 * type 'drivername', implemented by the functions in '*methods'. 278 * 279 * dlzimp must point to a NULL dlz_implementation_t pointer. That is, 280 * dlzimp != NULL && *dlzimp == NULL. It will be assigned a value that 281 * will later be used to identify the driver when deregistering it. 282 */ 283 284 isc_result_t 285 dns_dlzstrtoargv(isc_mem_t *mctx, char *s, unsigned int *argcp, char ***argvp); 286 287 /*%< 288 * This method is called when the name server is starting up to parse 289 * the DLZ driver command line from named.conf. Basically it splits 290 * up a string into and argc / argv. The primary difference of this 291 * method is items between braces { } are considered only 1 word. for 292 * example the command line "this is { one grouped phrase } and this 293 * isn't" would be parsed into: 294 * 295 * \li argv[0]: "this" 296 * \li argv[1]: "is" 297 * \li argv{2]: " one grouped phrase " 298 * \li argv[3]: "and" 299 * \li argv[4]: "this" 300 * \li argv{5}: "isn't" 301 * 302 * braces should NOT be nested, more than one grouping in the command 303 * line is allowed. Notice, argv[2] has an extra space at the 304 * beginning and end. Extra spaces are not stripped between a 305 * grouping. You can do so in your driver if needed, or be sure not 306 * to put extra spaces before / after the braces. 307 */ 308 309 void 310 dns_dlzunregister(dns_dlzimplementation_t **dlzimp); 311 312 /*%< 313 * Removes the dlz driver from the list of registered dlz drivers. 314 * There must be no active dlz drivers of this type when this function 315 * is called. 316 */ 317 318 319 typedef isc_result_t dns_dlz_writeablezone_t(dns_view_t *view, 320 dns_dlzdb_t *dlzdb, 321 const char *zone_name); 322 dns_dlz_writeablezone_t dns_dlz_writeablezone; 323 /*%< 324 * creates a writeable DLZ zone. Must be called from within the 325 * configure() method of a DLZ driver. 326 */ 327 328 329 isc_result_t 330 dns_dlzconfigure(dns_view_t *view, dns_dlzdb_t *dlzdb, 331 dlzconfigure_callback_t callback); 332 /*%< 333 * call a DLZ drivers configure method, if supplied 334 */ 335 336 isc_boolean_t 337 dns_dlz_ssumatch(dns_dlzdb_t *dlzdatabase, 338 dns_name_t *signer, dns_name_t *name, isc_netaddr_t *tcpaddr, 339 dns_rdatatype_t type, const dst_key_t *key); 340 /*%< 341 * call a DLZ drivers ssumatch method, if supplied. Otherwise return ISC_FALSE 342 */ 343 344 ISC_LANG_ENDDECLS 345 346 #endif /* DLZ_H */ 347