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