2 * validator/validator.h - secure validator DNS query response module
4 * Copyright (c) 2007, NLnet Labs. All rights reserved.
6 * This software is open source.
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
12 * Redistributions of source code must retain the above copyright notice,
13 * this list of conditions and the following disclaimer.
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.
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.
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.
39 * This file contains a module that performs validation of DNS queries.
40 * According to RFC 4034.
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"
52 struct config_strlist;
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.
59 #define NULL_KEY_TTL 60 /* seconds */
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.
65 #define BOGUS_KEY_TTL 60 /* seconds */
67 /** max number of query restarts, number of IPs to probe */
68 #define VAL_MAX_RESTART_COUNT 5
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
78 * Global state for the validator.
81 /** key cache; these are validated keys. trusted keys only
82 * end up here after being primed. */
83 struct key_cache* kcache;
85 /** aggressive negative cache. index into NSECs in rrset cache. */
86 struct val_neg_cache* neg_cache;
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;
92 /** clock skew min for signatures */
95 /** clock skew max for signatures */
98 /** TTL for bogus data; used instead of untrusted TTL from data.
99 * Bogus data will not be verified more often than this interval.
104 * Number of entries in the NSEC3 maximum iteration count table.
105 * Keep this table short, and sorted by size
107 int nsec3_keyiter_count;
110 * NSEC3 maximum iteration count per signing key size.
111 * This array contains key size values (in increasing order)
113 size_t* nsec3_keysize;
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.
120 size_t* nsec3_maxiter;
122 /** lock on bogus counter */
123 lock_basic_type bogus_lock;
124 /** number of times rrsets marked bogus */
125 size_t num_rrset_bogus;
129 * State of the validator for a query.
132 /** initial state for validation */
134 /** find the proper keys for validation, follow trust chain */
136 /** validate the answer, using found key entry */
140 /** DLV lookup state, processing DLV queries */
145 * Per query state for the validator module.
149 * State of the validator module.
151 enum val_state state;
154 * The original message we have been given to validate.
156 struct dns_msg* orig_msg;
159 * The query restart count
162 /** The blacklist saved for chainoftrust elements */
163 struct sock_list* chain_blacklist;
166 * The query name we have chased to; qname after following CNAMEs
168 struct query_info qchase;
171 * The chased reply, extract from original message. Can be:
175 * plus authority, additional (nsecs) that have same signature.
177 struct reply_info* chase_reply;
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.
187 * The skip is also used for referral messages, where it will
188 * range from 0, over the answer, authority and additional sections.
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;
200 struct ub_packed_rrset_key* ds_rrset;
202 /** domain name for empty nonterminal detection */
203 uint8_t* empty_DS_name;
204 /** length of empty_DS_name */
207 /** the current key entry */
208 struct key_entry_key* key_entry;
211 enum val_classification subtype;
214 uint8_t* signer_name;
215 /** length of signer_name */
218 /** true if this state is waiting to prime a trust anchor */
221 /** have we already checked the DLV? */
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 */
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 */
244 * Get the validator function block.
245 * @return: function block with function pointers to validator methods.
247 struct module_func_block* val_get_funcblock(void);
250 * Get validator state as a string
251 * @param state: to convert
252 * @return constant string that is printable.
254 const char* val_state_to_string(enum val_state state);
256 /** validator init */
257 int val_init(struct module_env* env, int id);
259 /** validator deinit */
260 void val_deinit(struct module_env* env, int id);
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);
267 * inform validator super.
269 * @param qstate: query state that finished.
270 * @param id: module id.
271 * @param super: the qstate to inform.
273 void val_inform_super(struct module_qstate* qstate, int id,
274 struct module_qstate* super);
276 /** validator cleanup query state */
277 void val_clear(struct module_qstate* qstate, int id);
280 * Debug helper routine that assists worker in determining memory in
282 * @param env: module environment
283 * @param id: module id.
284 * @return memory in use in bytes.
286 size_t val_get_mem(struct module_env* env, int id);
288 #endif /* VALIDATOR_VALIDATOR_H */