contrib/bind-9.5.2/lib/dns/include/dns/dlz.h

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