contrib/unbound/util/data/packed_rrset.h

   1 /*
   2  * util/data/packed_rrset.h - data storage for a set of resource records.
   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 LIMITED
  25  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  26  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
  27  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  28  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  29  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  30  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  31  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  32  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  33  * POSSIBILITY OF SUCH DAMAGE.
  34  */
  35
  36 /**
  37  * \file
  38  *
  39  * This file contains the data storage for RRsets.
  40  */
  41
  42 #ifndef UTIL_DATA_PACKED_RRSET_H
  43 #define UTIL_DATA_PACKED_RRSET_H
  44 #include "util/storage/lruhash.h"
  45 #include <ldns/rr.h>
  46 struct alloc_cache;
  47 struct regional;
  48
  49 /** type used to uniquely identify rrsets. Cannot be reused without
  50  * clearing the cache. */
  51 typedef uint64_t rrset_id_t;
  52
  53 /** this rrset is NSEC and is at zone apex (at child side of zonecut) */
  54 #define PACKED_RRSET_NSEC_AT_APEX 0x1
  55 /** this rrset is A/AAAA and is in-zone-glue (from parent side of zonecut) */
  56 #define PACKED_RRSET_PARENT_SIDE 0x2
  57 /** this rrset is SOA and has the negative ttl (from nxdomain or nodata),
  58  * this is set on SOA rrsets in the authority section, to keep its TTL separate
  59  * from the SOA in the answer section from a direct SOA query or ANY query. */
  60 #define PACKED_RRSET_SOA_NEG 0x4
  61
  62 /**
  63  * The identifying information for an RRset.
  64  */
  65 struct packed_rrset_key {
  66         /**
  67          * The domain name. If not null (for id=0) it is allocated, and
  68          * contains the wireformat domain name.
  69          * This dname is not canonicalized.
  70          */
  71         uint8_t* dname;
  72         /**
  73          * Length of the domain name, including last 0 root octet.
  74          */
  75         size_t dname_len;
  76         /**
  77          * Flags. 32bit to be easy for hashing:
  78          *      o PACKED_RRSET_NSEC_AT_APEX
  79          *      o PACKED_RRSET_PARENT_SIDE
  80          *      o PACKED_RRSET_SOA_NEG
  81          */
  82         uint32_t flags;
  83         /** the rrset type in network format */
  84         uint16_t type;
  85         /** the rrset class in network format */
  86         uint16_t rrset_class;
  87 };
  88
  89 /**
  90  * This structure contains an RRset. A set of resource records that
  91  * share the same domain name, type and class.
  92  *
  93  * Due to memory management and threading, the key structure cannot be
  94  * deleted, although the data can be. The id can be set to 0 to store and the
  95  * structure can be recycled with a new id.
  96  */
  97 struct ub_packed_rrset_key {
  98         /**
  99          * entry into hashtable. Note the lock is never destroyed,
 100          *  even when this key is retired to the cache.
 101          * the data pointer (if not null) points to a struct packed_rrset.
 102          */
 103         struct lruhash_entry entry;
 104         /**
 105          * the ID of this rrset. unique, based on threadid + sequenceno.
 106          * ids are not reused, except after flushing the cache.
 107          * zero is an unused entry, and never a valid id.
 108          * Check this value after getting entry.lock.
 109          * The other values in this struct may only be altered after changing
 110          * the id (which needs a writelock on entry.lock).
 111          */
 112         rrset_id_t id;
 113         /** key data: dname, type and class */
 114         struct packed_rrset_key rk;
 115 };
 116
 117 /**
 118  * RRset trustworthiness. Bigger value is more trust. RFC 2181.
 119  * The rrset_trust_add_noAA, rrset_trust_auth_noAA, rrset_trust_add_AA,
 120  * are mentioned as the same trustworthiness in 2181, but split up here
 121  * for ease of processing.
 122  *
 123  * rrset_trust_nonauth_ans_AA, rrset_trust_ans_noAA
 124  * are also mentioned as the same trustworthiness in 2181, but split up here
 125  * for ease of processing.
 126  *
 127  * Added trust_none for a sane initial value, smaller than anything else.
 128  * Added validated and ultimate trust for keys and rrsig validated content.
 129  */
 130 enum rrset_trust {
 131         /** initial value for trust */
 132         rrset_trust_none = 0,
 133         /** Additional information from non-authoritative answers */
 134         rrset_trust_add_noAA,
 135         /** Data from the authority section of a non-authoritative answer */
 136         rrset_trust_auth_noAA,
 137         /** Additional information from an authoritative answer */
 138         rrset_trust_add_AA,
 139         /** non-authoritative data from the answer section of authoritative
 140          * answers */
 141         rrset_trust_nonauth_ans_AA,
 142         /** Data from the answer section of a non-authoritative answer */
 143         rrset_trust_ans_noAA,
 144         /** Glue from a primary zone, or glue from a zone transfer */
 145         rrset_trust_glue,
 146         /** Data from the authority section of an authoritative answer */
 147         rrset_trust_auth_AA,
 148         /** The authoritative data included in the answer section of an
 149          *  authoritative reply */
 150         rrset_trust_ans_AA,
 151         /** Data from a zone transfer, other than glue */
 152         rrset_trust_sec_noglue,
 153         /** Data from a primary zone file, other than glue data */
 154         rrset_trust_prim_noglue,
 155         /** DNSSEC(rfc4034) validated with trusted keys */
 156         rrset_trust_validated,
 157         /** ultimately trusted, no more trust is possible;
 158          * trusted keys from the unbound configuration setup. */
 159         rrset_trust_ultimate
 160 };
 161
 162 /**
 163  * Security status from validation for data.
 164  * The order is significant; more secure, more proven later.
 165  */
 166 enum sec_status {
 167         /** UNCHECKED means that object has yet to be validated. */
 168         sec_status_unchecked = 0,
 169         /** BOGUS means that the object (RRset or message) failed to validate
 170          *  (according to local policy), but should have validated. */
 171         sec_status_bogus,
 172         /** INDETERMINATE means that the object is insecure, but not
 173          * authoritatively so. Generally this means that the RRset is not
 174          * below a configured trust anchor. */
 175         sec_status_indeterminate,
 176         /** INSECURE means that the object is authoritatively known to be
 177          * insecure. Generally this means that this RRset is below a trust
 178          * anchor, but also below a verified, insecure delegation. */
 179         sec_status_insecure,
 180         /** SECURE means that the object (RRset or message) validated
 181          * according to local policy. */
 182         sec_status_secure
 183 };
 184
 185 /**
 186  * RRset data.
 187  *
 188  * The data is packed, stored contiguously in memory.
 189  * memory layout:
 190  *      o base struct
 191  *      o rr_len size_t array
 192  *      o rr_data uint8_t* array
 193  *      o rr_ttl uint32_t array (after size_t and ptrs because those may be
 194  *              64bit and this array before those would make them unaligned).
 195  *              Since the stuff before is 32/64bit, rr_ttl is 32 bit aligned.
 196  *      o rr_data rdata wireformats
 197  *      o rrsig_data rdata wireformat(s)
 198  *
 199  * Rdata is stored in wireformat. The dname is stored in wireformat.
 200  * TTLs are stored as absolute values (and could be expired).
 201  *
 202  * RRSIGs are stored in the arrays after the regular rrs.
 203  *
 204  * You need the packed_rrset_key to know dname, type, class of the
 205  * resource records in this RRset. (if signed the rrsig gives the type too).
 206  *
 207  * On the wire an RR is:
 208  *      name, type, class, ttl, rdlength, rdata.
 209  * So we need to send the following per RR:
 210  *      key.dname, ttl, rr_data[i].
 211  *      since key.dname ends with type and class.
 212  *      and rr_data starts with the rdlength.
 213  *      the ttl value to send changes due to time.
 214  */
 215 struct packed_rrset_data {
 216         /** TTL (in seconds like time()) of the rrset.
 217          * Same for all RRs see rfc2181(5.2).  */
 218         uint32_t ttl;
 219         /** number of rrs. */
 220         size_t count;
 221         /** number of rrsigs, if 0 no rrsigs */
 222         size_t rrsig_count;
 223         /** the trustworthiness of the rrset data */
 224         enum rrset_trust trust;
 225         /** security status of the rrset data */
 226         enum sec_status security;
 227         /** length of every rr's rdata, rr_len[i] is size of rr_data[i]. */
 228         size_t* rr_len;
 229         /** ttl of every rr. rr_ttl[i] ttl of rr i. */
 230         uint32_t *rr_ttl;
 231         /**
 232          * Array of pointers to every rr's rdata.
 233          * The rr_data[i] rdata is stored in uncompressed wireformat.
 234          * The first uint16_t of rr_data[i] is network format rdlength.
 235          *
 236          * rr_data[count] to rr_data[count+rrsig_count] contain the rrsig data.
 237          */
 238         uint8_t** rr_data;
 239 };
 240
 241 /**
 242  * An RRset can be represented using both key and data together.
 243  * Split into key and data structures to simplify implementation of
 244  * caching schemes.
 245  */
 246 struct packed_rrset {
 247         /** domain name, type and class */
 248         struct packed_rrset_key* k;
 249         /** ttl, count and rdatas (and rrsig) */
 250         struct packed_rrset_data* d;
 251 };
 252
 253 /**
 254  * list of packed rrsets
 255  */
 256 struct packed_rrset_list {
 257         /** next in list */
 258         struct packed_rrset_list* next;
 259         /** rrset key and data */
 260         struct packed_rrset rrset;
 261 };
 262
 263 /**
 264  * Delete packed rrset key and data, not entered in hashtables yet.
 265  * Used during parsing.
 266  * @param pkey: rrset key structure with locks, key and data pointers.
 267  * @param alloc: where to return the unfree-able key structure.
 268  */
 269 void ub_packed_rrset_parsedelete(struct ub_packed_rrset_key* pkey,
 270         struct alloc_cache* alloc);
 271
 272 /**
 273  * Memory size of rrset data. RRset data must be filled in correctly.
 274  * @param data: data to examine.
 275  * @return size in bytes.
 276  */
 277 size_t packed_rrset_sizeof(struct packed_rrset_data* data);
 278
 279 /**
 280  * Get TTL of rrset. RRset data must be filled in correctly.
 281  * @param key: rrset key, with data to examine.
 282  * @return ttl value.
 283  */
 284 uint32_t ub_packed_rrset_ttl(struct ub_packed_rrset_key* key);
 285
 286 /**
 287  * Calculate memory size of rrset entry. For hash table usage.
 288  * @param key: struct ub_packed_rrset_key*.
 289  * @param data: struct packed_rrset_data*.
 290  * @return size in bytes.
 291  */
 292 size_t ub_rrset_sizefunc(void* key, void* data);
 293
 294 /**
 295  * compares two rrset keys.
 296  * @param k1: struct ub_packed_rrset_key*.
 297  * @param k2: struct ub_packed_rrset_key*.
 298  * @return 0 if equal.
 299  */
 300 int ub_rrset_compare(void* k1, void* k2);
 301
 302 /**
 303  * compare two rrset data structures.
 304  * Compared rdata and rrsigdata, not the trust or ttl value.
 305  * @param d1: data to compare.
 306  * @param d2: data to compare.
 307  * @return 1 if equal.
 308  */
 309 int rrsetdata_equal(struct packed_rrset_data* d1, struct packed_rrset_data* d2);
 310
 311 /**
 312  * Old key to be deleted. RRset keys are recycled via alloc.
 313  * The id is set to 0. So that other threads, after acquiring a lock always
 314  * get the correct value, in this case the 0 deleted-special value.
 315  * @param key: struct ub_packed_rrset_key*.
 316  * @param userdata: alloc structure to use for recycling.
 317  */
 318 void ub_rrset_key_delete(void* key, void* userdata);
 319
 320 /**
 321  * Old data to be deleted.
 322  * @param data: what to delete.
 323  * @param userdata: user data ptr.
 324  */
 325 void rrset_data_delete(void* data, void* userdata);
 326
 327 /**
 328  * Calculate hash value for a packed rrset key.
 329  * @param key: the rrset key with name, type, class, flags.
 330  * @return hash value.
 331  */
 332 hashvalue_t rrset_key_hash(struct packed_rrset_key* key);
 333
 334 /**
 335  * Fixup pointers in fixed data packed_rrset_data blob.
 336  * After a memcpy of the data for example. Will set internal pointers right.
 337  * @param data: rrset data structure. Otherwise correctly filled in.
 338  */
 339 void packed_rrset_ptr_fixup(struct packed_rrset_data* data);
 340
 341 /**
 342  * Fixup TTLs in fixed data packed_rrset_data blob.
 343  * @param data: rrset data structure. Otherwise correctly filled in.
 344  * @param add: how many seconds to add, pass time(0) for example.
 345  */
 346 void packed_rrset_ttl_add(struct packed_rrset_data* data, uint32_t add);
 347
 348 /**
 349  * Utility procedure to extract CNAME target name from its rdata.
 350  * Failsafes; it will change passed dname to a valid dname or do nothing.
 351  * @param rrset: the rrset structure. Must be a CNAME.
 352  *      Only first RR is used (multiple RRs are technically illegal anyway).
 353  *      Also works on type DNAME. Returns target name.
 354  * @param dname: this pointer is updated to point into the cname rdata.
 355  *      If a failsafe fails, nothing happens to the pointer (such as the
 356  *      rdata was not a valid dname, not a CNAME, ...).
 357  * @param dname_len: length of dname is returned.
 358  */
 359 void get_cname_target(struct ub_packed_rrset_key* rrset, uint8_t** dname,
 360         size_t* dname_len);
 361
 362 /**
 363  * Get a printable string for a rrset trust value
 364  * @param s: rrset trust value
 365  * @return printable string.
 366  */
 367 const char* rrset_trust_to_string(enum rrset_trust s);
 368
 369 /**
 370  * Get a printable string for a security status value
 371  * @param s: security status
 372  * @return printable string.
 373  */
 374 const char* sec_status_to_string(enum sec_status s);
 375
 376 /**
 377  * Print string with neat domain name, type, class from rrset.
 378  * @param v: at what verbosity level to print this.
 379  * @param str: string of message.
 380  * @param rrset: structure with name, type and class.
 381  */
 382 void log_rrset_key(enum verbosity_value v, const char* str,
 383         struct ub_packed_rrset_key* rrset);
 384
 385 /**
 386  * Allocate rrset in region - no more locks needed
 387  * @param key: a (just from rrset cache looked up) rrset key + valid,
 388  *      packed data record.
 389  * @param region: where to alloc the copy
 390  * @param now: adjust the TTLs to be relative (subtract from all TTLs).
 391  * @return new region-alloced rrset key or NULL on alloc failure.
 392  */
 393 struct ub_packed_rrset_key* packed_rrset_copy_region(
 394         struct ub_packed_rrset_key* key, struct regional* region,
 395         uint32_t now);
 396
 397 /**
 398  * Allocate rrset with malloc (from region or you are holding the lock).
 399  * @param key: key with data entry.
 400  * @param alloc: alloc_cache to create rrset_keys
 401  * @param now: adjust the TTLs to be absolute (add to all TTLs).
 402  * @return new region-alloced rrset key or NULL on alloc failure.
 403  */
 404 struct ub_packed_rrset_key* packed_rrset_copy_alloc(
 405         struct ub_packed_rrset_key* key, struct alloc_cache* alloc,
 406         uint32_t now);
 407
 408 /**
 409  * Create a ub_packed_rrset_key allocated on the heap.
 410  * It therefore does not have the correct ID value, and cannot be used
 411  * inside the cache.  It can be used in storage outside of the cache.
 412  * Keys for the cache have to be obtained from alloc.h .
 413  * @param rrset: the ldns rr set.
 414  * @return key allocated or NULL on failure.
 415  */
 416 struct ub_packed_rrset_key* ub_packed_rrset_heap_key(ldns_rr_list* rrset);
 417
 418 /**
 419  * Create packed_rrset data on the heap.
 420  * @param rrset: the ldns rr set with the data to copy.
 421  * @return data allocated or NULL on failure.
 422  */
 423 struct packed_rrset_data* packed_rrset_heap_data(ldns_rr_list* rrset);
 424
 425 /**
 426  * Convert packed rrset to ldns rr list.
 427  * @param rrset: packed rrset.
 428  * @param buf: scratch buffer.
 429  * @return rr list or NULL on failure.
 430  */
 431 ldns_rr_list* packed_rrset_to_rr_list(struct ub_packed_rrset_key* rrset,
 432         ldns_buffer* buf);
 433
 434 #endif /* UTIL_DATA_PACKED_RRSET_H */