1 /* 2 * services/cache/rrset.h - Resource record set cache. 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 the rrset cache. 40 */ 41 42 #ifndef SERVICES_CACHE_RRSET_H 43 #define SERVICES_CACHE_RRSET_H 44 #include "util/storage/lruhash.h" 45 #include "util/storage/slabhash.h" 46 #include "util/data/packed_rrset.h" 47 struct config_file; 48 struct alloc_cache; 49 struct rrset_ref; 50 struct regional; 51 52 /** 53 * The rrset cache 54 * Thin wrapper around hashtable, like a typedef. 55 */ 56 struct rrset_cache { 57 /** uses partitioned hash table */ 58 struct slabhash table; 59 }; 60 61 /** 62 * Create rrset cache 63 * @param cfg: config settings or NULL for defaults. 64 * @param alloc: initial default rrset key allocation. 65 * @return: NULL on error. 66 */ 67 struct rrset_cache* rrset_cache_create(struct config_file* cfg, 68 struct alloc_cache* alloc); 69 70 /** 71 * Delete rrset cache 72 * @param r: rrset cache to delete. 73 */ 74 void rrset_cache_delete(struct rrset_cache* r); 75 76 /** 77 * Adjust settings of the cache to settings from the config file. 78 * May purge the cache. May recreate the cache. 79 * There may be no threading or use by other threads. 80 * @param r: rrset cache to adjust (like realloc). 81 * @param cfg: config settings or NULL for defaults. 82 * @param alloc: initial default rrset key allocation. 83 * @return 0 on error, or new rrset cache pointer on success. 84 */ 85 struct rrset_cache* rrset_cache_adjust(struct rrset_cache* r, 86 struct config_file* cfg, struct alloc_cache* alloc); 87 88 /** 89 * Touch rrset, with given pointer and id. 90 * Caller may not hold a lock on ANY rrset, this could give deadlock. 91 * 92 * This routine is faster than a hashtable lookup: 93 * o no bin_lock is acquired. 94 * o no walk through the bin-overflow-list. 95 * o no comparison of the entry key to find it. 96 * 97 * @param r: rrset cache. 98 * @param key: rrset key. Marked recently used (if it was not deleted 99 * before the lock is acquired, in that case nothing happens). 100 * @param hash: hash value of the item. Please read it from the key when 101 * you have it locked. Used to find slab from slabhash. 102 * @param id: used to check that the item is unchanged and not deleted. 103 */ 104 void rrset_cache_touch(struct rrset_cache* r, struct ub_packed_rrset_key* key, 105 hashvalue_type hash, rrset_id_type id); 106 107 /** 108 * Update an rrset in the rrset cache. Stores the information for later use. 109 * Will lookup if the rrset is in the cache and perform an update if necessary. 110 * If the item was present, and superior, references are returned to that. 111 * The passed item is then deallocated with rrset_parsedelete. 112 * 113 * A superior rrset is: 114 * o rrset with better trust value. 115 * o same trust value, different rdata, newly passed rrset is inserted. 116 * If rdata is the same, TTL in the cache is updated. 117 * 118 * @param r: the rrset cache. 119 * @param ref: reference (ptr and id) to the rrset. Pass reference setup for 120 * the new rrset. The reference may be changed if the cached rrset is 121 * superior. 122 * Before calling the rrset is presumed newly allocated and changeable. 123 * After calling you do not hold a lock, and the rrset is inserted in 124 * the hashtable so you need a lock to change it. 125 * @param alloc: how to allocate (and deallocate) the special rrset key. 126 * @param timenow: current time (to see if ttl in cache is expired). 127 * @return: true if the passed reference is updated, false if it is unchanged. 128 * 0: reference unchanged, inserted in cache. 129 * 1: reference updated, item is inserted in cache. 130 * 2: reference updated, item in cache is considered superior. 131 * also the rdata is equal (but other parameters in cache are superior). 132 */ 133 int rrset_cache_update(struct rrset_cache* r, struct rrset_ref* ref, 134 struct alloc_cache* alloc, time_t timenow); 135 136 /** 137 * Update or add an rrset in the rrset cache using a wildcard dname. 138 * Generates wildcard dname by prepending the wildcard label to the closest 139 * encloser. Will lookup if the rrset is in the cache and perform an update if 140 * necessary. 141 * 142 * @param rrset_cache: the rrset cache. 143 * @param rrset: which rrset to cache as wildcard. This rrset is left 144 * untouched. 145 * @param ce: the closest encloser, will be uses to generate the wildcard dname. 146 * @param ce_len: the closest encloser length. 147 * @param alloc: how to allocate (and deallocate) the special rrset key. 148 * @param timenow: current time (to see if ttl in cache is expired). 149 */ 150 void rrset_cache_update_wildcard(struct rrset_cache* rrset_cache, 151 struct ub_packed_rrset_key* rrset, uint8_t* ce, size_t ce_len, 152 struct alloc_cache* alloc, time_t timenow); 153 154 /** 155 * Lookup rrset. You obtain read/write lock. You must unlock before lookup 156 * anything of else. 157 * @param r: the rrset cache. 158 * @param qname: name of rrset to lookup. 159 * @param qnamelen: length of name of rrset to lookup. 160 * @param qtype: type of rrset to lookup (host order). 161 * @param qclass: class of rrset to lookup (host order). 162 * @param flags: rrset flags, or 0. 163 * @param timenow: used to compare with TTL. 164 * @param wr: set true to get writelock. 165 * @return packed rrset key pointer. Remember to unlock the key.entry.lock. 166 * or NULL if could not be found or it was timed out. 167 */ 168 struct ub_packed_rrset_key* rrset_cache_lookup(struct rrset_cache* r, 169 uint8_t* qname, size_t qnamelen, uint16_t qtype, uint16_t qclass, 170 uint32_t flags, time_t timenow, int wr); 171 172 /** 173 * Obtain readlock on a (sorted) list of rrset references. 174 * Checks TTLs and IDs of the rrsets and rollbacks locking if not Ok. 175 * @param ref: array of rrset references (key pointer and ID value). 176 * duplicate references are allowed and handled. 177 * @param count: size of array. 178 * @param timenow: used to compare with TTL. 179 * @return true on success, false on a failure, which can be that some 180 * RRsets have timed out, or that they do not exist any more, the 181 * RRsets have been purged from the cache. 182 * If true, you hold readlocks on all the ref items. 183 */ 184 int rrset_array_lock(struct rrset_ref* ref, size_t count, time_t timenow); 185 186 /** 187 * Unlock array (sorted) of rrset references. 188 * @param ref: array of rrset references (key pointer and ID value). 189 * duplicate references are allowed and handled. 190 * @param count: size of array. 191 */ 192 void rrset_array_unlock(struct rrset_ref* ref, size_t count); 193 194 /** 195 * Unlock array (sorted) of rrset references and at the same time 196 * touch LRU on the rrsets. It needs the scratch region for temporary 197 * storage as it uses the initial locks to obtain hash values. 198 * @param r: the rrset cache. In this cache LRU is updated. 199 * @param scratch: region for temporary storage of hash values. 200 * if memory allocation fails, the lru touch fails silently, 201 * but locks are released. memory errors are logged. 202 * @param ref: array of rrset references (key pointer and ID value). 203 * duplicate references are allowed and handled. 204 * @param count: size of array. 205 */ 206 void rrset_array_unlock_touch(struct rrset_cache* r, struct regional* scratch, 207 struct rrset_ref* ref, size_t count); 208 209 /** 210 * Update security status of an rrset. Looks up the rrset. 211 * If found, checks if rdata is equal. 212 * If so, it will update the security, trust and rrset-ttl values. 213 * The values are only updated if security is increased (towards secure). 214 * @param r: the rrset cache. 215 * @param rrset: which rrset to attempt to update. This rrset is left 216 * untouched. The rrset in the cache is updated in-place. 217 * @param now: current time. 218 */ 219 void rrset_update_sec_status(struct rrset_cache* r, 220 struct ub_packed_rrset_key* rrset, time_t now); 221 222 /** 223 * Looks up security status of an rrset. Looks up the rrset. 224 * If found, checks if rdata is equal, and entry did not expire. 225 * If so, it will update the security, trust and rrset-ttl values. 226 * @param r: the rrset cache. 227 * @param rrset: This rrset may change security status due to the cache. 228 * But its status will only improve, towards secure. 229 * @param now: current time. 230 */ 231 void rrset_check_sec_status(struct rrset_cache* r, 232 struct ub_packed_rrset_key* rrset, time_t now); 233 234 /** 235 * Remove an rrset from the cache, by name and type and flags 236 * @param r: rrset cache 237 * @param nm: name of rrset 238 * @param nmlen: length of name 239 * @param type: type of rrset 240 * @param dclass: class of rrset, host order 241 * @param flags: flags of rrset, host order 242 */ 243 void rrset_cache_remove(struct rrset_cache* r, uint8_t* nm, size_t nmlen, 244 uint16_t type, uint16_t dclass, uint32_t flags); 245 246 /** mark rrset to be deleted, set id=0 */ 247 void rrset_markdel(void* key); 248 249 #endif /* SERVICES_CACHE_RRSET_H */ 250