contrib/bind9/lib/dns/include/dns/sdlz.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/sdlz.h */
  56
  57 #ifndef SDLZ_H
  58 #define SDLZ_H 1
  59
  60 #include <dns/dlz.h>
  61
  62 ISC_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. */
  69 typedef struct dns_sdlz_db dns_sdlz_db_t;
  70
  71  /* A simple DLZ database lookup in progress. */
  72 typedef struct dns_sdlzlookup dns_sdlzlookup_t;
  73
  74  /* A simple DLZ database traversal in progress. */
  75 typedef struct dns_sdlzallnodes dns_sdlzallnodes_t;
  76
  77 typedef 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
  94 typedef 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
 119 typedef 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
 133 typedef 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
 144 typedef 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
 153 typedef 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
 183 typedef 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
 199 typedef 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
 212 typedef 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
 224 typedef 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
 234 typedef 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
 253 typedef 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
 268 typedef 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
 280 typedef 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
 297 isc_result_t
 298 dns_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
 311 void
 312 dns_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
 320 typedef 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);
 325 dns_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
 332 typedef isc_result_t dns_sdlz_putrr_t(dns_sdlzlookup_t *lookup,
 333                                       const char *type,
 334                                       dns_ttl_t ttl,
 335                                       const char *data);
 336 dns_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
 342 typedef isc_result_t dns_sdlz_putsoa_t(dns_sdlzlookup_t *lookup,
 343                                        const char *mname,
 344                                        const char *rname,
 345                                        isc_uint32_t serial);
 346 dns_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
 358 typedef 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);
 362 dns_sdlz_setdb_t dns_sdlz_setdb;
 363 /*%<
 364  * Create the database pointers for a writeable SDLZ zone
 365  */
 366
 367
 368 ISC_LANG_ENDDECLS
 369
 370 #endif /* SDLZ_H */