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 LIMITED
  25  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  26  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
  27  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  28  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  29  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  30  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  31  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  32  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  33  * 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         /** If set, the validator should clean the additional section of
  97          * secure messages.
  98          */
  99         int clean_additional;
 100
 101         /**
 102          * If set, the validator will not make messages bogus, instead
 103          * indeterminate is issued, so that no clients receive SERVFAIL.
 104          * This allows an operator to run validation 'shadow' without
 105          * hurting responses to clients.
 106          */
 107         int permissive_mode;
 108
 109         /**
 110          * Number of entries in the NSEC3 maximum iteration count table.
 111          * Keep this table short, and sorted by size
 112          */
 113         int nsec3_keyiter_count;
 114
 115         /**
 116          * NSEC3 maximum iteration count per signing key size.
 117          * This array contains key size values (in increasing order)
 118          */
 119         size_t* nsec3_keysize;
 120
 121         /**
 122          * NSEC3 maximum iteration count per signing key size.
 123          * This array contains the maximum iteration count for the keysize
 124          * in the keysize array.
 125          */
 126         size_t* nsec3_maxiter;
 127
 128         /** lock on bogus counter */
 129         lock_basic_t bogus_lock;
 130         /** number of times rrsets marked bogus */
 131         size_t num_rrset_bogus;
 132 };
 133
 134 /**
 135  * State of the validator for a query.
 136  */
 137 enum val_state {
 138         /** initial state for validation */
 139         VAL_INIT_STATE = 0,
 140         /** find the proper keys for validation, follow trust chain */
 141         VAL_FINDKEY_STATE,
 142         /** validate the answer, using found key entry */
 143         VAL_VALIDATE_STATE,
 144         /** finish up */
 145         VAL_FINISHED_STATE,
 146         /** DLV lookup state, processing DLV queries */
 147         VAL_DLVLOOKUP_STATE
 148 };
 149
 150 /**
 151  * Per query state for the validator module.
 152  */
 153 struct val_qstate {
 154         /**
 155          * State of the validator module.
 156          */
 157         enum val_state state;
 158
 159         /**
 160          * The original message we have been given to validate.
 161          */
 162         struct dns_msg* orig_msg;
 163
 164         /**
 165          * The query restart count
 166          */
 167         int restart_count;
 168         /** The blacklist saved for chainoftrust elements */
 169         struct sock_list* chain_blacklist;
 170
 171         /**
 172          * The query name we have chased to; qname after following CNAMEs
 173          */
 174         struct query_info qchase;
 175
 176         /**
 177          * The chased reply, extract from original message. Can be:
 178          *      o CNAME
 179          *      o DNAME + CNAME
 180          *      o answer
 181          *      plus authority, additional (nsecs) that have same signature.
 182          */
 183         struct reply_info* chase_reply;
 184
 185         /**
 186          * The cname skip value; the number of rrsets that have been skipped
 187          * due to chasing cnames. This is the offset into the
 188          * orig_msg->rep->rrsets array, into the answer section.
 189          * starts at 0 - for the full original message.
 190          * if it is >0 - qchase followed the cname, chase_reply setup to be
 191          * that message and relevant authority rrsets.
 192          *
 193          * The skip is also used for referral messages, where it will
 194          * range from 0, over the answer, authority and additional sections.
 195          */
 196         size_t rrset_skip;
 197
 198         /** trust anchor name */
 199         uint8_t* trust_anchor_name;
 200         /** trust anchor labels */
 201         int trust_anchor_labs;
 202         /** trust anchor length */
 203         size_t trust_anchor_len;
 204
 205         /** the DS rrset */
 206         struct ub_packed_rrset_key* ds_rrset;
 207
 208         /** domain name for empty nonterminal detection */
 209         uint8_t* empty_DS_name;
 210         /** length of empty_DS_name */
 211         size_t empty_DS_len;
 212
 213         /** the current key entry */
 214         struct key_entry_key* key_entry;
 215
 216         /** subtype */
 217         enum val_classification subtype;
 218
 219         /** signer name */
 220         uint8_t* signer_name;
 221         /** length of signer_name */
 222         size_t signer_len;
 223
 224         /** true if this state is waiting to prime a trust anchor */
 225         int wait_prime_ta;
 226
 227         /** have we already checked the DLV? */
 228         int dlv_checked;
 229         /** The name for which the DLV is looked up. For the current message
 230          * or for the current RRset (for CNAME, REFERRAL types).
 231          * If there is signer name, that may be it, else a domain name */
 232         uint8_t* dlv_lookup_name;
 233         /** length of dlv lookup name */
 234         size_t dlv_lookup_name_len;
 235         /** Name at which chain of trust stopped with insecure, starting DLV
 236          * DLV must result in chain going further down */
 237         uint8_t* dlv_insecure_at;
 238         /** length of dlv insecure point name */
 239         size_t dlv_insecure_at_len;
 240         /** status of DLV lookup. Indication to VAL_DLV_STATE what to do */
 241         enum dlv_status {
 242                 dlv_error, /* server failure */
 243                 dlv_success, /* got a DLV */
 244                 dlv_ask_higher, /* ask again */
 245                 dlv_there_is_no_dlv /* got no DLV, sure of it */
 246         } dlv_status;
 247 };
 248
 249 /**
 250  * Get the validator function block.
 251  * @return: function block with function pointers to validator methods.
 252  */
 253 struct module_func_block* val_get_funcblock(void);
 254
 255 /**
 256  * Get validator state as a string
 257  * @param state: to convert
 258  * @return constant string that is printable.
 259  */
 260 const char* val_state_to_string(enum val_state state);
 261
 262 /** validator init */
 263 int val_init(struct module_env* env, int id);
 264
 265 /** validator deinit */
 266 void val_deinit(struct module_env* env, int id);
 267
 268 /** validator operate on a query */
 269 void val_operate(struct module_qstate* qstate, enum module_ev event, int id,
 270         struct outbound_entry* outbound);
 271
 272 /**
 273  * inform validator super.
 274  *
 275  * @param qstate: query state that finished.
 276  * @param id: module id.
 277  * @param super: the qstate to inform.
 278  */
 279 void val_inform_super(struct module_qstate* qstate, int id,
 280         struct module_qstate* super);
 281
 282 /** validator cleanup query state */
 283 void val_clear(struct module_qstate* qstate, int id);
 284
 285 /**
 286  * Debug helper routine that assists worker in determining memory in
 287  * use.
 288  * @param env: module environment
 289  * @param id: module id.
 290  * @return memory in use in bytes.
 291  */
 292 size_t val_get_mem(struct module_env* env, int id);
 293
 294 #endif /* VALIDATOR_VALIDATOR_H */