xref: /freebsd/contrib/unbound/iterator/iter_fwd.h (revision 8d20be1e22095c27faf8fe8b2f0d089739cc742e)
1 /*
2  * iterator/iter_fwd.h - iterative resolver module forward zones.
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 assist the iterator module.
40  * Keep track of forward zones, and read those from config.
41  */
42 
43 #ifndef ITERATOR_ITER_FWD_H
44 #define ITERATOR_ITER_FWD_H
45 #include "util/rbtree.h"
46 struct config_file;
47 struct delegpt;
48 
49 /**
50  * Iterator forward zones structure
51  */
52 struct iter_forwards {
53 	/**
54 	 * Zones are stored in this tree. Sort order is specially chosen.
55 	 * first sorted on qclass. Then on dname in nsec-like order, so that
56 	 * a lookup on class, name will return an exact match or the closest
57 	 * match which gives the ancestor needed.
58 	 * contents of type iter_forward_zone.
59 	 */
60 	rbtree_t* tree;
61 };
62 
63 /**
64  * Iterator forward servers for a particular zone.
65  */
66 struct iter_forward_zone {
67 	/** redblacktree node, key is this structure: class and name */
68 	rbnode_t node;
69 	/** name */
70 	uint8_t* name;
71 	/** length of name */
72 	size_t namelen;
73 	/** number of labels in name */
74 	int namelabs;
75 	/** delegation point with forward server information for this zone.
76 	 * If NULL then this forward entry is used to indicate that a
77 	 * stub-zone with the same name exists, and should be used.
78 	 * This delegation point is malloced.
79 	 */
80 	struct delegpt* dp;
81 	/** pointer to parent in tree (or NULL if none) */
82 	struct iter_forward_zone* parent;
83 	/** class. host order. */
84 	uint16_t dclass;
85 };
86 
87 /**
88  * Create forwards
89  * @return new forwards or NULL on error.
90  */
91 struct iter_forwards* forwards_create(void);
92 
93 /**
94  * Delete forwards.
95  * @param fwd: to delete.
96  */
97 void forwards_delete(struct iter_forwards* fwd);
98 
99 /**
100  * Process forwards config.
101  * @param fwd: where to store.
102  * @param cfg: config options.
103  * @return 0 on error.
104  */
105 int forwards_apply_cfg(struct iter_forwards* fwd, struct config_file* cfg);
106 
107 /**
108  * Find forward zone information
109  * For this qname/qclass find forward zone information, returns delegation
110  * point with server names and addresses, or NULL if no forwarding is needed.
111  *
112  * @param fwd: forward storage.
113  * @param qname: The qname of the query.
114  * @param qclass: The qclass of the query.
115  * @return: A delegation point if the query has to be forwarded to that list,
116  *         otherwise null.
117  */
118 struct delegpt* forwards_lookup(struct iter_forwards* fwd,
119 	uint8_t* qname, uint16_t qclass);
120 
121 /**
122  * Same as forwards_lookup, but for the root only
123  * @param fwd: forward storage.
124  * @param qclass: The qclass of the query.
125  * @return: A delegation point if root forward exists, otherwise null.
126  */
127 struct delegpt* forwards_lookup_root(struct iter_forwards* fwd,
128 	uint16_t qclass);
129 
130 /**
131  * Find next root item in forwards lookup tree.
132  * @param fwd: the forward storage
133  * @param qclass: class to look at next, or higher.
134  * @return false if none found, or if true stored in qclass.
135  */
136 int forwards_next_root(struct iter_forwards* fwd, uint16_t* qclass);
137 
138 /**
139  * Get memory in use by forward storage
140  * @param fwd: forward storage.
141  * @return bytes in use
142  */
143 size_t forwards_get_mem(struct iter_forwards* fwd);
144 
145 /** compare two fwd entries */
146 int fwd_cmp(const void* k1, const void* k2);
147 
148 /**
149  * Add zone to forward structure. For external use since it recalcs
150  * the tree parents.
151  * @param fwd: the forward data structure
152  * @param c: class of zone
153  * @param dp: delegation point with name and target nameservers for new
154  *	forward zone. malloced.
155  * @return false on failure (out of memory);
156  */
157 int forwards_add_zone(struct iter_forwards* fwd, uint16_t c,
158 	struct delegpt* dp);
159 
160 /**
161  * Remove zone from forward structure. For external use since it
162  * recalcs the tree parents.
163  * @param fwd: the forward data structure
164  * @param c: class of zone
165  * @param nm: name of zone (in uncompressed wireformat).
166  */
167 void forwards_delete_zone(struct iter_forwards* fwd, uint16_t c, uint8_t* nm);
168 
169 /**
170  * Add stub hole (empty entry in forward table, that makes resolution skip
171  * a forward-zone because the stub zone should override the forward zone).
172  * Does not add one if not necessary.
173  * @param fwd: the forward data structure
174  * @param c: class of zone
175  * @param nm: name of zone (in uncompressed wireformat).
176  * @return false on failure (out of memory);
177  */
178 int forwards_add_stub_hole(struct iter_forwards* fwd, uint16_t c, uint8_t* nm);
179 
180 /**
181  * Remove stub hole, if one exists.
182  * @param fwd: the forward data structure
183  * @param c: class of zone
184  * @param nm: name of zone (in uncompressed wireformat).
185  */
186 void forwards_delete_stub_hole(struct iter_forwards* fwd, uint16_t c,
187 	uint8_t* nm);
188 
189 #endif /* ITERATOR_ITER_FWD_H */
190