contrib/unbound/validator/val_nsec3.h

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