2 * iterator/iter_delegpt.h - delegation point with NS and address information.
4 * Copyright (c) 2007, NLnet Labs. All rights reserved.
6 * This software is open source.
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
12 * Redistributions of source code must retain the above copyright notice,
13 * this list of conditions and the following disclaimer.
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.
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.
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.
39 * This file implements the Delegation Point. It contains a list of name servers
40 * and their addresses if known.
43 #ifndef ITERATOR_ITER_DELEGPT_H
44 #define ITERATOR_ITER_DELEGPT_H
50 struct ub_packed_rrset_key;
51 struct msgreply_entry;
55 * For a domain name, the NS rrset, and the A and AAAA records for those.
58 /** the domain name of the delegation point. */
60 /** length of the delegation point name */
62 /** number of labels in delegation point */
65 /** the nameservers, names from the NS RRset rdata. */
66 struct delegpt_ns* nslist;
67 /** the target addresses for delegation */
68 struct delegpt_addr* target_list;
69 /** the list of usable targets; subset of target_list
70 * the items in this list are not part of the result list. */
71 struct delegpt_addr* usable_list;
72 /** the list of returned targets; subset of target_list */
73 struct delegpt_addr* result_list;
75 /** if true, the NS RRset was bogus. All info is bad. */
77 /** if true, the parent-side NS record has been applied:
78 * its names have been added and their addresses can follow later.
79 * Also true if the delegationpoint was created from a delegation
80 * message and thus contains the parent-side-info already. */
81 uint8_t has_parent_side_NS;
82 /** for assertions on type of delegpt */
87 * Nameservers for a delegation point.
91 struct delegpt_ns* next;
92 /** name of nameserver */
97 * If the name has been resolved. false if not queried for yet.
98 * true if the A, AAAA queries have been generated.
99 * marked true if those queries fail.
100 * and marked true if got4 and got6 are both true.
103 /** if the ipv4 address is in the delegpt */
105 /** if the ipv6 address is in the delegpt */
108 * If the name is parent-side only and thus dispreferred.
109 * Its addresses become dispreferred as well
112 /** if the parent-side ipv4 address has been looked up (last resort).
113 * Also enabled if a parent-side cache entry exists, or a parent-side
114 * negative-cache entry exists. */
116 /** if the parent-side ipv6 address has been looked up (last resort).
117 * Also enabled if a parent-side cache entry exists, or a parent-side
118 * negative-cache entry exists. */
123 * Address of target nameserver in delegation point.
125 struct delegpt_addr {
126 /** next delegation point in results */
127 struct delegpt_addr* next_result;
128 /** next delegation point in usable list */
129 struct delegpt_addr* next_usable;
130 /** next delegation point in all targets list */
131 struct delegpt_addr* next_target;
133 /** delegation point address */
134 struct sockaddr_storage addr;
135 /** length of addr */
137 /** number of attempts for this addr */
139 /** rtt stored here in the selection algorithm */
141 /** if true, the A or AAAA RR was bogus, so this address is bad.
142 * Also check the dp->bogus to see if everything is bogus. */
144 /** if true, this address is dispreferred: it is a lame IP address */
149 * Create new delegation point.
150 * @param regional: where to allocate it.
151 * @return new delegation point or NULL on error.
153 struct delegpt* delegpt_create(struct regional* regional);
156 * Create a copy of a delegation point.
157 * @param dp: delegation point to copy.
158 * @param regional: where to allocate it.
159 * @return new delegation point or NULL on error.
161 struct delegpt* delegpt_copy(struct delegpt* dp, struct regional* regional);
164 * Set name of delegation point.
165 * @param dp: delegation point.
166 * @param regional: where to allocate the name copy.
167 * @param name: name to use.
168 * @return false on error.
170 int delegpt_set_name(struct delegpt* dp, struct regional* regional,
174 * Add a name to the delegation point.
175 * @param dp: delegation point.
176 * @param regional: where to allocate the info.
177 * @param name: domain name in wire format.
178 * @param lame: name is lame, disprefer it.
179 * @return false on error.
181 int delegpt_add_ns(struct delegpt* dp, struct regional* regional,
182 uint8_t* name, int lame);
185 * Add NS rrset; calls add_ns repeatedly.
186 * @param dp: delegation point.
187 * @param regional: where to allocate the info.
188 * @param ns_rrset: NS rrset.
189 * @param lame: rrset is lame, disprefer it.
190 * @return 0 on alloc error.
192 int delegpt_rrset_add_ns(struct delegpt* dp, struct regional* regional,
193 struct ub_packed_rrset_key* ns_rrset, int lame);
196 * Add target address to the delegation point.
197 * @param dp: delegation point.
198 * @param regional: where to allocate the info.
199 * @param name: name for which target was found (must be in nslist).
200 * This name is marked resolved.
201 * @param namelen: length of name.
202 * @param addr: the address.
203 * @param addrlen: the length of addr.
204 * @param bogus: security status for the address, pass true if bogus.
205 * @param lame: address is lame.
206 * @return false on error.
208 int delegpt_add_target(struct delegpt* dp, struct regional* regional,
209 uint8_t* name, size_t namelen, struct sockaddr_storage* addr,
210 socklen_t addrlen, int bogus, int lame);
213 * Add A RRset to delegpt.
214 * @param dp: delegation point.
215 * @param regional: where to allocate the info.
216 * @param rrset: RRset A to add.
217 * @param lame: rrset is lame, disprefer it.
218 * @return 0 on alloc error.
220 int delegpt_add_rrset_A(struct delegpt* dp, struct regional* regional,
221 struct ub_packed_rrset_key* rrset, int lame);
224 * Add AAAA RRset to delegpt.
225 * @param dp: delegation point.
226 * @param regional: where to allocate the info.
227 * @param rrset: RRset AAAA to add.
228 * @param lame: rrset is lame, disprefer it.
229 * @return 0 on alloc error.
231 int delegpt_add_rrset_AAAA(struct delegpt* dp, struct regional* regional,
232 struct ub_packed_rrset_key* rrset, int lame);
235 * Add any RRset to delegpt.
236 * Does not check for duplicates added.
237 * @param dp: delegation point.
238 * @param regional: where to allocate the info.
239 * @param rrset: RRset to add, NS, A, AAAA.
240 * @param lame: rrset is lame, disprefer it.
241 * @return 0 on alloc error.
243 int delegpt_add_rrset(struct delegpt* dp, struct regional* regional,
244 struct ub_packed_rrset_key* rrset, int lame);
247 * Add address to the delegation point. No servername is associated or checked.
248 * @param dp: delegation point.
249 * @param regional: where to allocate the info.
250 * @param addr: the address.
251 * @param addrlen: the length of addr.
252 * @param bogus: if address is bogus.
253 * @param lame: if address is lame.
254 * @return false on error.
256 int delegpt_add_addr(struct delegpt* dp, struct regional* regional,
257 struct sockaddr_storage* addr, socklen_t addrlen, int bogus, int lame);
260 * Find NS record in name list of delegation point.
261 * @param dp: delegation point.
262 * @param name: name of nameserver to look for, uncompressed wireformat.
263 * @param namelen: length of name.
264 * @return the ns structure or NULL if not found.
266 struct delegpt_ns* delegpt_find_ns(struct delegpt* dp, uint8_t* name,
270 * Find address record in total list of delegation point.
271 * @param dp: delegation point.
272 * @param addr: address
273 * @param addrlen: length of addr
274 * @return the addr structure or NULL if not found.
276 struct delegpt_addr* delegpt_find_addr(struct delegpt* dp,
277 struct sockaddr_storage* addr, socklen_t addrlen);
280 * Print the delegation point to the log. For debugging.
281 * @param v: verbosity value that is needed to emit to log.
282 * @param dp: delegation point.
284 void delegpt_log(enum verbosity_value v, struct delegpt* dp);
286 /** count NS and number missing for logging */
287 void delegpt_count_ns(struct delegpt* dp, size_t* numns, size_t* missing);
289 /** count addresses, and number in result and available lists, for logging */
290 void delegpt_count_addr(struct delegpt* dp, size_t* numaddr, size_t* numres,
294 * Add all usable targets to the result list.
295 * @param dp: delegation point.
297 void delegpt_add_unused_targets(struct delegpt* dp);
300 * Count number of missing targets. These are ns names with no resolved flag.
301 * @param dp: delegation point.
302 * @return number of missing targets (or 0).
304 size_t delegpt_count_missing_targets(struct delegpt* dp);
306 /** count total number of targets in dp */
307 size_t delegpt_count_targets(struct delegpt* dp);
310 * Create new delegation point from a dns message
312 * Note that this method does not actually test to see if the message is an
313 * actual referral. It really is just checking to see if it can construct a
314 * delegation point, so the message could be of some other type (some ANSWER
315 * messages, some CNAME messages, generally.) Note that the resulting
316 * DelegationPoint will contain targets for all "relevant" glue (i.e.,
317 * address records whose ownernames match the target of one of the NS
318 * records), so if policy dictates that some glue should be discarded beyond
319 * that, discard it before calling this method. Note that this method will
320 * find "glue" in either the ADDITIONAL section or the ANSWER section.
322 * @param msg: the dns message, referral.
323 * @param regional: where to allocate delegation point.
324 * @return new delegation point or NULL on alloc error, or if the
325 * message was not appropriate.
327 struct delegpt* delegpt_from_message(struct dns_msg* msg,
328 struct regional* regional);
331 * Add negative message to delegation point.
332 * @param dp: delegation point.
333 * @param msg: the message added, marks off A or AAAA from an NS entry.
335 void delegpt_add_neg_msg(struct delegpt* dp, struct msgreply_entry* msg);
338 * Register the fact that there is no ipv6 and thus AAAAs are not going
339 * to be queried for or be useful.
340 * @param dp: the delegation point. Updated to reflect no ipv6.
342 void delegpt_no_ipv6(struct delegpt* dp);
345 * Register the fact that there is no ipv4 and thus As are not going
346 * to be queried for or be useful.
347 * @param dp: the delegation point. Updated to reflect no ipv4.
349 void delegpt_no_ipv4(struct delegpt* dp);
352 * create malloced delegation point, with the given name
353 * @param name: uncompressed wireformat of degegpt name.
354 * @return NULL on alloc failure
356 struct delegpt* delegpt_create_mlc(uint8_t* name);
359 * free malloced delegation point.
360 * @param dp: must have been created with delegpt_create_mlc, free'd.
362 void delegpt_free_mlc(struct delegpt* dp);
365 * Set name of delegation point.
366 * @param dp: delegation point. malloced.
367 * @param name: name to use.
368 * @return false on error.
370 int delegpt_set_name_mlc(struct delegpt* dp, uint8_t* name);
373 * add a name to malloced delegation point.
374 * @param dp: must have been created with delegpt_create_mlc.
375 * @param name: the name to add.
376 * @param lame: the name is lame, disprefer.
377 * @return false on error.
379 int delegpt_add_ns_mlc(struct delegpt* dp, uint8_t* name, int lame);
382 * add an address to a malloced delegation point.
383 * @param dp: must have been created with delegpt_create_mlc.
384 * @param addr: the address.
385 * @param addrlen: the length of addr.
386 * @param bogus: if address is bogus.
387 * @param lame: if address is lame.
388 * @return false on error.
390 int delegpt_add_addr_mlc(struct delegpt* dp, struct sockaddr_storage* addr,
391 socklen_t addrlen, int bogus, int lame);
394 * Add target address to the delegation point.
395 * @param dp: must have been created with delegpt_create_mlc.
396 * @param name: name for which target was found (must be in nslist).
397 * This name is marked resolved.
398 * @param namelen: length of name.
399 * @param addr: the address.
400 * @param addrlen: the length of addr.
401 * @param bogus: security status for the address, pass true if bogus.
402 * @param lame: address is lame.
403 * @return false on error.
405 int delegpt_add_target_mlc(struct delegpt* dp, uint8_t* name, size_t namelen,
406 struct sockaddr_storage* addr, socklen_t addrlen, int bogus, int lame);
408 /** get memory in use by dp */
409 size_t delegpt_get_mem(struct delegpt* dp);
411 #endif /* ITERATOR_ITER_DELEGPT_H */