1 /* 2 * validator/val_utils.h - validator utility 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 */ 41 42 #ifndef VALIDATOR_VAL_UTILS_H 43 #define VALIDATOR_VAL_UTILS_H 44 #include "util/data/packed_rrset.h" 45 #include "sldns/pkthdr.h" 46 struct query_info; 47 struct reply_info; 48 struct val_env; 49 struct module_env; 50 struct module_qstate; 51 struct ub_packed_rrset_key; 52 struct key_entry_key; 53 struct regional; 54 struct val_anchors; 55 struct rrset_cache; 56 struct sock_list; 57 58 /** 59 * Response classifications for the validator. The different types of proofs. 60 */ 61 enum val_classification { 62 /** Not subtyped yet. */ 63 VAL_CLASS_UNTYPED = 0, 64 /** Not a recognized subtype. */ 65 VAL_CLASS_UNKNOWN, 66 /** A positive, direct, response */ 67 VAL_CLASS_POSITIVE, 68 /** A positive response, with a CNAME/DNAME chain. */ 69 VAL_CLASS_CNAME, 70 /** A NOERROR/NODATA response. */ 71 VAL_CLASS_NODATA, 72 /** A NXDOMAIN response. */ 73 VAL_CLASS_NAMEERROR, 74 /** A CNAME/DNAME chain, and the offset is at the end of it, 75 * but there is no answer here, it can be NAMEERROR or NODATA. */ 76 VAL_CLASS_CNAMENOANSWER, 77 /** A referral, from cache with a nonRD query. */ 78 VAL_CLASS_REFERRAL, 79 /** A response to a qtype=ANY query. */ 80 VAL_CLASS_ANY 81 }; 82 83 /** 84 * Given a response, classify ANSWER responses into a subtype. 85 * @param query_flags: query flags for the original query. 86 * @param origqinf: query info. The original query name. 87 * @param qinf: query info. The chased query name. 88 * @param rep: response. The original response. 89 * @param skip: offset into the original response answer section. 90 * @return A subtype, all values possible except UNTYPED . 91 * Once CNAME type is returned you can increase skip. 92 * Then, another CNAME type, CNAME_NOANSWER or POSITIVE are possible. 93 */ 94 enum val_classification val_classify_response(uint16_t query_flags, 95 struct query_info* origqinf, struct query_info* qinf, 96 struct reply_info* rep, size_t skip); 97 98 /** 99 * Given a response, determine the name of the "signer". This is primarily 100 * to determine if the response is, in fact, signed at all, and, if so, what 101 * is the name of the most pertinent keyset. 102 * 103 * @param subtype: the type from classify. 104 * @param qinf: query, the chased query name. 105 * @param rep: response to that, original response. 106 * @param cname_skip: how many answer rrsets have been skipped due to CNAME 107 * chains being chased around. 108 * @param signer_name: signer name, if the response is signed 109 * (even partially), or null if the response isn't signed. 110 * @param signer_len: length of signer_name of 0 if signer_name is NULL. 111 */ 112 void val_find_signer(enum val_classification subtype, 113 struct query_info* qinf, struct reply_info* rep, 114 size_t cname_skip, uint8_t** signer_name, size_t* signer_len); 115 116 /** 117 * Verify RRset with keys 118 * @param env: module environment (scratch buffer) 119 * @param ve: validator environment (verification settings) 120 * @param rrset: what to verify 121 * @param keys: dnskey rrset to verify with. 122 * @param sigalg: if nonNULL provide downgrade protection otherwise one 123 * algorithm is enough. Algo list is constructed in here. 124 * @param reason: reason of failure. Fixed string or alloced in scratch. 125 * @param section: section of packet where this rrset comes from. 126 * @param qstate: qstate with region. 127 * @return security status of verification. 128 */ 129 enum sec_status val_verify_rrset(struct module_env* env, struct val_env* ve, 130 struct ub_packed_rrset_key* rrset, struct ub_packed_rrset_key* keys, 131 uint8_t* sigalg, char** reason, sldns_pkt_section section, 132 struct module_qstate* qstate); 133 134 /** 135 * Verify RRset with keys from a keyset. 136 * @param env: module environment (scratch buffer) 137 * @param ve: validator environment (verification settings) 138 * @param rrset: what to verify 139 * @param kkey: key_entry to verify with. 140 * @param reason: reason of failure. Fixed string or alloced in scratch. 141 * @param section: section of packet where this rrset comes from. 142 * @param qstate: qstate with region. 143 * @return security status of verification. 144 */ 145 enum sec_status val_verify_rrset_entry(struct module_env* env, 146 struct val_env* ve, struct ub_packed_rrset_key* rrset, 147 struct key_entry_key* kkey, char** reason, sldns_pkt_section section, 148 struct module_qstate* qstate); 149 150 /** 151 * Verify DNSKEYs with DS rrset. Like val_verify_new_DNSKEYs but 152 * returns a sec_status instead of a key_entry. 153 * @param env: module environment (scratch buffer) 154 * @param ve: validator environment (verification settings) 155 * @param dnskey_rrset: DNSKEY rrset to verify 156 * @param ds_rrset: DS rrset to verify with. 157 * @param sigalg: if nonNULL provide downgrade protection otherwise one 158 * algorithm is enough. The list of signalled algorithms is returned, 159 * must have enough space for ALGO_NEEDS_MAX+1. 160 * @param reason: reason of failure. Fixed string or alloced in scratch. 161 * @param qstate: qstate with region. 162 * @return: sec_status_secure if a DS matches. 163 * sec_status_insecure if end of trust (i.e., unknown algorithms). 164 * sec_status_bogus if it fails. 165 */ 166 enum sec_status val_verify_DNSKEY_with_DS(struct module_env* env, 167 struct val_env* ve, struct ub_packed_rrset_key* dnskey_rrset, 168 struct ub_packed_rrset_key* ds_rrset, uint8_t* sigalg, char** reason, 169 struct module_qstate* qstate); 170 171 /** 172 * Verify DNSKEYs with DS and DNSKEY rrset. Like val_verify_DNSKEY_with_DS 173 * but for a trust anchor. 174 * @param env: module environment (scratch buffer) 175 * @param ve: validator environment (verification settings) 176 * @param dnskey_rrset: DNSKEY rrset to verify 177 * @param ta_ds: DS rrset to verify with. 178 * @param ta_dnskey: DNSKEY rrset to verify with. 179 * @param sigalg: if nonNULL provide downgrade protection otherwise one 180 * algorithm is enough. The list of signalled algorithms is returned, 181 * must have enough space for ALGO_NEEDS_MAX+1. 182 * @param reason: reason of failure. Fixed string or alloced in scratch. 183 * @param qstate: qstate with region. 184 * @return: sec_status_secure if a DS matches. 185 * sec_status_insecure if end of trust (i.e., unknown algorithms). 186 * sec_status_bogus if it fails. 187 */ 188 enum sec_status val_verify_DNSKEY_with_TA(struct module_env* env, 189 struct val_env* ve, struct ub_packed_rrset_key* dnskey_rrset, 190 struct ub_packed_rrset_key* ta_ds, 191 struct ub_packed_rrset_key* ta_dnskey, uint8_t* sigalg, char** reason, 192 struct module_qstate* qstate); 193 194 /** 195 * Verify new DNSKEYs with DS rrset. The DS contains hash values that should 196 * match the DNSKEY keys. 197 * match the DS to a DNSKEY and verify the DNSKEY rrset with that key. 198 * 199 * @param region: where to allocate key entry result. 200 * @param env: module environment (scratch buffer) 201 * @param ve: validator environment (verification settings) 202 * @param dnskey_rrset: DNSKEY rrset to verify 203 * @param ds_rrset: DS rrset to verify with. 204 * @param downprot: if true provide downgrade protection otherwise one 205 * algorithm is enough. 206 * @param reason: reason of failure. Fixed string or alloced in scratch. 207 * @param qstate: qstate with region. 208 * @return a KeyEntry. This will either contain the now trusted 209 * dnskey_rrset, a "null" key entry indicating that this DS 210 * rrset/DNSKEY pair indicate an secure end to the island of trust 211 * (i.e., unknown algorithms), or a "bad" KeyEntry if the dnskey 212 * rrset fails to verify. Note that the "null" response should 213 * generally only occur in a private algorithm scenario: normally 214 * this sort of thing is checked before fetching the matching DNSKEY 215 * rrset. 216 * if downprot is set, a key entry with an algo list is made. 217 */ 218 struct key_entry_key* val_verify_new_DNSKEYs(struct regional* region, 219 struct module_env* env, struct val_env* ve, 220 struct ub_packed_rrset_key* dnskey_rrset, 221 struct ub_packed_rrset_key* ds_rrset, int downprot, char** reason, 222 struct module_qstate* qstate); 223 224 225 /** 226 * Verify rrset with trust anchor: DS and DNSKEY rrset. 227 * 228 * @param region: where to allocate key entry result. 229 * @param env: module environment (scratch buffer) 230 * @param ve: validator environment (verification settings) 231 * @param dnskey_rrset: DNSKEY rrset to verify 232 * @param ta_ds_rrset: DS rrset to verify with. 233 * @param ta_dnskey_rrset: the DNSKEY rrset to verify with. 234 * @param downprot: if true provide downgrade protection otherwise one 235 * algorithm is enough. 236 * @param reason: reason of failure. Fixed string or alloced in scratch. 237 * @param qstate: qstate with region. 238 * @return a KeyEntry. This will either contain the now trusted 239 * dnskey_rrset, a "null" key entry indicating that this DS 240 * rrset/DNSKEY pair indicate an secure end to the island of trust 241 * (i.e., unknown algorithms), or a "bad" KeyEntry if the dnskey 242 * rrset fails to verify. Note that the "null" response should 243 * generally only occur in a private algorithm scenario: normally 244 * this sort of thing is checked before fetching the matching DNSKEY 245 * rrset. 246 * if downprot is set, a key entry with an algo list is made. 247 */ 248 struct key_entry_key* val_verify_new_DNSKEYs_with_ta(struct regional* region, 249 struct module_env* env, struct val_env* ve, 250 struct ub_packed_rrset_key* dnskey_rrset, 251 struct ub_packed_rrset_key* ta_ds_rrset, 252 struct ub_packed_rrset_key* ta_dnskey_rrset, 253 int downprot, char** reason, struct module_qstate* qstate); 254 255 /** 256 * Determine if DS rrset is usable for validator or not. 257 * Returns true if the algorithms for key and DShash are supported, 258 * for at least one RR. 259 * 260 * @param ds_rrset: the newly received DS rrset. 261 * @return true or false if not usable. 262 */ 263 int val_dsset_isusable(struct ub_packed_rrset_key* ds_rrset); 264 265 /** 266 * Determine by looking at a signed RRset whether or not the RRset name was 267 * the result of a wildcard expansion. If so, return the name of the 268 * generating wildcard. 269 * 270 * @param rrset The rrset to check. 271 * @param wc: the wildcard name, if the rrset was synthesized from a wildcard. 272 * unchanged if not. The wildcard name, without "*." in front, is 273 * returned. This is a pointer into the rrset owner name. 274 * @param wc_len: the length of the returned wildcard name. 275 * @return false if the signatures are inconsistent in indicating the 276 * wildcard status; possible spoofing of wildcard response for other 277 * responses is being tried. We lost the status which rrsig was verified 278 * after the verification routine finished, so we simply check if 279 * the signatures are consistent; inserting a fake signature is a denial 280 * of service; but in that you could also have removed the real 281 * signature anyway. 282 */ 283 int val_rrset_wildcard(struct ub_packed_rrset_key* rrset, uint8_t** wc, 284 size_t* wc_len); 285 286 /** 287 * Chase the cname to the next query name. 288 * @param qchase: the current query name, updated to next target. 289 * @param rep: original message reply to look at CNAMEs. 290 * @param cname_skip: the skip into the answer section. Updated to skip 291 * DNAME and CNAME to the next part of the answer. 292 * @return false on error (bad rdata). 293 */ 294 int val_chase_cname(struct query_info* qchase, struct reply_info* rep, 295 size_t* cname_skip); 296 297 /** 298 * Fill up the chased reply with the content from the original reply; 299 * as pointers to those rrsets. Select the part after the cname_skip into 300 * the answer section, NS and AR sections that are signed with same signer. 301 * 302 * @param chase: chased reply, filled up. 303 * @param orig: original reply. 304 * @param cname_skip: which part of the answer section to skip. 305 * The skipped part contains CNAME(and DNAME)s that have been chased. 306 * @param name: the signer name to look for. 307 * @param len: length of name. 308 * @param signer: signer name or NULL if an unsigned RRset is considered. 309 * If NULL, rrsets with the lookup name are copied over. 310 */ 311 void val_fill_reply(struct reply_info* chase, struct reply_info* orig, 312 size_t cname_skip, uint8_t* name, size_t len, uint8_t* signer); 313 314 /** 315 * Remove rrset with index from reply, from the authority section. 316 * @param rep: reply to remove it from. 317 * @param index: rrset to remove, must be in the authority section. 318 */ 319 void val_reply_remove_auth(struct reply_info* rep, size_t index); 320 321 /** 322 * Remove all unsigned or non-secure status rrsets from NS and AR sections. 323 * So that unsigned data does not get let through to clients, when we have 324 * found the data to be secure. 325 * 326 * @param env: environment with cleaning options. 327 * @param rep: reply to dump all nonsecure stuff out of. 328 */ 329 void val_check_nonsecure(struct module_env* env, struct reply_info* rep); 330 331 /** 332 * Mark all unchecked rrset entries not below a trust anchor as indeterminate. 333 * Only security==unchecked rrsets are updated. 334 * @param rep: the reply with rrsets. 335 * @param anchors: the trust anchors. 336 * @param r: rrset cache to store updated security status into. 337 * @param env: module environment 338 */ 339 void val_mark_indeterminate(struct reply_info* rep, 340 struct val_anchors* anchors, struct rrset_cache* r, 341 struct module_env* env); 342 343 /** 344 * Mark all unchecked rrset entries below a NULL key entry as insecure. 345 * Only security==unchecked rrsets are updated. 346 * @param rep: the reply with rrsets. 347 * @param kname: end of secure space name. 348 * @param r: rrset cache to store updated security status into. 349 * @param env: module environment 350 */ 351 void val_mark_insecure(struct reply_info* rep, uint8_t* kname, 352 struct rrset_cache* r, struct module_env* env); 353 354 /** 355 * Find next unchecked rrset position, return it for skip. 356 * @param rep: the original reply to look into. 357 * @param skip: the skip now. 358 * @return new skip, which may be at the rep->rrset_count position to signal 359 * there are no unchecked items. 360 */ 361 size_t val_next_unchecked(struct reply_info* rep, size_t skip); 362 363 /** 364 * Find the signer name for an RRset. 365 * @param rrset: the rrset. 366 * @param sname: signer name is returned or NULL if not signed. 367 * @param slen: length of sname (or 0). 368 */ 369 void val_find_rrset_signer(struct ub_packed_rrset_key* rrset, uint8_t** sname, 370 size_t* slen); 371 372 /** 373 * Get string to denote the classification result. 374 * @param subtype: from classification function. 375 * @return static string to describe the classification. 376 */ 377 const char* val_classification_to_string(enum val_classification subtype); 378 379 /** 380 * Add existing list to blacklist. 381 * @param blacklist: the blacklist with result 382 * @param region: the region where blacklist is allocated. 383 * Allocation failures are logged. 384 * @param origin: origin list to add, if NULL, a cache-entry is added to 385 * the blacklist to stop cache from being used. 386 * @param cross: if true this is a cross-qstate copy, and the 'origin' 387 * list is not allocated in the same region as the blacklist. 388 */ 389 void val_blacklist(struct sock_list** blacklist, struct regional* region, 390 struct sock_list* origin, int cross); 391 392 /** 393 * check if has dnssec info, and if it has signed nsecs. gives error reason. 394 * @param rep: reply to check. 395 * @param reason: returned on fail. 396 * @return false if message has no signed nsecs. Can not prove negatives. 397 */ 398 int val_has_signed_nsecs(struct reply_info* rep, char** reason); 399 400 /** 401 * Return algo number for favorite (best) algorithm that we support in DS. 402 * @param ds_rrset: the DSes in this rrset are inspected and best algo chosen. 403 * @return algo number or 0 if none supported. 0 is unused as algo number. 404 */ 405 int val_favorite_ds_algo(struct ub_packed_rrset_key* ds_rrset); 406 407 /** 408 * Find DS denial message in cache. Saves new qstate allocation and allows 409 * the validator to use partial content which is not enough to construct a 410 * message for network (or user) consumption. Without SOA for example, 411 * which is a common occurrence in the unbound code since the referrals contain 412 * NSEC/NSEC3 rrs without the SOA element, thus do not allow synthesis of a 413 * full negative reply, but do allow synthesis of sufficient proof. 414 * @param env: query env with caches and time. 415 * @param nm: name of DS record sought. 416 * @param nmlen: length of name. 417 * @param c: class of DS RR. 418 * @param region: where to allocate result. 419 * @param topname: name of the key that is currently in use, that will get 420 * used to validate the result, and thus no higher entries from the 421 * negative cache need to be examined. 422 * @return a dns_msg on success. NULL on failure. 423 */ 424 struct dns_msg* val_find_DS(struct module_env* env, uint8_t* nm, size_t nmlen, 425 uint16_t c, struct regional* region, uint8_t* topname); 426 427 #endif /* VALIDATOR_VAL_UTILS_H */ 428