2 * Portions Copyright (C) 2005-2007, 2009-2012 Internet Systems Consortium, Inc. ("ISC")
3 * Portions Copyright (C) 1999-2001 Internet Software Consortium.
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.
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.
19 * Copyright (C) 2002 Stichting NLnet, Netherlands, stichting@nlnet.nl.
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
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.
35 * The development of Dynamically Loadable Zones (DLZ) for Bind 9 was
36 * conceived and contributed by Rob Butler.
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
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.
55 /*! \file dns/sdlz.h */
60 #include <dns/clientinfo.h>
65 #define DNS_SDLZFLAG_THREADSAFE 0x00000001U
66 #define DNS_SDLZFLAG_RELATIVEOWNER 0x00000002U
67 #define DNS_SDLZFLAG_RELATIVERDATA 0x00000004U
69 /* A simple DLZ database. */
70 typedef struct dns_sdlz_db dns_sdlz_db_t;
72 /* A simple DLZ database lookup in progress. */
73 typedef struct dns_sdlzlookup dns_sdlzlookup_t;
75 /* A simple DLZ database traversal in progress. */
76 typedef struct dns_sdlzallnodes dns_sdlzallnodes_t;
78 typedef isc_result_t (*dns_sdlzallnodesfunc_t)(const char *zone,
81 dns_sdlzallnodes_t *allnodes);
83 * Method prototype. Drivers implementing the SDLZ interface may
84 * supply an all nodes method. This method is called when the DNS
85 * server is performing a zone transfer query, after the allow zone
86 * transfer method has been called. This method is only called if the
87 * allow zone transfer method returned ISC_R_SUCCESS. This method and
88 * the allow zone transfer method are both required for zone transfers
89 * to be supported. If the driver generates data dynamically (instead
90 * of searching in a database for it) it should not implement this
91 * function as a zone transfer would be meaningless. A SDLZ driver
92 * does not have to implement an all nodes method.
95 typedef isc_result_t (*dns_sdlzallowzonexfr_t)(void *driverarg,
96 void *dbdata, const char *name,
100 * Method prototype. Drivers implementing the SDLZ interface may
101 * supply an allow zone transfer method. This method is called when
102 * the DNS server is performing a zone transfer query, before the all
103 * nodes method can be called. This method and the all node method
104 * are both required for zone transfers to be supported. If the
105 * driver generates data dynamically (instead of searching in a
106 * database for it) it should not implement this function as a zone
107 * transfer would be meaningless. A SDLZ driver does not have to
108 * implement an allow zone transfer method.
110 * This method should return ISC_R_SUCCESS if the zone is supported by
111 * the database and a zone transfer is allowed for the specified
112 * client. If the zone is supported by the database, but zone
113 * transfers are not allowed for the specified client this method
114 * should return ISC_R_NOPERM.. Lastly the method should return
115 * ISC_R_NOTFOUND if the zone is not supported by the database. If an
116 * error occurs it should return a result code indicating the type of
120 typedef isc_result_t (*dns_sdlzauthorityfunc_t)(const char *zone,
121 void *driverarg, void *dbdata,
122 dns_sdlzlookup_t *lookup);
125 * Method prototype. Drivers implementing the SDLZ interface may
126 * supply an authority method. This method is called when the DNS
127 * server is performing a query, after both the find zone and lookup
128 * methods have been called. This method is required if the lookup
129 * function does not supply authority information for the dns
130 * record. A SDLZ driver does not have to implement an authority
134 typedef isc_result_t (*dns_sdlzcreate_t)(const char *dlzname,
135 unsigned int argc, char *argv[],
136 void *driverarg, void **dbdata);
139 * Method prototype. Drivers implementing the SDLZ interface may
140 * supply a create method. This method is called when the DNS server
141 * is starting up and creating drivers for use later. A SDLZ driver
142 * does not have to implement a create method.
145 typedef void (*dns_sdlzdestroy_t)(void *driverarg, void *dbdata);
148 * Method prototype. Drivers implementing the SDLZ interface may
149 * supply a destroy method. This method is called when the DNS server
150 * is shutting down and no longer needs the driver. A SDLZ driver does
151 * not have to implement a destroy method.
155 (*dns_sdlzfindzone_t)(void *driverarg, void *dbdata, const char *name);
158 * Method prototype. Drivers implementing the SDLZ interface MUST
159 * supply a find zone method. This method is called when the DNS
160 * server is performing a query to to determine if 'name' is a
161 * supported dns zone. The find zone method will be called with the
162 * longest possible name first, and continue to be called with
163 * successively shorter domain names, until any of the following
166 * \li 1) the function returns (ISC_R_SUCCESS) indicating a zone name
169 * \li 2) a problem occurs, and the functions returns anything other than
172 * \li 3) we run out of domain name labels. I.E. we have tried the
173 * shortest domain name
175 * \li 4) the number of labels in the domain name is less than min_labels
176 * for dns_dlzfindzone
178 * The driver's find zone method should return ISC_R_SUCCESS if the
179 * zone is supported by the database. Otherwise it should return
180 * ISC_R_NOTFOUND, if the zone is not supported. If an error occurs
181 * it should return a result code indicating the type of error.
185 (*dns_sdlzlookupfunc_t)(const char *zone, const char *name, void *driverarg,
186 void *dbdata, dns_sdlzlookup_t *lookup,
187 dns_clientinfomethods_t *methods,
188 dns_clientinfo_t *clientinfo);
191 * Method prototype. Drivers implementing the SDLZ interface MUST
192 * supply a lookup method. This method is called when the
193 * DNS server is performing a query, after the find zone and before any
194 * other methods have been called. This function returns DNS record
195 * information using the dns_sdlz_putrr and dns_sdlz_putsoa functions.
196 * If this function supplies authority information for the DNS record
197 * the authority method is not required. If it does not, the
198 * authority function is required.
200 * The 'methods' and 'clientinfo' args allow an SDLZ driver to retrieve
201 * information about the querying client (such as source IP address)
205 typedef isc_result_t (*dns_sdlznewversion_t)(const char *zone,
206 void *driverarg, void *dbdata,
209 * Method prototype. Drivers implementing the SDLZ interface may
210 * supply a newversion method. This method is called to start a
211 * write transaction on a zone and should only be implemented by
212 * writeable backends.
213 * When implemented, the driver should create a new transaction, and
214 * fill *versionp with a pointer to the transaction state. The
215 * closeversion function will be called to close the transaction.
218 typedef void (*dns_sdlzcloseversion_t)(const char *zone, isc_boolean_t commit,
219 void *driverarg, void *dbdata,
222 * Method prototype. Drivers implementing the SDLZ interface must
223 * supply a closeversion method if they supply a newversion method.
224 * When implemented, the driver should close the given transaction,
225 * committing changes if 'commit' is ISC_TRUE. If 'commit' is not true
226 * then all changes should be discarded and the database rolled back.
227 * If the call is successful then *versionp should be set to NULL
230 typedef isc_result_t (*dns_sdlzconfigure_t)(dns_view_t *view, void *driverarg,
233 * Method prototype. Drivers implementing the SDLZ interface may
234 * supply a configure method. When supplied, it will be called
235 * immediately after the create method to give the driver a chance
236 * to configure writeable zones
240 typedef isc_boolean_t (*dns_sdlzssumatch_t)(const char *signer,
245 isc_uint32_t keydatalen,
246 unsigned char *keydata,
251 * Method prototype. Drivers implementing the SDLZ interface may
252 * supply a ssumatch method. If supplied, then ssumatch will be
253 * called to authorize any zone updates. The driver should return
254 * ISC_TRUE to allow the update, and ISC_FALSE to deny it. For a DLZ
255 * controlled zone, this is the only access control on updates.
259 typedef isc_result_t (*dns_sdlzmodrdataset_t)(const char *name,
260 const char *rdatastr,
261 void *driverarg, void *dbdata,
264 * Method prototype. Drivers implementing the SDLZ interface may
265 * supply addrdataset and subtractrdataset methods. If supplied, then these
266 * will be called when rdatasets are added/subtracted during
267 * updates. The version parameter comes from a call to the sdlz
268 * newversion() method from the driver. The rdataset parameter is a
269 * linearise string representation of the rdataset change. The format
270 * is the same as used by dig when displaying records. The fields are
274 typedef isc_result_t (*dns_sdlzdelrdataset_t)(const char *name,
276 void *driverarg, void *dbdata,
279 * Method prototype. Drivers implementing the SDLZ interface may
280 * supply a delrdataset method. If supplied, then this
281 * function will be called when rdatasets are deleted during
282 * updates. The call should remove all rdatasets of the given type for
283 * the specified name.
286 typedef struct dns_sdlzmethods {
287 dns_sdlzcreate_t create;
288 dns_sdlzdestroy_t destroy;
289 dns_sdlzfindzone_t findzone;
290 dns_sdlzlookupfunc_t lookup;
291 dns_sdlzauthorityfunc_t authority;
292 dns_sdlzallnodesfunc_t allnodes;
293 dns_sdlzallowzonexfr_t allowzonexfr;
294 dns_sdlznewversion_t newversion;
295 dns_sdlzcloseversion_t closeversion;
296 dns_sdlzconfigure_t configure;
297 dns_sdlzssumatch_t ssumatch;
298 dns_sdlzmodrdataset_t addrdataset;
299 dns_sdlzmodrdataset_t subtractrdataset;
300 dns_sdlzdelrdataset_t delrdataset;
304 dns_sdlzregister(const char *drivername, const dns_sdlzmethods_t *methods,
305 void *driverarg, unsigned int flags, isc_mem_t *mctx,
306 dns_sdlzimplementation_t **sdlzimp);
308 * Register a dynamically loadable zones (dlz) driver for the database
309 * type 'drivername', implemented by the functions in '*methods'.
311 * sdlzimp must point to a NULL dns_sdlzimplementation_t pointer.
312 * That is, sdlzimp != NULL && *sdlzimp == NULL. It will be assigned
313 * a value that will later be used to identify the driver when
318 dns_sdlzunregister(dns_sdlzimplementation_t **sdlzimp);
321 * Removes the sdlz driver from the list of registered sdlz drivers.
322 * There must be no active sdlz drivers of this type when this
323 * function is called.
326 typedef isc_result_t dns_sdlz_putnamedrr_t(dns_sdlzallnodes_t *allnodes,
331 dns_sdlz_putnamedrr_t dns_sdlz_putnamedrr;
334 * Add a single resource record to the allnodes structure to be later
335 * parsed into a zone transfer response.
338 typedef isc_result_t dns_sdlz_putrr_t(dns_sdlzlookup_t *lookup,
342 dns_sdlz_putrr_t dns_sdlz_putrr;
344 * Add a single resource record to the lookup structure to be later
345 * parsed into a query response.
348 typedef isc_result_t dns_sdlz_putsoa_t(dns_sdlzlookup_t *lookup,
351 isc_uint32_t serial);
352 dns_sdlz_putsoa_t dns_sdlz_putsoa;
354 * This function may optionally be called from the 'authority'
355 * callback to simplify construction of the SOA record for 'zone'. It
356 * will provide a SOA listing 'mname' as as the master server and
357 * 'rname' as the responsible person mailbox. It is the
358 * responsibility of the driver to increment the serial number between
359 * responses if necessary. All other SOA fields will have reasonable
364 typedef isc_result_t dns_sdlz_setdb_t(dns_dlzdb_t *dlzdatabase,
365 dns_rdataclass_t rdclass,
368 dns_sdlz_setdb_t dns_sdlz_setdb;
370 * Create the database pointers for a writeable SDLZ zone