contrib/unbound/validator/validator.h

   1 /*
   2  * validator/validator.h - secure validator DNS query response module
   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 a module that performs validation of DNS queries.
  40  * According to RFC 4034.
  41  */
  42
  43 #ifndef VALIDATOR_VALIDATOR_H
  44 #define VALIDATOR_VALIDATOR_H
  45 #include "util/module.h"
  46 #include "util/data/msgreply.h"
  47 #include "validator/val_utils.h"
  48 struct val_anchors;
  49 struct key_cache;
  50 struct key_entry_key;
  51 struct val_neg_cache;
  52 struct config_strlist;
  53
  54 /**
  55  * This is the TTL to use when a trust anchor fails to prime. A trust anchor
  56  * will be primed no more often than this interval.  Used when harden-
  57  * dnssec-stripped is off and the trust anchor fails.
  58  */
  59 #define NULL_KEY_TTL    60 /* seconds */
  60
  61 /**
  62  * TTL for bogus key entries.  When a DS or DNSKEY fails in the chain of
  63  * trust the entire zone for that name is blacked out for this TTL.
  64  */
  65 #define BOGUS_KEY_TTL   60 /* seconds */
  66
  67 /** max number of query restarts, number of IPs to probe */
  68 #define VAL_MAX_RESTART_COUNT 5
  69
  70 /** Root key sentinel is ta preamble */
  71 #define SENTINEL_IS             "root-key-sentinel-is-ta-"
  72 /** Root key sentinel is not ta preamble */
  73 #define SENTINEL_NOT            "root-key-sentinel-not-ta-"
  74 /** Root key sentinal keytag length */
  75 #define SENTINEL_KEYTAG_LEN     5
  76
  77 /**
  78  * Global state for the validator.
  79  */
  80 struct val_env {
  81         /** key cache; these are validated keys. trusted keys only
  82          * end up here after being primed. */
  83         struct key_cache* kcache;
  84
  85         /** aggressive negative cache. index into NSECs in rrset cache. */
  86         struct val_neg_cache* neg_cache;
  87
  88         /** for debug testing a fixed validation date can be entered.
  89          * if 0, current time is used for rrsig validation */
  90         int32_t date_override;
  91
  92         /** clock skew min for signatures */
  93         int32_t skew_min;
  94
  95         /** clock skew max for signatures */
  96         int32_t skew_max;
  97
  98         /** TTL for bogus data; used instead of untrusted TTL from data.
  99          * Bogus data will not be verified more often than this interval.
 100          * seconds. */
 101         uint32_t bogus_ttl;
 102
 103         /**
 104          * Number of entries in the NSEC3 maximum iteration count table.
 105          * Keep this table short, and sorted by size
 106          */
 107         int nsec3_keyiter_count;
 108
 109         /**
 110          * NSEC3 maximum iteration count per signing key size.
 111          * This array contains key size values (in increasing order)
 112          */
 113         size_t* nsec3_keysize;
 114
 115         /**
 116          * NSEC3 maximum iteration count per signing key size.
 117          * This array contains the maximum iteration count for the keysize
 118          * in the keysize array.
 119          */
 120         size_t* nsec3_maxiter;
 121
 122         /** lock on bogus counter */
 123         lock_basic_type bogus_lock;
 124         /** number of times rrsets marked bogus */
 125         size_t num_rrset_bogus;
 126 };
 127
 128 /**
 129  * State of the validator for a query.
 130  */
 131 enum val_state {
 132         /** initial state for validation */
 133         VAL_INIT_STATE = 0,
 134         /** find the proper keys for validation, follow trust chain */
 135         VAL_FINDKEY_STATE,
 136         /** validate the answer, using found key entry */
 137         VAL_VALIDATE_STATE,
 138         /** finish up */
 139         VAL_FINISHED_STATE,
 140         /** DLV lookup state, processing DLV queries */
 141         VAL_DLVLOOKUP_STATE
 142 };
 143
 144 /**
 145  * Per query state for the validator module.
 146  */
 147 struct val_qstate {
 148         /**
 149          * State of the validator module.
 150          */
 151         enum val_state state;
 152
 153         /**
 154          * The original message we have been given to validate.
 155          */
 156         struct dns_msg* orig_msg;
 157
 158         /**
 159          * The query restart count
 160          */
 161         int restart_count;
 162         /** The blacklist saved for chainoftrust elements */
 163         struct sock_list* chain_blacklist;
 164
 165         /**
 166          * The query name we have chased to; qname after following CNAMEs
 167          */
 168         struct query_info qchase;
 169
 170         /**
 171          * The chased reply, extract from original message. Can be:
 172          *      o CNAME
 173          *      o DNAME + CNAME
 174          *      o answer
 175          *      plus authority, additional (nsecs) that have same signature.
 176          */
 177         struct reply_info* chase_reply;
 178
 179         /**
 180          * The cname skip value; the number of rrsets that have been skipped
 181          * due to chasing cnames. This is the offset into the
 182          * orig_msg->rep->rrsets array, into the answer section.
 183          * starts at 0 - for the full original message.
 184          * if it is >0 - qchase followed the cname, chase_reply setup to be
 185          * that message and relevant authority rrsets.
 186          *
 187          * The skip is also used for referral messages, where it will
 188          * range from 0, over the answer, authority and additional sections.
 189          */
 190         size_t rrset_skip;
 191
 192         /** trust anchor name */
 193         uint8_t* trust_anchor_name;
 194         /** trust anchor labels */
 195         int trust_anchor_labs;
 196         /** trust anchor length */
 197         size_t trust_anchor_len;
 198
 199         /** the DS rrset */
 200         struct ub_packed_rrset_key* ds_rrset;
 201
 202         /** domain name for empty nonterminal detection */
 203         uint8_t* empty_DS_name;
 204         /** length of empty_DS_name */
 205         size_t empty_DS_len;
 206
 207         /** the current key entry */
 208         struct key_entry_key* key_entry;
 209
 210         /** subtype */
 211         enum val_classification subtype;
 212
 213         /** signer name */
 214         uint8_t* signer_name;
 215         /** length of signer_name */
 216         size_t signer_len;
 217
 218         /** true if this state is waiting to prime a trust anchor */
 219         int wait_prime_ta;
 220
 221         /** have we already checked the DLV? */
 222         int dlv_checked;
 223         /** The name for which the DLV is looked up. For the current message
 224          * or for the current RRset (for CNAME, REFERRAL types).
 225          * If there is signer name, that may be it, else a domain name */
 226         uint8_t* dlv_lookup_name;
 227         /** length of dlv lookup name */
 228         size_t dlv_lookup_name_len;
 229         /** Name at which chain of trust stopped with insecure, starting DLV
 230          * DLV must result in chain going further down */
 231         uint8_t* dlv_insecure_at;
 232         /** length of dlv insecure point name */
 233         size_t dlv_insecure_at_len;
 234         /** status of DLV lookup. Indication to VAL_DLV_STATE what to do */
 235         enum dlv_status {
 236                 dlv_error, /* server failure */
 237                 dlv_success, /* got a DLV */
 238                 dlv_ask_higher, /* ask again */
 239                 dlv_there_is_no_dlv /* got no DLV, sure of it */
 240         } dlv_status;
 241 };
 242
 243 /**
 244  * Get the validator function block.
 245  * @return: function block with function pointers to validator methods.
 246  */
 247 struct module_func_block* val_get_funcblock(void);
 248
 249 /**
 250  * Get validator state as a string
 251  * @param state: to convert
 252  * @return constant string that is printable.
 253  */
 254 const char* val_state_to_string(enum val_state state);
 255
 256 /** validator init */
 257 int val_init(struct module_env* env, int id);
 258
 259 /** validator deinit */
 260 void val_deinit(struct module_env* env, int id);
 261
 262 /** validator operate on a query */
 263 void val_operate(struct module_qstate* qstate, enum module_ev event, int id,
 264         struct outbound_entry* outbound);
 265
 266 /**
 267  * inform validator super.
 268  *
 269  * @param qstate: query state that finished.
 270  * @param id: module id.
 271  * @param super: the qstate to inform.
 272  */
 273 void val_inform_super(struct module_qstate* qstate, int id,
 274         struct module_qstate* super);
 275
 276 /** validator cleanup query state */
 277 void val_clear(struct module_qstate* qstate, int id);
 278
 279 /**
 280  * Debug helper routine that assists worker in determining memory in
 281  * use.
 282  * @param env: module environment
 283  * @param id: module id.
 284  * @return memory in use in bytes.
 285  */
 286 size_t val_get_mem(struct module_env* env, int id);
 287
 288 #endif /* VALIDATOR_VALIDATOR_H */