2 * validator/val_utils.h - validator utility functions.
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 helper functions for the validator module.
42 #ifndef VALIDATOR_VAL_UTILS_H
43 #define VALIDATOR_VAL_UTILS_H
44 #include "util/data/packed_rrset.h"
45 #include "sldns/pkthdr.h"
51 struct ub_packed_rrset_key;
59 * Response classifications for the validator. The different types of proofs.
61 enum val_classification {
62 /** Not subtyped yet. */
63 VAL_CLASS_UNTYPED = 0,
64 /** Not a recognized subtype. */
66 /** A positive, direct, response */
68 /** A positive response, with a CNAME/DNAME chain. */
70 /** A NOERROR/NODATA response. */
72 /** A NXDOMAIN response. */
74 /** A CNAME/DNAME chain, and the offset is at the end of it,
75 * but there is no answer here, it can be NAMEERROR or NODATA. */
76 VAL_CLASS_CNAMENOANSWER,
77 /** A referral, from cache with a nonRD query. */
79 /** A response to a qtype=ANY query. */
84 * Given a response, classify ANSWER responses into a subtype.
85 * @param query_flags: query flags for the original query.
86 * @param origqinf: query info. The original query name.
87 * @param qinf: query info. The chased query name.
88 * @param rep: response. The original response.
89 * @param skip: offset into the original response answer section.
90 * @return A subtype, all values possible except UNTYPED .
91 * Once CNAME type is returned you can increase skip.
92 * Then, another CNAME type, CNAME_NOANSWER or POSITIVE are possible.
94 enum val_classification val_classify_response(uint16_t query_flags,
95 struct query_info* origqinf, struct query_info* qinf,
96 struct reply_info* rep, size_t skip);
99 * Given a response, determine the name of the "signer". This is primarily
100 * to determine if the response is, in fact, signed at all, and, if so, what
101 * is the name of the most pertinent keyset.
103 * @param subtype: the type from classify.
104 * @param qinf: query, the chased query name.
105 * @param rep: response to that, original response.
106 * @param cname_skip: how many answer rrsets have been skipped due to CNAME
107 * chains being chased around.
108 * @param signer_name: signer name, if the response is signed
109 * (even partially), or null if the response isn't signed.
110 * @param signer_len: length of signer_name of 0 if signer_name is NULL.
112 void val_find_signer(enum val_classification subtype,
113 struct query_info* qinf, struct reply_info* rep,
114 size_t cname_skip, uint8_t** signer_name, size_t* signer_len);
117 * Verify RRset with keys
118 * @param env: module environment (scratch buffer)
119 * @param ve: validator environment (verification settings)
120 * @param rrset: what to verify
121 * @param keys: dnskey rrset to verify with.
122 * @param sigalg: if nonNULL provide downgrade protection otherwise one
123 * algorithm is enough. Algo list is constructed in here.
124 * @param reason: reason of failure. Fixed string or alloced in scratch.
125 * @param section: section of packet where this rrset comes from.
126 * @param qstate: qstate with region.
127 * @return security status of verification.
129 enum sec_status val_verify_rrset(struct module_env* env, struct val_env* ve,
130 struct ub_packed_rrset_key* rrset, struct ub_packed_rrset_key* keys,
131 uint8_t* sigalg, char** reason, sldns_pkt_section section,
132 struct module_qstate* qstate);
135 * Verify RRset with keys from a keyset.
136 * @param env: module environment (scratch buffer)
137 * @param ve: validator environment (verification settings)
138 * @param rrset: what to verify
139 * @param kkey: key_entry to verify with.
140 * @param reason: reason of failure. Fixed string or alloced in scratch.
141 * @param section: section of packet where this rrset comes from.
142 * @param qstate: qstate with region.
143 * @return security status of verification.
145 enum sec_status val_verify_rrset_entry(struct module_env* env,
146 struct val_env* ve, struct ub_packed_rrset_key* rrset,
147 struct key_entry_key* kkey, char** reason, sldns_pkt_section section,
148 struct module_qstate* qstate);
151 * Verify DNSKEYs with DS rrset. Like val_verify_new_DNSKEYs but
152 * returns a sec_status instead of a key_entry.
153 * @param env: module environment (scratch buffer)
154 * @param ve: validator environment (verification settings)
155 * @param dnskey_rrset: DNSKEY rrset to verify
156 * @param ds_rrset: DS rrset to verify with.
157 * @param sigalg: if nonNULL provide downgrade protection otherwise one
158 * algorithm is enough. The list of signalled algorithms is returned,
159 * must have enough space for ALGO_NEEDS_MAX+1.
160 * @param reason: reason of failure. Fixed string or alloced in scratch.
161 * @param qstate: qstate with region.
162 * @return: sec_status_secure if a DS matches.
163 * sec_status_insecure if end of trust (i.e., unknown algorithms).
164 * sec_status_bogus if it fails.
166 enum sec_status val_verify_DNSKEY_with_DS(struct module_env* env,
167 struct val_env* ve, struct ub_packed_rrset_key* dnskey_rrset,
168 struct ub_packed_rrset_key* ds_rrset, uint8_t* sigalg, char** reason,
169 struct module_qstate* qstate);
172 * Verify DNSKEYs with DS and DNSKEY rrset. Like val_verify_DNSKEY_with_DS
173 * but for a trust anchor.
174 * @param env: module environment (scratch buffer)
175 * @param ve: validator environment (verification settings)
176 * @param dnskey_rrset: DNSKEY rrset to verify
177 * @param ta_ds: DS rrset to verify with.
178 * @param ta_dnskey: DNSKEY rrset to verify with.
179 * @param sigalg: if nonNULL provide downgrade protection otherwise one
180 * algorithm is enough. The list of signalled algorithms is returned,
181 * must have enough space for ALGO_NEEDS_MAX+1.
182 * @param reason: reason of failure. Fixed string or alloced in scratch.
183 * @param qstate: qstate with region.
184 * @return: sec_status_secure if a DS matches.
185 * sec_status_insecure if end of trust (i.e., unknown algorithms).
186 * sec_status_bogus if it fails.
188 enum sec_status val_verify_DNSKEY_with_TA(struct module_env* env,
189 struct val_env* ve, struct ub_packed_rrset_key* dnskey_rrset,
190 struct ub_packed_rrset_key* ta_ds,
191 struct ub_packed_rrset_key* ta_dnskey, uint8_t* sigalg, char** reason,
192 struct module_qstate* qstate);
195 * Verify new DNSKEYs with DS rrset. The DS contains hash values that should
196 * match the DNSKEY keys.
197 * match the DS to a DNSKEY and verify the DNSKEY rrset with that key.
199 * @param region: where to allocate key entry result.
200 * @param env: module environment (scratch buffer)
201 * @param ve: validator environment (verification settings)
202 * @param dnskey_rrset: DNSKEY rrset to verify
203 * @param ds_rrset: DS rrset to verify with.
204 * @param downprot: if true provide downgrade protection otherwise one
205 * algorithm is enough.
206 * @param reason: reason of failure. Fixed string or alloced in scratch.
207 * @param qstate: qstate with region.
208 * @return a KeyEntry. This will either contain the now trusted
209 * dnskey_rrset, a "null" key entry indicating that this DS
210 * rrset/DNSKEY pair indicate an secure end to the island of trust
211 * (i.e., unknown algorithms), or a "bad" KeyEntry if the dnskey
212 * rrset fails to verify. Note that the "null" response should
213 * generally only occur in a private algorithm scenario: normally
214 * this sort of thing is checked before fetching the matching DNSKEY
216 * if downprot is set, a key entry with an algo list is made.
218 struct key_entry_key* val_verify_new_DNSKEYs(struct regional* region,
219 struct module_env* env, struct val_env* ve,
220 struct ub_packed_rrset_key* dnskey_rrset,
221 struct ub_packed_rrset_key* ds_rrset, int downprot, char** reason,
222 struct module_qstate* qstate);
226 * Verify rrset with trust anchor: DS and DNSKEY rrset.
228 * @param region: where to allocate key entry result.
229 * @param env: module environment (scratch buffer)
230 * @param ve: validator environment (verification settings)
231 * @param dnskey_rrset: DNSKEY rrset to verify
232 * @param ta_ds_rrset: DS rrset to verify with.
233 * @param ta_dnskey_rrset: the DNSKEY rrset to verify with.
234 * @param downprot: if true provide downgrade protection otherwise one
235 * algorithm is enough.
236 * @param reason: reason of failure. Fixed string or alloced in scratch.
237 * @param qstate: qstate with region.
238 * @return a KeyEntry. This will either contain the now trusted
239 * dnskey_rrset, a "null" key entry indicating that this DS
240 * rrset/DNSKEY pair indicate an secure end to the island of trust
241 * (i.e., unknown algorithms), or a "bad" KeyEntry if the dnskey
242 * rrset fails to verify. Note that the "null" response should
243 * generally only occur in a private algorithm scenario: normally
244 * this sort of thing is checked before fetching the matching DNSKEY
246 * if downprot is set, a key entry with an algo list is made.
248 struct key_entry_key* val_verify_new_DNSKEYs_with_ta(struct regional* region,
249 struct module_env* env, struct val_env* ve,
250 struct ub_packed_rrset_key* dnskey_rrset,
251 struct ub_packed_rrset_key* ta_ds_rrset,
252 struct ub_packed_rrset_key* ta_dnskey_rrset,
253 int downprot, char** reason, struct module_qstate* qstate);
256 * Determine if DS rrset is usable for validator or not.
257 * Returns true if the algorithms for key and DShash are supported,
258 * for at least one RR.
260 * @param ds_rrset: the newly received DS rrset.
261 * @return true or false if not usable.
263 int val_dsset_isusable(struct ub_packed_rrset_key* ds_rrset);
266 * Determine by looking at a signed RRset whether or not the RRset name was
267 * the result of a wildcard expansion. If so, return the name of the
268 * generating wildcard.
270 * @param rrset The rrset to check.
271 * @param wc: the wildcard name, if the rrset was synthesized from a wildcard.
272 * unchanged if not. The wildcard name, without "*." in front, is
273 * returned. This is a pointer into the rrset owner name.
274 * @param wc_len: the length of the returned wildcard name.
275 * @return false if the signatures are inconsistent in indicating the
276 * wildcard status; possible spoofing of wildcard response for other
277 * responses is being tried. We lost the status which rrsig was verified
278 * after the verification routine finished, so we simply check if
279 * the signatures are consistent; inserting a fake signature is a denial
280 * of service; but in that you could also have removed the real
283 int val_rrset_wildcard(struct ub_packed_rrset_key* rrset, uint8_t** wc,
287 * Chase the cname to the next query name.
288 * @param qchase: the current query name, updated to next target.
289 * @param rep: original message reply to look at CNAMEs.
290 * @param cname_skip: the skip into the answer section. Updated to skip
291 * DNAME and CNAME to the next part of the answer.
292 * @return false on error (bad rdata).
294 int val_chase_cname(struct query_info* qchase, struct reply_info* rep,
298 * Fill up the chased reply with the content from the original reply;
299 * as pointers to those rrsets. Select the part after the cname_skip into
300 * the answer section, NS and AR sections that are signed with same signer.
302 * @param chase: chased reply, filled up.
303 * @param orig: original reply.
304 * @param cname_skip: which part of the answer section to skip.
305 * The skipped part contains CNAME(and DNAME)s that have been chased.
306 * @param name: the signer name to look for.
307 * @param len: length of name.
308 * @param signer: signer name or NULL if an unsigned RRset is considered.
309 * If NULL, rrsets with the lookup name are copied over.
311 void val_fill_reply(struct reply_info* chase, struct reply_info* orig,
312 size_t cname_skip, uint8_t* name, size_t len, uint8_t* signer);
315 * Remove rrset with index from reply, from the authority section.
316 * @param rep: reply to remove it from.
317 * @param index: rrset to remove, must be in the authority section.
319 void val_reply_remove_auth(struct reply_info* rep, size_t index);
322 * Remove all unsigned or non-secure status rrsets from NS and AR sections.
323 * So that unsigned data does not get let through to clients, when we have
324 * found the data to be secure.
326 * @param env: environment with cleaning options.
327 * @param rep: reply to dump all nonsecure stuff out of.
329 void val_check_nonsecure(struct module_env* env, struct reply_info* rep);
332 * Mark all unchecked rrset entries not below a trust anchor as indeterminate.
333 * Only security==unchecked rrsets are updated.
334 * @param rep: the reply with rrsets.
335 * @param anchors: the trust anchors.
336 * @param r: rrset cache to store updated security status into.
337 * @param env: module environment
339 void val_mark_indeterminate(struct reply_info* rep,
340 struct val_anchors* anchors, struct rrset_cache* r,
341 struct module_env* env);
344 * Mark all unchecked rrset entries below a NULL key entry as insecure.
345 * Only security==unchecked rrsets are updated.
346 * @param rep: the reply with rrsets.
347 * @param kname: end of secure space name.
348 * @param r: rrset cache to store updated security status into.
349 * @param env: module environment
351 void val_mark_insecure(struct reply_info* rep, uint8_t* kname,
352 struct rrset_cache* r, struct module_env* env);
355 * Find next unchecked rrset position, return it for skip.
356 * @param rep: the original reply to look into.
357 * @param skip: the skip now.
358 * @return new skip, which may be at the rep->rrset_count position to signal
359 * there are no unchecked items.
361 size_t val_next_unchecked(struct reply_info* rep, size_t skip);
364 * Find the signer name for an RRset.
365 * @param rrset: the rrset.
366 * @param sname: signer name is returned or NULL if not signed.
367 * @param slen: length of sname (or 0).
369 void val_find_rrset_signer(struct ub_packed_rrset_key* rrset, uint8_t** sname,
373 * Get string to denote the classification result.
374 * @param subtype: from classification function.
375 * @return static string to describe the classification.
377 const char* val_classification_to_string(enum val_classification subtype);
380 * Add existing list to blacklist.
381 * @param blacklist: the blacklist with result
382 * @param region: the region where blacklist is allocated.
383 * Allocation failures are logged.
384 * @param origin: origin list to add, if NULL, a cache-entry is added to
385 * the blacklist to stop cache from being used.
386 * @param cross: if true this is a cross-qstate copy, and the 'origin'
387 * list is not allocated in the same region as the blacklist.
389 void val_blacklist(struct sock_list** blacklist, struct regional* region,
390 struct sock_list* origin, int cross);
393 * check if has dnssec info, and if it has signed nsecs. gives error reason.
394 * @param rep: reply to check.
395 * @param reason: returned on fail.
396 * @return false if message has no signed nsecs. Can not prove negatives.
398 int val_has_signed_nsecs(struct reply_info* rep, char** reason);
401 * Return algo number for favorite (best) algorithm that we support in DS.
402 * @param ds_rrset: the DSes in this rrset are inspected and best algo chosen.
403 * @return algo number or 0 if none supported. 0 is unused as algo number.
405 int val_favorite_ds_algo(struct ub_packed_rrset_key* ds_rrset);
408 * Find DS denial message in cache. Saves new qstate allocation and allows
409 * the validator to use partial content which is not enough to construct a
410 * message for network (or user) consumption. Without SOA for example,
411 * which is a common occurrence in the unbound code since the referrals contain
412 * NSEC/NSEC3 rrs without the SOA element, thus do not allow synthesis of a
413 * full negative reply, but do allow synthesis of sufficient proof.
414 * @param env: query env with caches and time.
415 * @param nm: name of DS record sought.
416 * @param nmlen: length of name.
417 * @param c: class of DS RR.
418 * @param region: where to allocate result.
419 * @param topname: name of the key that is currently in use, that will get
420 * used to validate the result, and thus no higher entries from the
421 * negative cache need to be examined.
422 * @return a dns_msg on success. NULL on failure.
424 struct dns_msg* val_find_DS(struct module_env* env, uint8_t* nm, size_t nmlen,
425 uint16_t c, struct regional* region, uint8_t* topname);
427 #endif /* VALIDATOR_VAL_UTILS_H */