/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
 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 */