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
  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 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 struct alloc_cache;
  46 struct regional;
  47
  48 /** type used to uniquely identify rrsets. Cannot be reused without
  49  * clearing the cache. */
  50 typedef uint64_t rrset_id_type;
  51
  52 /** this rrset is NSEC and is at zone apex (at child side of zonecut) */
  53 #define PACKED_RRSET_NSEC_AT_APEX 0x1
  54 /** this rrset is A/AAAA and is in-zone-glue (from parent side of zonecut) */
  55 #define PACKED_RRSET_PARENT_SIDE 0x2
  56 /** this rrset is SOA and has the negative ttl (from nxdomain or nodata),
  57  * this is set on SOA rrsets in the authority section, to keep its TTL separate
  58  * from the SOA in the answer section from a direct SOA query or ANY query. */
  59 #define PACKED_RRSET_SOA_NEG 0x4
  60 /** This rrset is considered to have a fixed TTL; its TTL doesn't have to be
  61  * updated on encoding in a reply.  This flag is not expected to be set in
  62  * cached data. */
  63 #define PACKED_RRSET_FIXEDTTL 0x80000000
  64 /** This rrset is from RPZ. It is not real, it is synthesized data to block
  65  * access. The flag makes lookups, from cache in iterator, ignore the fake
  66  * items and only use actual data.  Eg. when the iterator looksup NS, CNAME,
  67  * A and AAAA types, it then gets items without this flag that are the
  68  * actual network. But messages with these records in it can be stored in
  69  * the cache and retrieved for a reply. */
  70 #define PACKED_RRSET_RPZ 0x8
  71
  72 /** number of rrs and rrsets for integer overflow protection.  More than
  73  * this is not really possible (64K packet has much less RRs and RRsets) in
  74  * a message.  And this is small enough that also multiplied there is no
  75  * integer overflow. */
  76 #define RR_COUNT_MAX 0xffffff
  77
  78 /**
  79  * The identifying information for an RRset.
  80  */
  81 struct packed_rrset_key {
  82         /**
  83          * The domain name. If not null (for id=0) it is allocated, and
  84          * contains the wireformat domain name.
  85          * This dname is not canonicalized.
  86          */
  87         uint8_t* dname;
  88         /**
  89          * Length of the domain name, including last 0 root octet.
  90          */
  91         size_t dname_len;
  92         /**
  93          * Flags. 32bit to be easy for hashing:
  94          *      o PACKED_RRSET_NSEC_AT_APEX
  95          *      o PACKED_RRSET_PARENT_SIDE
  96          *      o PACKED_RRSET_SOA_NEG
  97          *      o PACKED_RRSET_FIXEDTTL (not supposed to be cached)
  98          *      o PACKED_RRSET_RPZ
  99          */
 100         uint32_t flags;
 101         /** the rrset type in network format */
 102         uint16_t type;
 103         /** the rrset class in network format */
 104         uint16_t rrset_class;
 105 };
 106
 107 /**
 108  * This structure contains an RRset. A set of resource records that
 109  * share the same domain name, type and class.
 110  *
 111  * Due to memory management and threading, the key structure cannot be
 112  * deleted, although the data can be. The id can be set to 0 to store and the
 113  * structure can be recycled with a new id.
 114  */
 115 struct ub_packed_rrset_key {
 116         /**
 117          * entry into hashtable. Note the lock is never destroyed,
 118          *  even when this key is retired to the cache.
 119          * the data pointer (if not null) points to a struct packed_rrset.
 120          */
 121         struct lruhash_entry entry;
 122         /**
 123          * the ID of this rrset. unique, based on threadid + sequenceno.
 124          * ids are not reused, except after flushing the cache.
 125          * zero is an unused entry, and never a valid id.
 126          * Check this value after getting entry.lock.
 127          * The other values in this struct may only be altered after changing
 128          * the id (which needs a writelock on entry.lock).
 129          */
 130         rrset_id_type id;
 131         /** key data: dname, type and class */
 132         struct packed_rrset_key rk;
 133 };
 134
 135 /**
 136  * RRset trustworthiness. Bigger value is more trust. RFC 2181.
 137  * The rrset_trust_add_noAA, rrset_trust_auth_noAA, rrset_trust_add_AA,
 138  * are mentioned as the same trustworthiness in 2181, but split up here
 139  * for ease of processing.
 140  *
 141  * rrset_trust_nonauth_ans_AA, rrset_trust_ans_noAA
 142  * are also mentioned as the same trustworthiness in 2181, but split up here
 143  * for ease of processing.
 144  *
 145  * Added trust_none for a sane initial value, smaller than anything else.
 146  * Added validated and ultimate trust for keys and rrsig validated content.
 147  */
 148 enum rrset_trust {
 149         /** initial value for trust */
 150         rrset_trust_none = 0,
 151         /** Additional information from non-authoritative answers */
 152         rrset_trust_add_noAA,
 153         /** Data from the authority section of a non-authoritative answer */
 154         rrset_trust_auth_noAA,
 155         /** Additional information from an authoritative answer */
 156         rrset_trust_add_AA,
 157         /** non-authoritative data from the answer section of authoritative
 158          * answers */
 159         rrset_trust_nonauth_ans_AA,
 160         /** Data from the answer section of a non-authoritative answer */
 161         rrset_trust_ans_noAA,
 162         /** Glue from a primary zone, or glue from a zone transfer */
 163         rrset_trust_glue,
 164         /** Data from the authority section of an authoritative answer */
 165         rrset_trust_auth_AA,
 166         /** The authoritative data included in the answer section of an
 167          *  authoritative reply */
 168         rrset_trust_ans_AA,
 169         /** Data from a zone transfer, other than glue */
 170         rrset_trust_sec_noglue,
 171         /** Data from a primary zone file, other than glue data */
 172         rrset_trust_prim_noglue,
 173         /** DNSSEC(rfc4034) validated with trusted keys */
 174         rrset_trust_validated,
 175         /** ultimately trusted, no more trust is possible;
 176          * trusted keys from the unbound configuration setup. */
 177         rrset_trust_ultimate
 178 };
 179
 180 /**
 181  * Security status from validation for data.
 182  * The order is significant; more secure, more proven later.
 183  */
 184 enum sec_status {
 185         /** UNCHECKED means that object has yet to be validated. */
 186         sec_status_unchecked = 0,
 187         /** BOGUS means that the object (RRset or message) failed to validate
 188          *  (according to local policy), but should have validated. */
 189         sec_status_bogus,
 190         /** INDETERMINATE means that the object is insecure, but not
 191          * authoritatively so. Generally this means that the RRset is not
 192          * below a configured trust anchor. */
 193         sec_status_indeterminate,
 194         /** INSECURE means that the object is authoritatively known to be
 195          * insecure. Generally this means that this RRset is below a trust
 196          * anchor, but also below a verified, insecure delegation. */
 197         sec_status_insecure,
 198         /** SECURE_SENTINEL_FAIL means that the object (RRset or message)
 199          * validated according to local policy but did not succeed in the root
 200          * KSK sentinel test (draft-ietf-dnsop-kskroll-sentinel). */
 201         sec_status_secure_sentinel_fail,
 202         /** SECURE means that the object (RRset or message) validated
 203          * according to local policy. */
 204         sec_status_secure
 205 };
 206
 207 /**
 208  * RRset data.
 209  *
 210  * The data is packed, stored contiguously in memory.
 211  *
 212  * It is not always stored contiguously, in that case, an unpacked-packed
 213  * rrset has the arrays separate.  A bunch of routines work on that, but
 214  * the packed rrset that is contiguous is for the rrset-cache and the
 215  * cache-response routines in daemon/worker.c.
 216  *
 217  * memory layout:
 218  *      o base struct
 219  *      o rr_len size_t array
 220  *      o rr_data uint8_t* array
 221  *      o rr_ttl time_t array (after size_t and ptrs because those may be
 222  *              64bit and this array before those would make them unaligned).
 223  *              Since the stuff before is 32/64bit, rr_ttl is 32 bit aligned.
 224  *      o rr_data rdata wireformats
 225  *      o rrsig_data rdata wireformat(s)
 226  *
 227  * Rdata is stored in wireformat. The dname is stored in wireformat.
 228  * TTLs are stored as absolute values (and could be expired).
 229  *
 230  * RRSIGs are stored in the arrays after the regular rrs.
 231  *
 232  * You need the packed_rrset_key to know dname, type, class of the
 233  * resource records in this RRset. (if signed the rrsig gives the type too).
 234  *
 235  * On the wire an RR is:
 236  *      name, type, class, ttl, rdlength, rdata.
 237  * So we need to send the following per RR:
 238  *      key.dname, ttl, rr_data[i].
 239  *      since key.dname ends with type and class.
 240  *      and rr_data starts with the rdlength.
 241  *      the ttl value to send changes due to time.
 242  */
 243 struct packed_rrset_data {
 244         /** Timestamp added to TTLs in the packed data.
 245          * Needed to support serving original TTLs. */
 246         time_t ttl_add;
 247         /** TTL (in seconds like time()) of the rrset.
 248          * Same for all RRs see rfc2181(5.2).  */
 249         time_t ttl;
 250         /** number of rrs. */
 251         size_t count;
 252         /** number of rrsigs, if 0 no rrsigs */
 253         size_t rrsig_count;
 254         /** the trustworthiness of the rrset data */
 255         enum rrset_trust trust;
 256         /** security status of the rrset data */
 257         enum sec_status security;
 258         /** length of every rr's rdata, rr_len[i] is size of rr_data[i]. */
 259         size_t* rr_len;
 260         /** ttl of every rr. rr_ttl[i] ttl of rr i. */
 261         time_t *rr_ttl;
 262         /**
 263          * Array of pointers to every rr's rdata.
 264          * The rr_data[i] rdata is stored in uncompressed wireformat.
 265          * The first uint16_t of rr_data[i] is network format rdlength.
 266          *
 267          * rr_data[count] to rr_data[count+rrsig_count] contain the rrsig data.
 268          */
 269         uint8_t** rr_data;
 270 };
 271
 272 /**
 273  * An RRset can be represented using both key and data together.
 274  * Split into key and data structures to simplify implementation of
 275  * caching schemes.
 276  */
 277 struct packed_rrset {
 278         /** domain name, type and class */
 279         struct packed_rrset_key* k;
 280         /** ttl, count and rdatas (and rrsig) */
 281         struct packed_rrset_data* d;
 282 };
 283
 284 /**
 285  * list of packed rrsets
 286  */
 287 struct packed_rrset_list {
 288         /** next in list */
 289         struct packed_rrset_list* next;
 290         /** rrset key and data */
 291         struct packed_rrset rrset;
 292 };
 293
 294 /**
 295  * Delete packed rrset key and data, not entered in hashtables yet.
 296  * Used during parsing.
 297  * @param pkey: rrset key structure with locks, key and data pointers.
 298  * @param alloc: where to return the unfree-able key structure.
 299  */
 300 void ub_packed_rrset_parsedelete(struct ub_packed_rrset_key* pkey,
 301         struct alloc_cache* alloc);
 302
 303 /**
 304  * Memory size of rrset data. RRset data must be filled in correctly.
 305  * @param data: data to examine.
 306  * @return size in bytes.
 307  */
 308 size_t packed_rrset_sizeof(struct packed_rrset_data* data);
 309
 310 /**
 311  * Get TTL of rrset. RRset data must be filled in correctly.
 312  * @param key: rrset key, with data to examine.
 313  * @return ttl value.
 314  */
 315 time_t ub_packed_rrset_ttl(struct ub_packed_rrset_key* key);
 316
 317 /**
 318  * Calculate memory size of rrset entry. For hash table usage.
 319  * @param key: struct ub_packed_rrset_key*.
 320  * @param data: struct packed_rrset_data*.
 321  * @return size in bytes.
 322  */
 323 size_t ub_rrset_sizefunc(void* key, void* data);
 324
 325 /**
 326  * compares two rrset keys.
 327  * @param k1: struct ub_packed_rrset_key*.
 328  * @param k2: struct ub_packed_rrset_key*.
 329  * @return 0 if equal.
 330  */
 331 int ub_rrset_compare(void* k1, void* k2);
 332
 333 /**
 334  * compare two rrset data structures.
 335  * Compared rdata and rrsigdata, not the trust or ttl value.
 336  * @param d1: data to compare.
 337  * @param d2: data to compare.
 338  * @return 1 if equal.
 339  */
 340 int rrsetdata_equal(struct packed_rrset_data* d1, struct packed_rrset_data* d2);
 341
 342 /**
 343  * Old key to be deleted. RRset keys are recycled via alloc.
 344  * The id is set to 0. So that other threads, after acquiring a lock always
 345  * get the correct value, in this case the 0 deleted-special value.
 346  * @param key: struct ub_packed_rrset_key*.
 347  * @param userdata: alloc structure to use for recycling.
 348  */
 349 void ub_rrset_key_delete(void* key, void* userdata);
 350
 351 /**
 352  * Old data to be deleted.
 353  * @param data: what to delete.
 354  * @param userdata: user data ptr.
 355  */
 356 void rrset_data_delete(void* data, void* userdata);
 357
 358 /**
 359  * Calculate hash value for a packed rrset key.
 360  * @param key: the rrset key with name, type, class, flags.
 361  * @return hash value.
 362  */
 363 hashvalue_type rrset_key_hash(struct packed_rrset_key* key);
 364
 365 /**
 366  * Fixup pointers in fixed data packed_rrset_data blob.
 367  * After a memcpy of the data for example. Will set internal pointers right.
 368  * @param data: rrset data structure. Otherwise correctly filled in.
 369  */
 370 void packed_rrset_ptr_fixup(struct packed_rrset_data* data);
 371
 372 /**
 373  * Fixup TTLs in fixed data packed_rrset_data blob.
 374  * @param data: rrset data structure. Otherwise correctly filled in.
 375  * @param add: how many seconds to add, pass time(0) for example.
 376  */
 377 void packed_rrset_ttl_add(struct packed_rrset_data* data, time_t add);
 378
 379 /**
 380  * Utility procedure to extract CNAME target name from its rdata.
 381  * Failsafes; it will change passed dname to a valid dname or do nothing.
 382  * @param rrset: the rrset structure. Must be a CNAME.
 383  *      Only first RR is used (multiple RRs are technically illegal anyway).
 384  *      Also works on type DNAME. Returns target name.
 385  * @param dname: this pointer is updated to point into the cname rdata.
 386  *      If a failsafe fails, nothing happens to the pointer (such as the
 387  *      rdata was not a valid dname, not a CNAME, ...).
 388  * @param dname_len: length of dname is returned.
 389  */
 390 void get_cname_target(struct ub_packed_rrset_key* rrset, uint8_t** dname,
 391         size_t* dname_len);
 392
 393 /**
 394  * Get a printable string for a rrset trust value
 395  * @param s: rrset trust value
 396  * @return printable string.
 397  */
 398 const char* rrset_trust_to_string(enum rrset_trust s);
 399
 400 /**
 401  * Get a printable string for a security status value
 402  * @param s: security status
 403  * @return printable string.
 404  */
 405 const char* sec_status_to_string(enum sec_status s);
 406
 407 /**
 408  * Print string with neat domain name, type, class from rrset.
 409  * @param v: at what verbosity level to print this.
 410  * @param str: string of message.
 411  * @param rrset: structure with name, type and class.
 412  */
 413 void log_rrset_key(enum verbosity_value v, const char* str,
 414         struct ub_packed_rrset_key* rrset);
 415
 416 /**
 417  * Convert RR from RRset to string.
 418  * @param rrset: structure with data.
 419  * @param i: index of rr or RRSIG.
 420  * @param now: time that is subtracted from ttl before printout. Can be 0.
 421  * @param dest: destination string buffer. Must be nonNULL.
 422  * @param dest_len: length of dest buffer (>0).
 423  * @return false on failure.
 424  */
 425 int packed_rr_to_string(struct ub_packed_rrset_key* rrset, size_t i,
 426         time_t now, char* dest, size_t dest_len);
 427
 428 /**
 429  * Print the string with prefix, one rr per line.
 430  * @param v: at what verbosity level to print this.
 431  * @param str: string of message.
 432  * @param rrset: with name, and rdata, and rrsigs.
 433  */
 434 void log_packed_rrset(enum verbosity_value v, const char* str,
 435         struct ub_packed_rrset_key* rrset);
 436
 437 /**
 438  * Allocate rrset in region - no more locks needed
 439  * @param key: a (just from rrset cache looked up) rrset key + valid,
 440  *      packed data record.
 441  * @param region: where to alloc the copy
 442  * @param now: adjust the TTLs to be relative (subtract from all TTLs).
 443  * @return new region-alloced rrset key or NULL on alloc failure.
 444  */
 445 struct ub_packed_rrset_key* packed_rrset_copy_region(
 446         struct ub_packed_rrset_key* key, struct regional* region,
 447         time_t now);
 448
 449 /**
 450  * Allocate rrset with malloc (from region or you are holding the lock).
 451  * @param key: key with data entry.
 452  * @param alloc: alloc_cache to create rrset_keys
 453  * @param now: adjust the TTLs to be absolute (add to all TTLs).
 454  * @return new region-alloced rrset key or NULL on alloc failure.
 455  */
 456 struct ub_packed_rrset_key* packed_rrset_copy_alloc(
 457         struct ub_packed_rrset_key* key, struct alloc_cache* alloc,
 458         time_t now);
 459
 460 /**
 461  * Find RR index in packed rrset
 462  * Raw comparison, does not canonicalize RDATA
 463  * @param d: packed rrset
 464  * @param rdata: RDATA of RR to find
 465  * @param len: length of rdata
 466  * @param index: pointer to int to store index of found RR
 467  * @return 1 if RR found, 0 otherwise
 468  */
 469 int
 470 packed_rrset_find_rr(struct packed_rrset_data* d, uint8_t* rdata, size_t len,
 471         size_t* index);
 472
 473 #endif /* UTIL_DATA_PACKED_RRSET_H */