xref: /freebsd/contrib/unbound/iterator/iter_delegpt.h (revision c7046f76c2c027b00c0e6ba57cfd28f1a78f5e23)
1 /*
2  * iterator/iter_delegpt.h - delegation point with NS and address information.
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
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.
34  */
35 
36 /**
37  * \file
38  *
39  * This file implements the Delegation Point. It contains a list of name servers
40  * and their addresses if known.
41  */
42 
43 #ifndef ITERATOR_ITER_DELEGPT_H
44 #define ITERATOR_ITER_DELEGPT_H
45 #include "util/log.h"
46 struct regional;
47 struct delegpt_ns;
48 struct delegpt_addr;
49 struct dns_msg;
50 struct ub_packed_rrset_key;
51 struct msgreply_entry;
52 
53 /**
54  * Delegation Point.
55  * For a domain name, the NS rrset, and the A and AAAA records for those.
56  */
57 struct delegpt {
58 	/** the domain name of the delegation point. */
59 	uint8_t* name;
60 	/** length of the delegation point name */
61 	size_t namelen;
62 	/** number of labels in delegation point */
63 	int namelabs;
64 
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;
74 
75 	/** if true, the NS RRset was bogus. All info is bad. */
76 	int bogus;
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 */
83 	uint8_t dp_type_mlc;
84 	/** use SSL for upstream query */
85 	uint8_t ssl_upstream;
86 	/** use TCP for upstream query */
87 	uint8_t tcp_upstream;
88 	/** delegpt from authoritative zone that is locally hosted */
89 	uint8_t auth_dp;
90 	/*** no cache */
91 	int no_cache;
92 };
93 
94 /**
95  * Nameservers for a delegation point.
96  */
97 struct delegpt_ns {
98 	/** next in list */
99 	struct delegpt_ns* next;
100 	/** name of nameserver */
101 	uint8_t* name;
102 	/** length of name */
103 	size_t namelen;
104 	/**
105 	 * If the name has been resolved. false if not queried for yet.
106 	 * true if the A, AAAA queries have been generated.
107 	 * marked true if those queries fail.
108 	 * and marked true if got4 and got6 are both true.
109 	 */
110 	int resolved;
111 	/** if the ipv4 address is in the delegpt, 0=not, 1=yes 2=negative,
112 	 * negative means it was done, but no content. */
113 	uint8_t got4;
114 	/** if the ipv6 address is in the delegpt, 0=not, 1=yes 2=negative */
115 	uint8_t got6;
116 	/**
117 	 * If the name is parent-side only and thus dispreferred.
118 	 * Its addresses become dispreferred as well
119 	 */
120 	uint8_t lame;
121 	/** if the parent-side ipv4 address has been looked up (last resort).
122 	 * Also enabled if a parent-side cache entry exists, or a parent-side
123 	 * negative-cache entry exists. */
124 	uint8_t done_pside4;
125 	/** if the parent-side ipv6 address has been looked up (last resort).
126 	 * Also enabled if a parent-side cache entry exists, or a parent-side
127 	 * negative-cache entry exists. */
128 	uint8_t done_pside6;
129 	/** the TLS authentication name, (if not NULL) to use. */
130 	char* tls_auth_name;
131 	/** the port to use; it should mostly be the default 53 but configured
132 	 *  upstreams can provide nondefault ports. */
133 	int port;
134 };
135 
136 /**
137  * Address of target nameserver in delegation point.
138  */
139 struct delegpt_addr {
140 	/** next delegation point in results */
141 	struct delegpt_addr* next_result;
142 	/** next delegation point in usable list */
143 	struct delegpt_addr* next_usable;
144 	/** next delegation point in all targets list */
145 	struct delegpt_addr* next_target;
146 
147 	/** delegation point address */
148 	struct sockaddr_storage addr;
149 	/** length of addr */
150 	socklen_t addrlen;
151 	/** number of attempts for this addr */
152 	int attempts;
153 	/** rtt stored here in the selection algorithm */
154 	int sel_rtt;
155 	/** if true, the A or AAAA RR was bogus, so this address is bad.
156 	 * Also check the dp->bogus to see if everything is bogus. */
157 	uint8_t bogus;
158 	/** if true, this address is dispreferred: it is a lame IP address */
159 	uint8_t lame;
160 	/** if the address is dnsseclame, but this cannot be cached, this
161 	 * option is useful to mark the address dnsseclame.
162 	 * This value is not copied in addr-copy and dp-copy. */
163 	uint8_t dnsseclame;
164 	/** the TLS authentication name, (if not NULL) to use. */
165 	char* tls_auth_name;
166 };
167 
168 /**
169  * Create new delegation point.
170  * @param regional: where to allocate it.
171  * @return new delegation point or NULL on error.
172  */
173 struct delegpt* delegpt_create(struct regional* regional);
174 
175 /**
176  * Create a copy of a delegation point.
177  * @param dp: delegation point to copy.
178  * @param regional: where to allocate it.
179  * @return new delegation point or NULL on error.
180  */
181 struct delegpt* delegpt_copy(struct delegpt* dp, struct regional* regional);
182 
183 /**
184  * Set name of delegation point.
185  * @param dp: delegation point.
186  * @param regional: where to allocate the name copy.
187  * @param name: name to use.
188  * @return false on error.
189  */
190 int delegpt_set_name(struct delegpt* dp, struct regional* regional,
191 	uint8_t* name);
192 
193 /**
194  * Add a name to the delegation point.
195  * @param dp: delegation point.
196  * @param regional: where to allocate the info.
197  * @param name: domain name in wire format.
198  * @param lame: name is lame, disprefer it.
199  * @param tls_auth_name: TLS authentication name (or NULL).
200  * @param port: port to use for resolved addresses.
201  * @return false on error.
202  */
203 int delegpt_add_ns(struct delegpt* dp, struct regional* regional,
204 	uint8_t* name, uint8_t lame, char* tls_auth_name, int port);
205 
206 /**
207  * Add NS rrset; calls add_ns repeatedly.
208  * @param dp: delegation point.
209  * @param regional: where to allocate the info.
210  * @param ns_rrset: NS rrset.
211  * @param lame: rrset is lame, disprefer it.
212  * @return 0 on alloc error.
213  */
214 int delegpt_rrset_add_ns(struct delegpt* dp, struct regional* regional,
215 	struct ub_packed_rrset_key* ns_rrset, uint8_t lame);
216 
217 /**
218  * Add target address to the delegation point.
219  * @param dp: delegation point.
220  * @param regional: where to allocate the info.
221  * @param name: name for which target was found (must be in nslist).
222  *	This name is marked resolved.
223  * @param namelen: length of name.
224  * @param addr: the address.
225  * @param addrlen: the length of addr.
226  * @param bogus: security status for the address, pass true if bogus.
227  * @param lame: address is lame.
228  * @param additions: will be set to 1 if a new address is added
229  * @return false on error.
230  */
231 int delegpt_add_target(struct delegpt* dp, struct regional* regional,
232 	uint8_t* name, size_t namelen, struct sockaddr_storage* addr,
233 	socklen_t addrlen, uint8_t bogus, uint8_t lame, int* additions);
234 
235 /**
236  * Add A RRset to delegpt.
237  * @param dp: delegation point.
238  * @param regional: where to allocate the info.
239  * @param rrset: RRset A to add.
240  * @param lame: rrset is lame, disprefer it.
241  * @param additions: will be set to 1 if a new address is added
242  * @return 0 on alloc error.
243  */
244 int delegpt_add_rrset_A(struct delegpt* dp, struct regional* regional,
245 	struct ub_packed_rrset_key* rrset, uint8_t lame, int* additions);
246 
247 /**
248  * Add AAAA RRset to delegpt.
249  * @param dp: delegation point.
250  * @param regional: where to allocate the info.
251  * @param rrset: RRset AAAA to add.
252  * @param lame: rrset is lame, disprefer it.
253  * @param additions: will be set to 1 if a new address is added
254  * @return 0 on alloc error.
255  */
256 int delegpt_add_rrset_AAAA(struct delegpt* dp, struct regional* regional,
257 	struct ub_packed_rrset_key* rrset, uint8_t lame, int* additions);
258 
259 /**
260  * Add any RRset to delegpt.
261  * Does not check for duplicates added.
262  * @param dp: delegation point.
263  * @param regional: where to allocate the info.
264  * @param rrset: RRset to add, NS, A, AAAA.
265  * @param lame: rrset is lame, disprefer it.
266  * @param additions: will be set to 1 if a new address is added
267  * @return 0 on alloc error.
268  */
269 int delegpt_add_rrset(struct delegpt* dp, struct regional* regional,
270 	struct ub_packed_rrset_key* rrset, uint8_t lame, int* additions);
271 
272 /**
273  * Add address to the delegation point. No servername is associated or checked.
274  * @param dp: delegation point.
275  * @param regional: where to allocate the info.
276  * @param addr: the address.
277  * @param addrlen: the length of addr.
278  * @param bogus: if address is bogus.
279  * @param lame: if address is lame.
280  * @param tls_auth_name: TLS authentication name (or NULL).
281  * @param port: the port to use; if -1 the port is taken from addr.
282  * @param additions: will be set to 1 if a new address is added
283  * @return false on error.
284  */
285 int delegpt_add_addr(struct delegpt* dp, struct regional* regional,
286 	struct sockaddr_storage* addr, socklen_t addrlen,
287 	uint8_t bogus, uint8_t lame, char* tls_auth_name, int port,
288 	int* additions);
289 
290 /**
291  * Find NS record in name list of delegation point.
292  * @param dp: delegation point.
293  * @param name: name of nameserver to look for, uncompressed wireformat.
294  * @param namelen: length of name.
295  * @return the ns structure or NULL if not found.
296  */
297 struct delegpt_ns* delegpt_find_ns(struct delegpt* dp, uint8_t* name,
298 	size_t namelen);
299 
300 /**
301  * Find address record in total list of delegation point.
302  * @param dp: delegation point.
303  * @param addr: address
304  * @param addrlen: length of addr
305  * @return the addr structure or NULL if not found.
306  */
307 struct delegpt_addr* delegpt_find_addr(struct delegpt* dp,
308 	struct sockaddr_storage* addr, socklen_t addrlen);
309 
310 /**
311  * Print the delegation point to the log. For debugging.
312  * @param v: verbosity value that is needed to emit to log.
313  * @param dp: delegation point.
314  */
315 void delegpt_log(enum verbosity_value v, struct delegpt* dp);
316 
317 /** count NS and number missing for logging */
318 void delegpt_count_ns(struct delegpt* dp, size_t* numns, size_t* missing);
319 
320 /** count addresses, and number in result and available lists, for logging */
321 void delegpt_count_addr(struct delegpt* dp, size_t* numaddr, size_t* numres,
322 	size_t* numavail);
323 
324 /**
325  * Add all usable targets to the result list.
326  * @param dp: delegation point.
327  */
328 void delegpt_add_unused_targets(struct delegpt* dp);
329 
330 /**
331  * Count number of missing targets. These are ns names with no resolved flag.
332  * @param dp: delegation point.
333  * @param alllame: if set, check if all the missing targets are lame.
334  * @return number of missing targets (or 0).
335  */
336 size_t delegpt_count_missing_targets(struct delegpt* dp, int* alllame);
337 
338 /** count total number of targets in dp */
339 size_t delegpt_count_targets(struct delegpt* dp);
340 
341 /**
342  * Create new delegation point from a dns message
343  *
344  * Note that this method does not actually test to see if the message is an
345  * actual referral. It really is just checking to see if it can construct a
346  * delegation point, so the message could be of some other type (some ANSWER
347  * messages, some CNAME messages, generally.) Note that the resulting
348  * DelegationPoint will contain targets for all "relevant" glue (i.e.,
349  * address records whose ownernames match the target of one of the NS
350  * records), so if policy dictates that some glue should be discarded beyond
351  * that, discard it before calling this method. Note that this method will
352  * find "glue" in either the ADDITIONAL section or the ANSWER section.
353  *
354  * @param msg: the dns message, referral.
355  * @param regional: where to allocate delegation point.
356  * @return new delegation point or NULL on alloc error, or if the
357  *         message was not appropriate.
358  */
359 struct delegpt* delegpt_from_message(struct dns_msg* msg,
360 	struct regional* regional);
361 
362 /**
363  * Mark negative return in delegation point for specific nameserver.
364  * sets the got4 or got6 to negative, updates the ns->resolved.
365  * @param ns: the nameserver in the delegpt.
366  * @param qtype: A or AAAA (host order).
367  */
368 void delegpt_mark_neg(struct delegpt_ns* ns, uint16_t qtype);
369 
370 /**
371  * Add negative message to delegation point.
372  * @param dp: delegation point.
373  * @param msg: the message added, marks off A or AAAA from an NS entry.
374  */
375 void delegpt_add_neg_msg(struct delegpt* dp, struct msgreply_entry* msg);
376 
377 /**
378  * Register the fact that there is no ipv6 and thus AAAAs are not going
379  * to be queried for or be useful.
380  * @param dp: the delegation point. Updated to reflect no ipv6.
381  */
382 void delegpt_no_ipv6(struct delegpt* dp);
383 
384 /**
385  * Register the fact that there is no ipv4 and thus As are not going
386  * to be queried for or be useful.
387  * @param dp: the delegation point. Updated to reflect no ipv4.
388  */
389 void delegpt_no_ipv4(struct delegpt* dp);
390 
391 /**
392  * create malloced delegation point, with the given name
393  * @param name: uncompressed wireformat of delegpt name.
394  * @return NULL on alloc failure
395  */
396 struct delegpt* delegpt_create_mlc(uint8_t* name);
397 
398 /**
399  * free malloced delegation point.
400  * @param dp: must have been created with delegpt_create_mlc, free'd.
401  */
402 void delegpt_free_mlc(struct delegpt* dp);
403 
404 /**
405  * Set name of delegation point.
406  * @param dp: delegation point. malloced.
407  * @param name: name to use.
408  * @return false on error.
409  */
410 int delegpt_set_name_mlc(struct delegpt* dp, uint8_t* name);
411 
412 /**
413  * add a name to malloced delegation point.
414  * @param dp: must have been created with delegpt_create_mlc.
415  * @param name: the name to add.
416  * @param lame: the name is lame, disprefer.
417  * @param tls_auth_name: TLS authentication name (or NULL).
418  * @param port: port to use for resolved addresses.
419  * @return false on error.
420  */
421 int delegpt_add_ns_mlc(struct delegpt* dp, uint8_t* name, uint8_t lame,
422 	char* tls_auth_name, int port);
423 
424 /**
425  * add an address to a malloced delegation point.
426  * @param dp: must have been created with delegpt_create_mlc.
427  * @param addr: the address.
428  * @param addrlen: the length of addr.
429  * @param bogus: if address is bogus.
430  * @param lame: if address is lame.
431  * @param tls_auth_name: TLS authentication name (or NULL).
432  * @param port: the port to use; if -1 the port is taken from addr.
433  * @return false on error.
434  */
435 int delegpt_add_addr_mlc(struct delegpt* dp, struct sockaddr_storage* addr,
436 	socklen_t addrlen, uint8_t bogus, uint8_t lame, char* tls_auth_name,
437 	int port);
438 
439 /**
440  * Add target address to the delegation point.
441  * @param dp: must have been created with delegpt_create_mlc.
442  * @param name: name for which target was found (must be in nslist).
443  *	This name is marked resolved.
444  * @param namelen: length of name.
445  * @param addr: the address.
446  * @param addrlen: the length of addr.
447  * @param bogus: security status for the address, pass true if bogus.
448  * @param lame: address is lame.
449  * @return false on error.
450  */
451 int delegpt_add_target_mlc(struct delegpt* dp, uint8_t* name, size_t namelen,
452 	struct sockaddr_storage* addr, socklen_t addrlen, uint8_t bogus,
453 	uint8_t lame);
454 
455 /** get memory in use by dp */
456 size_t delegpt_get_mem(struct delegpt* dp);
457 
458 #endif /* ITERATOR_ITER_DELEGPT_H */
459