xref: /freebsd/contrib/unbound/services/localzone.h (revision d2ce15bd43b3a1dcce08eecbff8d5d359946d972)
1 /*
2  * services/localzone.h - local zones authority service.
3  *
4  * Copyright (c) 2007, NLnet Labs. All rights reserved.
5  *
6  * This software is open source.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * Redistributions of source code must retain the above copyright notice,
13  * this list of conditions and the following disclaimer.
14  *
15  * Redistributions in binary form must reproduce the above copyright notice,
16  * this list of conditions and the following disclaimer in the documentation
17  * and/or other materials provided with the distribution.
18  *
19  * Neither the name of the NLNET LABS nor the names of its contributors may
20  * be used to endorse or promote products derived from this software without
21  * specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
25  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
26  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
27  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
28  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
32  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33  * POSSIBILITY OF SUCH DAMAGE.
34  */
35 
36 /**
37  * \file
38  *
39  * This file contains functions to enable local zone authority service.
40  */
41 
42 #ifndef SERVICES_LOCALZONE_H
43 #define SERVICES_LOCALZONE_H
44 #include "util/rbtree.h"
45 #include "util/locks.h"
46 struct ub_packed_rrset_key;
47 struct regional;
48 struct config_file;
49 struct edns_data;
50 struct query_info;
51 
52 /**
53  * Local zone type
54  * This type determines processing for queries that did not match
55  * local-data directly.
56  */
57 enum localzone_type {
58 	/** drop query */
59 	local_zone_deny = 0,
60 	/** answer with error */
61 	local_zone_refuse,
62 	/** answer nxdomain or nodata */
63 	local_zone_static,
64 	/** resolve normally */
65 	local_zone_transparent,
66 	/** do not block types at localdata names */
67 	local_zone_typetransparent,
68 	/** answer with data at zone apex */
69 	local_zone_redirect,
70 	/** remove default AS112 blocking contents for zone
71 	 * nodefault is used in config not during service. */
72 	local_zone_nodefault
73 };
74 
75 /**
76  * Authoritative local zones storage, shared.
77  */
78 struct local_zones {
79 	/** lock on the localzone tree */
80 	lock_quick_t lock;
81 	/** rbtree of struct local_zone */
82 	rbtree_t ztree;
83 };
84 
85 /**
86  * Local zone. A locally served authoritative zone.
87  */
88 struct local_zone {
89 	/** rbtree node, key is name and class */
90 	rbnode_t node;
91 	/** parent zone, if any. */
92 	struct local_zone* parent;
93 
94 	/** zone name, in uncompressed wireformat */
95 	uint8_t* name;
96 	/** length of zone name */
97 	size_t namelen;
98 	/** number of labels in zone name */
99 	int namelabs;
100 	/** the class of this zone.
101 	 * uses 'dclass' to not conflict with c++ keyword class. */
102 	uint16_t dclass;
103 
104 	/** lock on the data in the structure
105 	 * For the node, parent, name, namelen, namelabs, dclass, you
106 	 * need to also hold the zones_tree lock to change them (or to
107 	 * delete this zone) */
108 	lock_rw_t lock;
109 
110 	/** how to process zone */
111 	enum localzone_type type;
112 
113 	/** in this region the zone's data is allocated.
114 	 * the struct local_zone itself is malloced. */
115 	struct regional* region;
116 	/** local data for this zone
117 	 * rbtree of struct local_data */
118 	rbtree_t data;
119 	/** if data contains zone apex SOA data, this is a ptr to it. */
120 	struct ub_packed_rrset_key* soa;
121 };
122 
123 /**
124  * Local data. One domain name, and the RRs to go with it.
125  */
126 struct local_data {
127 	/** rbtree node, key is name only */
128 	rbnode_t node;
129 	/** domain name */
130 	uint8_t* name;
131 	/** length of name */
132 	size_t namelen;
133 	/** number of labels in name */
134 	int namelabs;
135 	/** the data rrsets, with different types, linked list.
136 	 * If this list is NULL, the node is an empty non-terminal. */
137 	struct local_rrset* rrsets;
138 };
139 
140 /**
141  * A local data RRset
142  */
143 struct local_rrset {
144 	/** next in list */
145 	struct local_rrset* next;
146 	/** RRset data item */
147 	struct ub_packed_rrset_key* rrset;
148 };
149 
150 /**
151  * Create local zones storage
152  * @return new struct or NULL on error.
153  */
154 struct local_zones* local_zones_create(void);
155 
156 /**
157  * Delete local zones storage
158  * @param zones: to delete.
159  */
160 void local_zones_delete(struct local_zones* zones);
161 
162 /**
163  * Apply config settings; setup the local authoritative data.
164  * Takes care of locking.
165  * @param zones: is set up.
166  * @param cfg: config data.
167  * @return false on error.
168  */
169 int local_zones_apply_cfg(struct local_zones* zones, struct config_file* cfg);
170 
171 /**
172  * Compare two local_zone entries in rbtree. Sort hierarchical but not
173  * canonical
174  * @param z1: zone 1
175  * @param z2: zone 2
176  * @return: -1, 0, +1 comparison value.
177  */
178 int local_zone_cmp(const void* z1, const void* z2);
179 
180 /**
181  * Compare two local_data entries in rbtree. Sort canonical.
182  * @param d1: data 1
183  * @param d2: data 2
184  * @return: -1, 0, +1 comparison value.
185  */
186 int local_data_cmp(const void* d1, const void* d2);
187 
188 /**
189  * Delete one zone
190  * @param z: to delete.
191  */
192 void local_zone_delete(struct local_zone* z);
193 
194 /**
195  * Lookup zone that contains the given name, class.
196  * User must lock the tree or result zone.
197  * @param zones: the zones tree
198  * @param name: dname to lookup
199  * @param len: length of name.
200  * @param labs: labelcount of name.
201  * @param dclass: class to lookup.
202  * @return closest local_zone or NULL if no covering zone is found.
203  */
204 struct local_zone* local_zones_lookup(struct local_zones* zones,
205 	uint8_t* name, size_t len, int labs, uint16_t dclass);
206 
207 /**
208  * Debug helper. Print all zones
209  * Takes care of locking.
210  * @param zones: the zones tree
211  */
212 void local_zones_print(struct local_zones* zones);
213 
214 /**
215  * Answer authoritatively for local zones.
216  * Takes care of locking.
217  * @param zones: the stored zones (shared, read only).
218  * @param qinfo: query info (parsed).
219  * @param edns: edns info (parsed).
220  * @param buf: buffer with query ID and flags, also for reply.
221  * @param temp: temporary storage region.
222  * @return true if answer is in buffer. false if query is not answered
223  * by authority data. If the reply should be dropped altogether, the return
224  * value is true, but the buffer is cleared (empty).
225  */
226 int local_zones_answer(struct local_zones* zones, struct query_info* qinfo,
227 	struct edns_data* edns, ldns_buffer* buf, struct regional* temp);
228 
229 /**
230  * Parse the string into localzone type.
231  *
232  * @param str: string to parse
233  * @param t: local zone type returned here.
234  * @return 0 on parse error.
235  */
236 int local_zone_str2type(const char* str, enum localzone_type* t);
237 
238 /**
239  * Print localzone type to a string.  Pointer to a constant string.
240  *
241  * @param t: local zone type.
242  * @return constant string that describes type.
243  */
244 const char* local_zone_type2str(enum localzone_type t);
245 
246 /**
247  * Find zone that with exactly given name, class.
248  * User must lock the tree or result zone.
249  * @param zones: the zones tree
250  * @param name: dname to lookup
251  * @param len: length of name.
252  * @param labs: labelcount of name.
253  * @param dclass: class to lookup.
254  * @return the exact local_zone or NULL.
255  */
256 struct local_zone* local_zones_find(struct local_zones* zones,
257 	uint8_t* name, size_t len, int labs, uint16_t dclass);
258 
259 /**
260  * Add a new zone. Caller must hold the zones lock.
261  * Adjusts the other zones as well (parent pointers) after insertion.
262  * The zone must NOT exist (returns NULL and logs error).
263  * @param zones: the zones tree
264  * @param name: dname to add
265  * @param len: length of name.
266  * @param labs: labelcount of name.
267  * @param dclass: class to add.
268  * @param tp: type.
269  * @return local_zone or NULL on error, caller must printout memory error.
270  */
271 struct local_zone* local_zones_add_zone(struct local_zones* zones,
272 	uint8_t* name, size_t len, int labs, uint16_t dclass,
273 	enum localzone_type tp);
274 
275 /**
276  * Delete a zone. Caller must hold the zones lock.
277  * Adjusts the other zones as well (parent pointers) after insertion.
278  * @param zones: the zones tree
279  * @param zone: the zone to delete from tree. Also deletes zone from memory.
280  */
281 void local_zones_del_zone(struct local_zones* zones, struct local_zone* zone);
282 
283 /**
284  * Add RR data into the localzone data.
285  * Looks up the zone, if no covering zone, a transparent zone with the
286  * name of the RR is created.
287  * @param zones: the zones tree. Not locked by caller.
288  * @param rr: string with on RR.
289  * @param buf: buffer for scratch.
290  * @return false on failure.
291  */
292 int local_zones_add_RR(struct local_zones* zones, const char* rr,
293 	ldns_buffer* buf);
294 
295 /**
296  * Remove data from domain name in the tree.
297  * All types are removed. No effect if zone or name does not exist.
298  * @param zones: zones tree.
299  * @param name: dname to remove
300  * @param len: length of name.
301  * @param labs: labelcount of name.
302  * @param dclass: class to remove.
303  */
304 void local_zones_del_data(struct local_zones* zones,
305 	uint8_t* name, size_t len, int labs, uint16_t dclass);
306 
307 
308 /**
309  * Form wireformat from text format domain name.
310  * @param str: the domain name in text "www.example.com"
311  * @param res: resulting wireformat is stored here with malloc.
312  * @param len: length of resulting wireformat.
313  * @param labs: number of labels in resulting wireformat.
314  * @return false on error, syntax or memory. Also logged.
315  */
316 int parse_dname(const char* str, uint8_t** res, size_t* len, int* labs);
317 
318 #endif /* SERVICES_LOCALZONE_H */
319