unbound/validator/val_nsec3.h

   1 /*
   2  * validator/val_nsec3.h - validator NSEC3 denial of existance functions.
   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 helper functions for the validator module.
  40  * The functions help with NSEC3 checking, the different NSEC3 proofs
  41  * for denial of existance, and proofs for presence of types.
  42  *
  43  * NSEC3
  44  *                      1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3
  45  *  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  46  * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  47  * |   Hash Alg.   |     Flags     |          Iterations           |
  48  * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  49  * |  Salt Length  |                     Salt                      /
  50  * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  51  * |  Hash Length  |             Next Hashed Owner Name            /
  52  * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  53  * /                         Type Bit Maps                         /
  54  * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  55  *
  56  * NSEC3PARAM
  57  *                      1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3
  58  *  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  59  * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  60  * |   Hash Alg.   |     Flags     |          Iterations           |
  61  * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  62  * |  Salt Length  |                     Salt                      /
  63  * +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  64  *
  65  */
  66
  67 #ifndef VALIDATOR_VAL_NSEC3_H
  68 #define VALIDATOR_VAL_NSEC3_H
  69 #include "util/rbtree.h"
  70 #include "util/data/packed_rrset.h"
  71 struct val_env;
  72 struct regional;
  73 struct module_env;
  74 struct ub_packed_rrset_key;
  75 struct reply_info;
  76 struct query_info;
  77 struct key_entry_key;
  78 struct sldns_buffer;
  79
  80 /**
  81  *     0 1 2 3 4 5 6 7
  82  *    +-+-+-+-+-+-+-+-+
  83  *    |             |O|
  84  *    +-+-+-+-+-+-+-+-+
  85  * The OPT-OUT bit in the NSEC3 flags field.
  86  * If enabled, there can be zero or more unsigned delegations in the span.
  87  * If disabled, there are zero unsigned delegations in the span.
  88  */
  89 #define NSEC3_OPTOUT    0x01
  90 /**
  91  * The unknown flags in the NSEC3 flags field.
  92  * They must be zero, or the NSEC3 is ignored.
  93  */
  94 #define NSEC3_UNKNOWN_FLAGS 0xFE
  95
  96 /** The SHA1 hash algorithm for NSEC3 */
  97 #define NSEC3_HASH_SHA1 0x01
  98
  99 /**
 100  * Determine if the set of NSEC3 records provided with a response prove NAME
 101  * ERROR. This means that the NSEC3s prove a) the closest encloser exists,
 102  * b) the direct child of the closest encloser towards qname doesn't exist,
 103  * and c) *.closest encloser does not exist.
 104  *
 105  * @param env: module environment with temporary region and buffer.
 106  * @param ve: validator environment, with iteration count settings.
 107  * @param list: array of RRsets, some of which are NSEC3s.
 108  * @param num: number of RRsets in the array to examine.
 109  * @param qinfo: query that is verified for.
 110  * @param kkey: key entry that signed the NSEC3s.
 111  * @return:
 112  *      sec_status SECURE of the Name Error is proven by the NSEC3 RRs,
 113  *      BOGUS if not, INSECURE if all of the NSEC3s could be validly ignored.
 114  */
 115 enum sec_status
 116 nsec3_prove_nameerror(struct module_env* env, struct val_env* ve,
 117         struct ub_packed_rrset_key** list, size_t num,
 118         struct query_info* qinfo, struct key_entry_key* kkey);
 119
 120 /**
 121  * Determine if the NSEC3s provided in a response prove the NOERROR/NODATA
 122  * status. There are a number of different variants to this:
 123  *
 124  * 1) Normal NODATA -- qname is matched to an NSEC3 record, type is not
 125  * present.
 126  *
 127  * 2) ENT NODATA -- because there must be NSEC3 record for
 128  * empty-non-terminals, this is the same as #1.
 129  *
 130  * 3) NSEC3 ownername NODATA -- qname matched an existing, lone NSEC3
 131  * ownername, but qtype was not NSEC3. NOTE: as of nsec-05, this case no
 132  * longer exists.
 133  *
 134  * 4) Wildcard NODATA -- A wildcard matched the name, but not the type.
 135  *
 136  * 5) Opt-In DS NODATA -- the qname is covered by an opt-in span and qtype ==
 137  * DS. (or maybe some future record with the same parent-side-only property)
 138  *
 139  * @param env: module environment with temporary region and buffer.
 140  * @param ve: validator environment, with iteration count settings.
 141  * @param list: array of RRsets, some of which are NSEC3s.
 142  * @param num: number of RRsets in the array to examine.
 143  * @param qinfo: query that is verified for.
 144  * @param kkey: key entry that signed the NSEC3s.
 145  * @return:
 146  *      sec_status SECURE of the proposition is proven by the NSEC3 RRs,
 147  *      BOGUS if not, INSECURE if all of the NSEC3s could be validly ignored.
 148  */
 149 enum sec_status
 150 nsec3_prove_nodata(struct module_env* env, struct val_env* ve,
 151         struct ub_packed_rrset_key** list, size_t num,
 152         struct query_info* qinfo, struct key_entry_key* kkey);
 153
 154
 155 /**
 156  * Prove that a positive wildcard match was appropriate (no direct match
 157  * RRset).
 158  *
 159  * @param env: module environment with temporary region and buffer.
 160  * @param ve: validator environment, with iteration count settings.
 161  * @param list: array of RRsets, some of which are NSEC3s.
 162  * @param num: number of RRsets in the array to examine.
 163  * @param qinfo: query that is verified for.
 164  * @param kkey: key entry that signed the NSEC3s.
 165  * @param wc: The purported wildcard that matched. This is the wildcard name
 166  *      as *.wildcard.name., with the *. label already removed.
 167  * @return:
 168  *      sec_status SECURE of the proposition is proven by the NSEC3 RRs,
 169  *      BOGUS if not, INSECURE if all of the NSEC3s could be validly ignored.
 170  */
 171 enum sec_status
 172 nsec3_prove_wildcard(struct module_env* env, struct val_env* ve,
 173         struct ub_packed_rrset_key** list, size_t num,
 174         struct query_info* qinfo, struct key_entry_key* kkey, uint8_t* wc);
 175
 176 /**
 177  * Prove that a DS response either had no DS, or wasn't a delegation point.
 178  *
 179  * Fundamentally there are two cases here: normal NODATA and Opt-In NODATA.
 180  *
 181  * @param env: module environment with temporary region and buffer.
 182  * @param ve: validator environment, with iteration count settings.
 183  * @param list: array of RRsets, some of which are NSEC3s.
 184  * @param num: number of RRsets in the array to examine.
 185  * @param qinfo: query that is verified for.
 186  * @param kkey: key entry that signed the NSEC3s.
 187  * @param reason: string for bogus result.
 188  * @return:
 189  *      sec_status SECURE of the proposition is proven by the NSEC3 RRs,
 190  *      BOGUS if not, INSECURE if all of the NSEC3s could be validly ignored.
 191  *      or if there was no DS in an insecure (i.e., opt-in) way,
 192  *      INDETERMINATE if it was clear that this wasn't a delegation point.
 193  */
 194 enum sec_status
 195 nsec3_prove_nods(struct module_env* env, struct val_env* ve,
 196         struct ub_packed_rrset_key** list, size_t num,
 197         struct query_info* qinfo, struct key_entry_key* kkey, char** reason);
 198
 199 /**
 200  * Prove NXDOMAIN or NODATA.
 201  *
 202  * @param env: module environment with temporary region and buffer.
 203  * @param ve: validator environment, with iteration count settings.
 204  * @param list: array of RRsets, some of which are NSEC3s.
 205  * @param num: number of RRsets in the array to examine.
 206  * @param qinfo: query that is verified for.
 207  * @param kkey: key entry that signed the NSEC3s.
 208  * @param nodata: if return value is secure, this indicates if nodata or
 209  *      nxdomain was proven.
 210  * @return:
 211  *      sec_status SECURE of the proposition is proven by the NSEC3 RRs,
 212  *      BOGUS if not, INSECURE if all of the NSEC3s could be validly ignored.
 213  */
 214 enum sec_status
 215 nsec3_prove_nxornodata(struct module_env* env, struct val_env* ve,
 216         struct ub_packed_rrset_key** list, size_t num,
 217         struct query_info* qinfo, struct key_entry_key* kkey, int* nodata);
 218
 219 /**
 220  * The NSEC3 hash result storage.
 221  * Consists of an rbtree, with these nodes in it.
 222  * The nodes detail how a set of parameters (from nsec3 rr) plus
 223  * a dname result in a hash.
 224  */
 225 struct nsec3_cached_hash {
 226         /** rbtree node, key is this structure */
 227         rbnode_t node;
 228         /** where are the parameters for conversion, in this rrset data */
 229         struct ub_packed_rrset_key* nsec3;
 230         /** where are the parameters for conversion, this RR number in data */
 231         int rr;
 232         /** the name to convert */
 233         uint8_t* dname;
 234         /** length of the dname */
 235         size_t dname_len;
 236         /** the hash result (not base32 encoded) */
 237         uint8_t* hash;
 238         /** length of hash in bytes */
 239         size_t hash_len;
 240         /** the hash result in base32 encoding */
 241         uint8_t* b32;
 242         /** length of base32 encoding (as a label) */
 243         size_t b32_len;
 244 };
 245
 246 /**
 247  * Rbtree for hash cache comparison function.
 248  * @param c1: key 1.
 249  * @param c2: key 2.
 250  * @return: comparison code, -1, 0, 1, of the keys.
 251  */
 252 int nsec3_hash_cmp(const void* c1, const void* c2);
 253
 254 /**
 255  * Obtain the hash of an owner name.
 256  * Used internally by the nsec3 proof functions in this file.
 257  * published to enable unit testing of hash algorithms and cache.
 258  *
 259  * @param table: the cache table. Must be inited at start.
 260  * @param region: scratch region to use for allocation.
 261  *      This region holds the tree, if you wipe the region, reinit the tree.
 262  * @param buf: temporary buffer.
 263  * @param nsec3: the rrset with parameters
 264  * @param rr: rr number from d that has the NSEC3 parameters to hash to.
 265  * @param dname: name to hash
 266  *      This pointer is used inside the tree, assumed region-alloced.
 267  * @param dname_len: the length of the name.
 268  * @param hash: the hash node is returned on success.
 269  * @return:
 270  *      1 on success, either from cache or newly hashed hash is returned.
 271  *      0 on a malloc failure.
 272  *      -1 if the NSEC3 rr was badly formatted (i.e. formerr).
 273  */
 274 int nsec3_hash_name(rbtree_t* table, struct regional* region,
 275         struct sldns_buffer* buf, struct ub_packed_rrset_key* nsec3, int rr,
 276         uint8_t* dname, size_t dname_len, struct nsec3_cached_hash** hash);
 277
 278 /**
 279  * Get next owner name, converted to base32 encoding and with the
 280  * zone name (taken from the nsec3 owner name) appended.
 281  * @param rrset: the NSEC3 rrset.
 282  * @param r: the rr num of the nsec3 in the rrset.
 283  * @param buf: buffer to store name in
 284  * @param max: size of buffer.
 285  * @return length of name on success. 0 on failure (buffer too short or
 286  *      bad format nsec3 record).
 287  */
 288 size_t nsec3_get_nextowner_b32(struct ub_packed_rrset_key* rrset, int r,
 289         uint8_t* buf, size_t max);
 290
 291 /**
 292  * Convert hash into base32 encoding and with the
 293  * zone name appended.
 294  * @param hash: hashed buffer
 295  * @param hashlen: length of hash
 296  * @param zone: name of zone
 297  * @param zonelen: length of zonename.
 298  * @param buf: buffer to store name in
 299  * @param max: size of buffer.
 300  * @return length of name on success. 0 on failure (buffer too short or
 301  *      bad format nsec3 record).
 302  */
 303 size_t nsec3_hash_to_b32(uint8_t* hash, size_t hashlen, uint8_t* zone,
 304         size_t zonelen, uint8_t* buf, size_t max);
 305
 306 /**
 307  * Get NSEC3 parameters out of rr.
 308  * @param rrset: the NSEC3 rrset.
 309  * @param r: the rr num of the nsec3 in the rrset.
 310  * @param algo: nsec3 hash algo.
 311  * @param iter: iteration count.
 312  * @param salt: ptr to salt inside rdata.
 313  * @param saltlen: length of salt.
 314  * @return 0 if bad formatted, unknown nsec3 hash algo, or unknown flags set.
 315  */
 316 int nsec3_get_params(struct ub_packed_rrset_key* rrset, int r,
 317         int* algo, size_t* iter, uint8_t** salt, size_t* saltlen);
 318
 319 /**
 320  * Get NSEC3 hashed in a buffer
 321  * @param buf: buffer for temp use.
 322  * @param nm: name to hash
 323  * @param nmlen: length of nm.
 324  * @param algo: algo to use, must be known.
 325  * @param iter: iterations
 326  * @param salt: salt for nsec3
 327  * @param saltlen: length of salt.
 328  * @param res: result of hash stored here.
 329  * @param max: maximum space for result.
 330  * @return 0 on failure, otherwise bytelength stored.
 331  */
 332 size_t nsec3_get_hashed(struct sldns_buffer* buf, uint8_t* nm, size_t nmlen,
 333         int algo, size_t iter, uint8_t* salt, size_t saltlen, uint8_t* res,
 334         size_t max);
 335
 336 /**
 337  * see if NSEC3 RR contains given type
 338  * @param rrset: NSEC3 rrset
 339  * @param r: RR in rrset
 340  * @param type: in host order to check bit for.
 341  * @return true if bit set, false if not or error.
 342  */
 343 int nsec3_has_type(struct ub_packed_rrset_key* rrset, int r, uint16_t type);
 344
 345 /**
 346  * return if nsec3 RR has the optout flag
 347  * @param rrset: NSEC3 rrset
 348  * @param r: RR in rrset
 349  * @return true if optout, false on error or not optout
 350  */
 351 int nsec3_has_optout(struct ub_packed_rrset_key* rrset, int r);
 352
 353 /**
 354  * Return nsec3 RR next hashed owner name
 355  * @param rrset: NSEC3 rrset
 356  * @param r: RR in rrset
 357  * @param next: ptr into rdata to next owner hash
 358  * @param nextlen: length of hash.
 359  * @return false on malformed
 360  */
 361 int nsec3_get_nextowner(struct ub_packed_rrset_key* rrset, int r,
 362         uint8_t** next, size_t* nextlen);
 363
 364 /**
 365  * nsec3Covers
 366  * Given a hash and a candidate NSEC3Record, determine if that NSEC3Record
 367  * covers the hash. Covers specifically means that the hash is in between
 368  * the owner and next hashes and does not equal either.
 369  *
 370  * @param zone: the zone name.
 371  * @param hash: the hash of the name
 372  * @param rrset: the rrset of the NSEC3.
 373  * @param rr: which rr in the rrset.
 374  * @param buf: temporary buffer.
 375  * @return true if covers, false if not.
 376  */
 377 int nsec3_covers(uint8_t* zone, struct nsec3_cached_hash* hash,
 378         struct ub_packed_rrset_key* rrset, int rr, struct sldns_buffer* buf);
 379
 380 #endif /* VALIDATOR_VAL_NSEC3_H */