contrib/bind9/lib/dns/include/dns/dlz.h

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