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 };
 141
 142 /**
 143  * Per query state for the validator module.
 144  */
 145 struct val_qstate {
 146         /**
 147          * State of the validator module.
 148          */
 149         enum val_state state;
 150
 151         /**
 152          * The original message we have been given to validate.
 153          */
 154         struct dns_msg* orig_msg;
 155
 156         /**
 157          * The query restart count
 158          */
 159         int restart_count;
 160         /** The blacklist saved for chainoftrust elements */
 161         struct sock_list* chain_blacklist;
 162
 163         /**
 164          * The query name we have chased to; qname after following CNAMEs
 165          */
 166         struct query_info qchase;
 167
 168         /**
 169          * The chased reply, extract from original message. Can be:
 170          *      o CNAME
 171          *      o DNAME + CNAME
 172          *      o answer
 173          *      plus authority, additional (nsecs) that have same signature.
 174          */
 175         struct reply_info* chase_reply;
 176
 177         /**
 178          * The cname skip value; the number of rrsets that have been skipped
 179          * due to chasing cnames. This is the offset into the
 180          * orig_msg->rep->rrsets array, into the answer section.
 181          * starts at 0 - for the full original message.
 182          * if it is >0 - qchase followed the cname, chase_reply setup to be
 183          * that message and relevant authority rrsets.
 184          *
 185          * The skip is also used for referral messages, where it will
 186          * range from 0, over the answer, authority and additional sections.
 187          */
 188         size_t rrset_skip;
 189
 190         /** trust anchor name */
 191         uint8_t* trust_anchor_name;
 192         /** trust anchor labels */
 193         int trust_anchor_labs;
 194         /** trust anchor length */
 195         size_t trust_anchor_len;
 196
 197         /** the DS rrset */
 198         struct ub_packed_rrset_key* ds_rrset;
 199
 200         /** domain name for empty nonterminal detection */
 201         uint8_t* empty_DS_name;
 202         /** length of empty_DS_name */
 203         size_t empty_DS_len;
 204
 205         /** the current key entry */
 206         struct key_entry_key* key_entry;
 207
 208         /** subtype */
 209         enum val_classification subtype;
 210
 211         /** signer name */
 212         uint8_t* signer_name;
 213         /** length of signer_name */
 214         size_t signer_len;
 215
 216         /** true if this state is waiting to prime a trust anchor */
 217         int wait_prime_ta;
 218 };
 219
 220 /**
 221  * Get the validator function block.
 222  * @return: function block with function pointers to validator methods.
 223  */
 224 struct module_func_block* val_get_funcblock(void);
 225
 226 /**
 227  * Get validator state as a string
 228  * @param state: to convert
 229  * @return constant string that is printable.
 230  */
 231 const char* val_state_to_string(enum val_state state);
 232
 233 /** validator init */
 234 int val_init(struct module_env* env, int id);
 235
 236 /** validator deinit */
 237 void val_deinit(struct module_env* env, int id);
 238
 239 /** validator operate on a query */
 240 void val_operate(struct module_qstate* qstate, enum module_ev event, int id,
 241         struct outbound_entry* outbound);
 242
 243 /**
 244  * inform validator super.
 245  *
 246  * @param qstate: query state that finished.
 247  * @param id: module id.
 248  * @param super: the qstate to inform.
 249  */
 250 void val_inform_super(struct module_qstate* qstate, int id,
 251         struct module_qstate* super);
 252
 253 /** validator cleanup query state */
 254 void val_clear(struct module_qstate* qstate, int id);
 255
 256 /**
 257  * Debug helper routine that assists worker in determining memory in
 258  * use.
 259  * @param env: module environment
 260  * @param id: module id.
 261  * @return memory in use in bytes.
 262  */
 263 size_t val_get_mem(struct module_env* env, int id);
 264
 265 #endif /* VALIDATOR_VALIDATOR_H */