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
25 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
26 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
27 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
28 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
29 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
30 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
31 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
32 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
33 * SOFTWARE, EVEN IF ADVISED OF THE 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 */
84 /** use SSL for upstream query */
86 /** use TCP for upstream query */
88 /** delegpt from authoritative zone that is locally hosted */
95 * Nameservers for a delegation point.
99 struct delegpt_ns* next;
100 /** name of nameserver */
102 /** length of name */
104 /** number of cache lookups for the name */
105 int cache_lookup_count;
107 * If the name has been resolved. false if not queried for yet.
108 * true if the A, AAAA queries have been generated.
109 * marked true if those queries fail.
110 * and marked true if got4 and got6 are both true.
113 /** if the ipv4 address is in the delegpt, 0=not, 1=yes 2=negative,
114 * negative means it was done, but no content. */
116 /** if the ipv6 address is in the delegpt, 0=not, 1=yes 2=negative */
119 * If the name is parent-side only and thus dispreferred.
120 * Its addresses become dispreferred as well
123 /** if the parent-side ipv4 address has been looked up (last resort).
124 * Also enabled if a parent-side cache entry exists, or a parent-side
125 * negative-cache entry exists. */
127 /** if the parent-side ipv6 address has been looked up (last resort).
128 * Also enabled if a parent-side cache entry exists, or a parent-side
129 * negative-cache entry exists. */
131 /** the TLS authentication name, (if not NULL) to use. */
133 /** the port to use; it should mostly be the default 53 but configured
134 * upstreams can provide nondefault ports. */
139 * Address of target nameserver in delegation point.
141 struct delegpt_addr {
142 /** next delegation point in results */
143 struct delegpt_addr* next_result;
144 /** next delegation point in usable list */
145 struct delegpt_addr* next_usable;
146 /** next delegation point in all targets list */
147 struct delegpt_addr* next_target;
149 /** delegation point address */
150 struct sockaddr_storage addr;
151 /** length of addr */
153 /** number of attempts for this addr */
155 /** rtt stored here in the selection algorithm */
157 /** if true, the A or AAAA RR was bogus, so this address is bad.
158 * Also check the dp->bogus to see if everything is bogus. */
160 /** if true, this address is dispreferred: it is a lame IP address */
162 /** if the address is dnsseclame, but this cannot be cached, this
163 * option is useful to mark the address dnsseclame.
164 * This value is not copied in addr-copy and dp-copy. */
166 /** the TLS authentication name, (if not NULL) to use. */
171 * Create new delegation point.
172 * @param regional: where to allocate it.
173 * @return new delegation point or NULL on error.
175 struct delegpt* delegpt_create(struct regional* regional);
178 * Create a copy of a delegation point.
179 * @param dp: delegation point to copy.
180 * @param regional: where to allocate it.
181 * @return new delegation point or NULL on error.
183 struct delegpt* delegpt_copy(struct delegpt* dp, struct regional* regional);
186 * Set name of delegation point.
187 * @param dp: delegation point.
188 * @param regional: where to allocate the name copy.
189 * @param name: name to use.
190 * @return false on error.
192 int delegpt_set_name(struct delegpt* dp, struct regional* regional,
196 * Add a name to the delegation point.
197 * @param dp: delegation point.
198 * @param regional: where to allocate the info.
199 * @param name: domain name in wire format.
200 * @param lame: name is lame, disprefer it.
201 * @param tls_auth_name: TLS authentication name (or NULL).
202 * @param port: port to use for resolved addresses.
203 * @return false on error.
205 int delegpt_add_ns(struct delegpt* dp, struct regional* regional,
206 uint8_t* name, uint8_t lame, char* tls_auth_name, int port);
209 * Add NS rrset; calls add_ns repeatedly.
210 * @param dp: delegation point.
211 * @param regional: where to allocate the info.
212 * @param ns_rrset: NS rrset.
213 * @param lame: rrset is lame, disprefer it.
214 * @return 0 on alloc error.
216 int delegpt_rrset_add_ns(struct delegpt* dp, struct regional* regional,
217 struct ub_packed_rrset_key* ns_rrset, uint8_t lame);
220 * Add target address to the delegation point.
221 * @param dp: delegation point.
222 * @param regional: where to allocate the info.
223 * @param name: name for which target was found (must be in nslist).
224 * This name is marked resolved.
225 * @param namelen: length of name.
226 * @param addr: the address.
227 * @param addrlen: the length of addr.
228 * @param bogus: security status for the address, pass true if bogus.
229 * @param lame: address is lame.
230 * @param additions: will be set to 1 if a new address is added
231 * @return false on error.
233 int delegpt_add_target(struct delegpt* dp, struct regional* regional,
234 uint8_t* name, size_t namelen, struct sockaddr_storage* addr,
235 socklen_t addrlen, uint8_t bogus, uint8_t lame, int* additions);
238 * Add A RRset to delegpt.
239 * @param dp: delegation point.
240 * @param regional: where to allocate the info.
241 * @param rrset: RRset A to add.
242 * @param lame: rrset is lame, disprefer it.
243 * @param additions: will be set to 1 if a new address is added
244 * @return 0 on alloc error.
246 int delegpt_add_rrset_A(struct delegpt* dp, struct regional* regional,
247 struct ub_packed_rrset_key* rrset, uint8_t lame, int* additions);
250 * Add AAAA RRset to delegpt.
251 * @param dp: delegation point.
252 * @param regional: where to allocate the info.
253 * @param rrset: RRset AAAA to add.
254 * @param lame: rrset is lame, disprefer it.
255 * @param additions: will be set to 1 if a new address is added
256 * @return 0 on alloc error.
258 int delegpt_add_rrset_AAAA(struct delegpt* dp, struct regional* regional,
259 struct ub_packed_rrset_key* rrset, uint8_t lame, int* additions);
262 * Add any RRset to delegpt.
263 * Does not check for duplicates added.
264 * @param dp: delegation point.
265 * @param regional: where to allocate the info.
266 * @param rrset: RRset to add, NS, A, AAAA.
267 * @param lame: rrset is lame, disprefer it.
268 * @param additions: will be set to 1 if a new address is added
269 * @return 0 on alloc error.
271 int delegpt_add_rrset(struct delegpt* dp, struct regional* regional,
272 struct ub_packed_rrset_key* rrset, uint8_t lame, int* additions);
275 * Add address to the delegation point. No servername is associated or checked.
276 * @param dp: delegation point.
277 * @param regional: where to allocate the info.
278 * @param addr: the address.
279 * @param addrlen: the length of addr.
280 * @param bogus: if address is bogus.
281 * @param lame: if address is lame.
282 * @param tls_auth_name: TLS authentication name (or NULL).
283 * @param port: the port to use; if -1 the port is taken from addr.
284 * @param additions: will be set to 1 if a new address is added
285 * @return false on error.
287 int delegpt_add_addr(struct delegpt* dp, struct regional* regional,
288 struct sockaddr_storage* addr, socklen_t addrlen,
289 uint8_t bogus, uint8_t lame, char* tls_auth_name, int port,
293 * Find NS record in name list of delegation point.
294 * @param dp: delegation point.
295 * @param name: name of nameserver to look for, uncompressed wireformat.
296 * @param namelen: length of name.
297 * @return the ns structure or NULL if not found.
299 struct delegpt_ns* delegpt_find_ns(struct delegpt* dp, uint8_t* name,
303 * Find address record in total list of delegation point.
304 * @param dp: delegation point.
305 * @param addr: address
306 * @param addrlen: length of addr
307 * @return the addr structure or NULL if not found.
309 struct delegpt_addr* delegpt_find_addr(struct delegpt* dp,
310 struct sockaddr_storage* addr, socklen_t addrlen);
313 * Print the delegation point to the log. For debugging.
314 * @param v: verbosity value that is needed to emit to log.
315 * @param dp: delegation point.
317 void delegpt_log(enum verbosity_value v, struct delegpt* dp);
319 /** count NS and number missing for logging */
320 void delegpt_count_ns(struct delegpt* dp, size_t* numns, size_t* missing);
322 /** count addresses, and number in result and available lists, for logging */
323 void delegpt_count_addr(struct delegpt* dp, size_t* numaddr, size_t* numres,
327 * Add all usable targets to the result list.
328 * @param dp: delegation point.
330 void delegpt_add_unused_targets(struct delegpt* dp);
333 * Count number of missing targets. These are ns names with no resolved flag.
334 * @param dp: delegation point.
335 * @param alllame: if set, check if all the missing targets are lame.
336 * @return number of missing targets (or 0).
338 size_t delegpt_count_missing_targets(struct delegpt* dp, int* alllame);
340 /** count total number of targets in dp */
341 size_t delegpt_count_targets(struct delegpt* dp);
344 * Create new delegation point from a dns message
346 * Note that this method does not actually test to see if the message is an
347 * actual referral. It really is just checking to see if it can construct a
348 * delegation point, so the message could be of some other type (some ANSWER
349 * messages, some CNAME messages, generally.) Note that the resulting
350 * DelegationPoint will contain targets for all "relevant" glue (i.e.,
351 * address records whose ownernames match the target of one of the NS
352 * records), so if policy dictates that some glue should be discarded beyond
353 * that, discard it before calling this method. Note that this method will
354 * find "glue" in either the ADDITIONAL section or the ANSWER section.
356 * @param msg: the dns message, referral.
357 * @param regional: where to allocate delegation point.
358 * @return new delegation point or NULL on alloc error, or if the
359 * message was not appropriate.
361 struct delegpt* delegpt_from_message(struct dns_msg* msg,
362 struct regional* regional);
365 * Mark negative return in delegation point for specific nameserver.
366 * sets the got4 or got6 to negative, updates the ns->resolved.
367 * @param ns: the nameserver in the delegpt.
368 * @param qtype: A or AAAA (host order).
370 void delegpt_mark_neg(struct delegpt_ns* ns, uint16_t qtype);
373 * Add negative message to delegation point.
374 * @param dp: delegation point.
375 * @param msg: the message added, marks off A or AAAA from an NS entry.
377 void delegpt_add_neg_msg(struct delegpt* dp, struct msgreply_entry* msg);
380 * Register the fact that there is no ipv6 and thus AAAAs are not going
381 * to be queried for or be useful.
382 * @param dp: the delegation point. Updated to reflect no ipv6.
384 void delegpt_no_ipv6(struct delegpt* dp);
387 * Register the fact that there is no ipv4 and thus As are not going
388 * to be queried for or be useful.
389 * @param dp: the delegation point. Updated to reflect no ipv4.
391 void delegpt_no_ipv4(struct delegpt* dp);
394 * create malloced delegation point, with the given name
395 * @param name: uncompressed wireformat of delegpt name.
396 * @return NULL on alloc failure
398 struct delegpt* delegpt_create_mlc(uint8_t* name);
401 * free malloced delegation point.
402 * @param dp: must have been created with delegpt_create_mlc, free'd.
404 void delegpt_free_mlc(struct delegpt* dp);
407 * Set name of delegation point.
408 * @param dp: delegation point. malloced.
409 * @param name: name to use.
410 * @return false on error.
412 int delegpt_set_name_mlc(struct delegpt* dp, uint8_t* name);
415 * add a name to malloced delegation point.
416 * @param dp: must have been created with delegpt_create_mlc.
417 * @param name: the name to add.
418 * @param lame: the name is lame, disprefer.
419 * @param tls_auth_name: TLS authentication name (or NULL).
420 * @param port: port to use for resolved addresses.
421 * @return false on error.
423 int delegpt_add_ns_mlc(struct delegpt* dp, uint8_t* name, uint8_t lame,
424 char* tls_auth_name, int port);
427 * add an address to a malloced delegation point.
428 * @param dp: must have been created with delegpt_create_mlc.
429 * @param addr: the address.
430 * @param addrlen: the length of addr.
431 * @param bogus: if address is bogus.
432 * @param lame: if address is lame.
433 * @param tls_auth_name: TLS authentication name (or NULL).
434 * @param port: the port to use; if -1 the port is taken from addr.
435 * @return false on error.
437 int delegpt_add_addr_mlc(struct delegpt* dp, struct sockaddr_storage* addr,
438 socklen_t addrlen, uint8_t bogus, uint8_t lame, char* tls_auth_name,
442 * Add target address to the delegation point.
443 * @param dp: must have been created with delegpt_create_mlc.
444 * @param name: name for which target was found (must be in nslist).
445 * This name is marked resolved.
446 * @param namelen: length of name.
447 * @param addr: the address.
448 * @param addrlen: the length of addr.
449 * @param bogus: security status for the address, pass true if bogus.
450 * @param lame: address is lame.
451 * @return false on error.
453 int delegpt_add_target_mlc(struct delegpt* dp, uint8_t* name, size_t namelen,
454 struct sockaddr_storage* addr, socklen_t addrlen, uint8_t bogus,
457 /** get memory in use by dp */
458 size_t delegpt_get_mem(struct delegpt* dp);
461 * See if the addr is on the result list.
462 * @param dp: delegation point.
463 * @param find: the pointer is searched for on the result list.
464 * @return 1 if found, 0 if not found.
466 int delegpt_addr_on_result_list(struct delegpt* dp, struct delegpt_addr* find);
469 * Remove the addr from the usable list.
470 * @param dp: the delegation point.
471 * @param del: the addr to remove from the list, the pointer is searched for.
473 void delegpt_usable_list_remove_addr(struct delegpt* dp,
474 struct delegpt_addr* del);
477 * Add the delegpt_addr back to the result list, if it is not already on
478 * the result list. Also removes it from the usable list.
479 * @param dp: delegation point.
480 * @param a: addr to add, nothing happens if it is already on the result list.
481 * It is removed from the usable list.
483 void delegpt_add_to_result_list(struct delegpt* dp, struct delegpt_addr* a);
485 #endif /* ITERATOR_ITER_DELEGPT_H */