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 #include "util/locks.h" 47 struct iter_env; 48 struct config_file; 49 struct delegpt; 50 51 /** 52 * Iterator hints structure 53 */ 54 struct iter_hints { 55 /** lock on the forwards tree. 56 * When grabbing both this lock and the anchors.lock, this lock 57 * is grabbed first. */ 58 lock_rw_type lock; 59 /** 60 * Hints are stored in this tree. Sort order is specially chosen. 61 * first sorted on qclass. Then on dname in nsec-like order, so that 62 * a lookup on class, name will return an exact match or the closest 63 * match which gives the ancestor needed. 64 * contents of type iter_hints_stub. The class IN root is in here. 65 * uses name_tree_node from dnstree.h. 66 */ 67 rbtree_type tree; 68 }; 69 70 /** 71 * Iterator hints for a particular stub. 72 */ 73 struct iter_hints_stub { 74 /** tree sorted by name, class */ 75 struct name_tree_node node; 76 /** delegation point with hint information for this stub. malloced. */ 77 struct delegpt* dp; 78 /** does the stub need to forego priming (like on other ports) */ 79 uint8_t noprime; 80 }; 81 82 /** 83 * Create hints 84 * @return new hints or NULL on error. 85 */ 86 struct iter_hints* hints_create(void); 87 88 /** 89 * Delete hints. 90 * @param hints: to delete. 91 */ 92 void hints_delete(struct iter_hints* hints); 93 94 /** 95 * Process hints config. Sets default values for root hints if no config. 96 * @param hints: where to store. 97 * @param cfg: config options. 98 * @return 0 on error. 99 */ 100 int hints_apply_cfg(struct iter_hints* hints, struct config_file* cfg); 101 102 /** 103 * Find hints for the given class. 104 * The return value is contents of the hints structure. 105 * Caller should lock and unlock a readlock on the hints structure if nolock 106 * is set. 107 * Otherwise caller should unlock the readlock on the hints structure if a 108 * value was returned. 109 * @param hints: hint storage. 110 * @param qname: the qname that generated the delegation point. 111 * @param qclass: class for which root hints are requested. host order. 112 * @param nolock: Skip locking, locking is handled by the caller. 113 * @return: NULL if no hints, or a ptr to stored hints. 114 */ 115 struct delegpt* hints_find(struct iter_hints* hints, uint8_t* qname, 116 uint16_t qclass, int nolock); 117 118 /** 119 * Same as hints_lookup, but for the root only. 120 * @param hints: hint storage. 121 * @param qclass: class for which root hints are requested. host order. 122 * @param nolock: Skip locking, locking is handled by the caller. 123 * @return: NULL if no hints, or a ptr to stored hints. 124 */ 125 struct delegpt* hints_find_root(struct iter_hints* hints, 126 uint16_t qclass, int nolock); 127 128 /** 129 * Find next root hints (to cycle through all root hints). 130 * Handles its own locking unless nolock is set. In that case the caller 131 * should lock and unlock a readlock on the hints structure. 132 * @param hints: hint storage 133 * @param qclass: class for which root hints are sought. 134 * 0 means give the first available root hints class. 135 * x means, give class x or a higher class if any. 136 * returns the found class in this variable. 137 * @param nolock: Skip locking, locking is handled by the caller. 138 * @return true if a root hint class is found. 139 * false if not root hint class is found (qclass may have been changed). 140 */ 141 int hints_next_root(struct iter_hints* hints, uint16_t* qclass, int nolock); 142 143 /** 144 * Given a qname/qclass combination, and the delegation point from the cache 145 * for this qname/qclass, determine if this combination indicates that a 146 * stub hint exists and must be primed. 147 * The return value is contents of the hints structure. 148 * Caller should lock and unlock a readlock on the hints structure if nolock 149 * is set. 150 * Otherwise caller should unlock the readlock on the hints structure if a 151 * value was returned. 152 * 153 * @param hints: hint storage. 154 * @param qname: The qname that generated the delegation point. 155 * @param qclass: The qclass that generated the delegation point. 156 * @param dp: The cache generated delegation point. 157 * @param nolock: Skip locking, locking is handled by the caller. 158 * @return: A priming delegation point if there is a stub hint that must 159 * be primed, otherwise null. 160 */ 161 struct iter_hints_stub* hints_lookup_stub(struct iter_hints* hints, 162 uint8_t* qname, uint16_t qclass, struct delegpt* dp, int nolock); 163 164 /** 165 * Get memory in use by hints 166 * Locks and unlocks the structure. 167 * @param hints: hint storage. 168 * @return bytes in use 169 */ 170 size_t hints_get_mem(struct iter_hints* hints); 171 172 /** 173 * Add stub to hints structure. For external use since it recalcs 174 * the tree parents. 175 * Handles its own locking unless nolock is set. In that case the caller 176 * should lock and unlock a writelock on the hints structure. 177 * @param hints: the hints data structure 178 * @param c: class of zone 179 * @param dp: delegation point with name and target nameservers for new 180 * hints stub. malloced. 181 * @param noprime: set noprime option to true or false on new hint stub. 182 * @param nolock: Skip locking, locking is handled by the caller. 183 * @return false on failure (out of memory); 184 */ 185 int hints_add_stub(struct iter_hints* hints, uint16_t c, struct delegpt* dp, 186 int noprime, int nolock); 187 188 /** 189 * Remove stub from hints structure. For external use since it 190 * recalcs the tree parents. 191 * Handles its own locking unless nolock is set. In that case the caller 192 * should lock and unlock a writelock on the hints structure. 193 * @param hints: the hints data structure 194 * @param c: class of stub zone 195 * @param nm: name of stub zone (in uncompressed wireformat). 196 * @param nolock: Skip locking, locking is handled by the caller. 197 */ 198 void hints_delete_stub(struct iter_hints* hints, uint16_t c, 199 uint8_t* nm, int nolock); 200 201 #endif /* ITERATOR_ITER_HINTS_H */ 202