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
94ISC_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
103typedef 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
121typedef 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
131typedef 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
140typedef 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
171typedef 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
181typedef 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 */
194typedef 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 */
204struct 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
212typedef isc_result_t (*dlzconfigure_callback_t)(dns_view_t *, dns_zone_t *);
213
214/*% An instance of a DLZ driver */
215struct 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
231isc_result_t
232dns_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
241isc_result_t
242dns_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
254void
255dns_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
263isc_result_t
264dns_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
272isc_result_t
273dns_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
286isc_result_t
287dns_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
311void
312dns_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
321typedef isc_result_t dns_dlz_writeablezone_t(dns_view_t *view,
322					     const char *zone_name);
323dns_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
330isc_result_t
331dns_dlzconfigure(dns_view_t *view, dlzconfigure_callback_t callback);
332/*%<
333 * call a DLZ drivers configure method, if supplied
334 */
335
336isc_boolean_t
337dns_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
344ISC_LANG_ENDDECLS
345
346#endif /* DLZ_H */
347