1 /* 2 * iterator/iter_hints.h - iterative resolver module stub and root hints. 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 contains functions to assist the iterator module. 40 * Keep track of stub and root hints, and read those from config. 41 */ 42 43 #ifndef ITERATOR_ITER_HINTS_H 44 #define ITERATOR_ITER_HINTS_H 45 #include "util/storage/dnstree.h" 46 struct iter_env; 47 struct config_file; 48 struct delegpt; 49 50 /** 51 * Iterator hints structure 52 */ 53 struct iter_hints { 54 /** 55 * Hints are stored in this tree. Sort order is specially chosen. 56 * first sorted on qclass. Then on dname in nsec-like order, so that 57 * a lookup on class, name will return an exact match or the closest 58 * match which gives the ancestor needed. 59 * contents of type iter_hints_stub. The class IN root is in here. 60 * uses name_tree_node from dnstree.h. 61 */ 62 rbtree_type tree; 63 }; 64 65 /** 66 * Iterator hints for a particular stub. 67 */ 68 struct iter_hints_stub { 69 /** tree sorted by name, class */ 70 struct name_tree_node node; 71 /** delegation point with hint information for this stub. malloced. */ 72 struct delegpt* dp; 73 /** does the stub need to forego priming (like on other ports) */ 74 uint8_t noprime; 75 }; 76 77 /** 78 * Create hints 79 * @return new hints or NULL on error. 80 */ 81 struct iter_hints* hints_create(void); 82 83 /** 84 * Delete hints. 85 * @param hints: to delete. 86 */ 87 void hints_delete(struct iter_hints* hints); 88 89 /** 90 * Process hints config. Sets default values for root hints if no config. 91 * @param hints: where to store. 92 * @param cfg: config options. 93 * @return 0 on error. 94 */ 95 int hints_apply_cfg(struct iter_hints* hints, struct config_file* cfg); 96 97 /** 98 * Find root hints for the given class. 99 * @param hints: hint storage. 100 * @param qclass: class for which root hints are requested. host order. 101 * @return: NULL if no hints, or a ptr to stored hints. 102 */ 103 struct delegpt* hints_lookup_root(struct iter_hints* hints, uint16_t qclass); 104 105 /** 106 * Find next root hints (to cycle through all root hints). 107 * @param hints: hint storage 108 * @param qclass: class for which root hints are sought. 109 * 0 means give the first available root hints class. 110 * x means, give class x or a higher class if any. 111 * returns the found class in this variable. 112 * @return true if a root hint class is found. 113 * false if not root hint class is found (qclass may have been changed). 114 */ 115 int hints_next_root(struct iter_hints* hints, uint16_t* qclass); 116 117 /** 118 * Given a qname/qclass combination, and the delegation point from the cache 119 * for this qname/qclass, determine if this combination indicates that a 120 * stub hint exists and must be primed. 121 * 122 * @param hints: hint storage. 123 * @param qname: The qname that generated the delegation point. 124 * @param qclass: The qclass that generated the delegation point. 125 * @param dp: The cache generated delegation point. 126 * @return: A priming delegation point if there is a stub hint that must 127 * be primed, otherwise null. 128 */ 129 struct iter_hints_stub* hints_lookup_stub(struct iter_hints* hints, 130 uint8_t* qname, uint16_t qclass, struct delegpt* dp); 131 132 /** 133 * Get memory in use by hints 134 * @param hints: hint storage. 135 * @return bytes in use 136 */ 137 size_t hints_get_mem(struct iter_hints* hints); 138 139 /** 140 * Add stub to hints structure. For external use since it recalcs 141 * the tree parents. 142 * @param hints: the hints data structure 143 * @param c: class of zone 144 * @param dp: delegation point with name and target nameservers for new 145 * hints stub. malloced. 146 * @param noprime: set noprime option to true or false on new hint stub. 147 * @return false on failure (out of memory); 148 */ 149 int hints_add_stub(struct iter_hints* hints, uint16_t c, struct delegpt* dp, 150 int noprime); 151 152 /** 153 * Remove stub from hints structure. For external use since it 154 * recalcs the tree parents. 155 * @param hints: the hints data structure 156 * @param c: class of stub zone 157 * @param nm: name of stub zone (in uncompressed wireformat). 158 */ 159 void hints_delete_stub(struct iter_hints* hints, uint16_t c, uint8_t* nm); 160 161 #endif /* ITERATOR_ITER_HINTS_H */ 162