3 #ifndef LDNS_DNSSEC_VERIFY_H
4 #define LDNS_DNSSEC_VERIFY_H
6 #define LDNS_DNSSEC_TRUST_TREE_MAX_PARENTS 10
8 #include <ldns/dnssec.h>
15 * Chain structure that contains all DNSSEC data needed to
18 typedef struct ldns_dnssec_data_chain_struct ldns_dnssec_data_chain;
19 struct ldns_dnssec_data_chain_struct
22 ldns_rr_list *signatures;
23 ldns_rr_type parent_type;
24 ldns_dnssec_data_chain *parent;
25 ldns_pkt_rcode packet_rcode;
26 ldns_rr_type packet_qtype;
31 * Creates a new dnssec_chain structure
32 * \return ldns_dnssec_data_chain *
34 ldns_dnssec_data_chain *ldns_dnssec_data_chain_new();
37 * Frees a dnssec_data_chain structure
39 * \param[in] *chain The chain to free
41 void ldns_dnssec_data_chain_free(ldns_dnssec_data_chain *chain);
44 * Frees a dnssec_data_chain structure, and all data
47 * \param[in] *chain The dnssec_data_chain to free
49 void ldns_dnssec_data_chain_deep_free(ldns_dnssec_data_chain *chain);
52 * Prints the dnssec_data_chain to the given file stream
54 * \param[in] *out The file stream to print to
55 * \param[in] *chain The dnssec_data_chain to print
57 void ldns_dnssec_data_chain_print(FILE *out, const ldns_dnssec_data_chain *chain);
60 * Build an ldns_dnssec_data_chain, which contains all
61 * DNSSEC data that is needed to derive the trust tree later
63 * The data_set will be cloned
65 * \param[in] *res resolver structure for further needed queries
66 * \param[in] qflags resolution flags
67 * \param[in] *data_set The original rrset where the chain ends
68 * \param[in] *pkt optional, can contain the original packet
69 * (and hence the sigs and maybe the key)
70 * \param[in] *orig_rr The original Resource Record
72 * \return the DNSSEC data chain
74 ldns_dnssec_data_chain *ldns_dnssec_build_data_chain(ldns_resolver *res,
75 const uint16_t qflags,
76 const ldns_rr_list *data_set,
81 * Tree structure that contains the relation of DNSSEC data,
82 * and their cryptographic status.
84 * This tree is derived from a data_chain, and can be used
85 * to look whether there is a connection between an RRSET
86 * and a trusted key. The tree only contains pointers to the
87 * data_chain, and therefore one should *never* free() the
88 * data_chain when there is still a trust tree derived from
104 * For each signature there is a parent; if the parent
105 * pointer is null, it couldn't be found and there was no
106 * denial; otherwise is a tree which contains either a
107 * DNSKEY, a DS, or a NSEC rr
109 typedef struct ldns_dnssec_trust_tree_struct ldns_dnssec_trust_tree;
110 struct ldns_dnssec_trust_tree_struct
113 /* the complete rrset this rr was in */
115 ldns_dnssec_trust_tree *parents[LDNS_DNSSEC_TRUST_TREE_MAX_PARENTS];
116 ldns_status parent_status[LDNS_DNSSEC_TRUST_TREE_MAX_PARENTS];
117 /** for debugging, add signatures too (you might want
118 those if they contain errors) */
119 ldns_rr *parent_signature[LDNS_DNSSEC_TRUST_TREE_MAX_PARENTS];
124 * Creates a new (empty) dnssec_trust_tree structure
126 * \return ldns_dnssec_trust_tree *
128 ldns_dnssec_trust_tree *ldns_dnssec_trust_tree_new();
131 * Frees the dnssec_trust_tree recursively
133 * There is no deep free; all data in the trust tree
134 * consists of pointers to a data_chain
136 * \param[in] tree The tree to free
138 void ldns_dnssec_trust_tree_free(ldns_dnssec_trust_tree *tree);
141 * returns the depth of the trust tree
143 * \param[in] tree tree to calculate the depth of
144 * \return The depth of the tree
146 size_t ldns_dnssec_trust_tree_depth(ldns_dnssec_trust_tree *tree);
149 * Prints the dnssec_trust_tree structure to the given file
152 * If a link status is not LDNS_STATUS_OK; the status and
153 * relevant signatures are printed too
155 * \param[in] *out The file stream to print to
156 * \param[in] tree The trust tree to print
157 * \param[in] tabs Prepend each line with tabs*2 spaces
158 * \param[in] extended If true, add little explanation lines to the output
160 void ldns_dnssec_trust_tree_print(FILE *out,
161 ldns_dnssec_trust_tree *tree,
166 * Adds a trust tree as a parent for the given trust tree
168 * \param[in] *tree The tree to add the parent to
169 * \param[in] *parent The parent tree to add
170 * \param[in] *parent_signature The RRSIG relevant to this parent/child
172 * \param[in] parent_status The DNSSEC status for this parent, child and RRSIG
173 * \return LDNS_STATUS_OK if the addition succeeds, error otherwise
175 ldns_status ldns_dnssec_trust_tree_add_parent(ldns_dnssec_trust_tree *tree,
176 const ldns_dnssec_trust_tree *parent,
177 const ldns_rr *parent_signature,
178 const ldns_status parent_status);
181 * Generates a dnssec_trust_ttree for the given rr from the
184 * This does not clone the actual data; Don't free the
185 * data_chain before you are done with this tree
187 * \param[in] *data_chain The chain to derive the trust tree from
188 * \param[in] *rr The RR this tree will be about
189 * \return ldns_dnssec_trust_tree *
191 ldns_dnssec_trust_tree *ldns_dnssec_derive_trust_tree(
192 ldns_dnssec_data_chain *data_chain,
196 * Sub function for derive_trust_tree that is used for a
199 * \param[in] new_tree The trust tree that we are building
200 * \param[in] data_chain The data chain containing the data for the trust tree
201 * \param[in] cur_sig_rr The currently relevant signature
203 void ldns_dnssec_derive_trust_tree_normal_rrset(
204 ldns_dnssec_trust_tree *new_tree,
205 ldns_dnssec_data_chain *data_chain,
206 ldns_rr *cur_sig_rr);
209 * Sub function for derive_trust_tree that is used for DNSKEY rrsets
211 * \param[in] new_tree The trust tree that we are building
212 * \param[in] data_chain The data chain containing the data for the trust tree
213 * \param[in] cur_rr The currently relevant DNSKEY RR
214 * \param[in] cur_sig_rr The currently relevant signature
216 void ldns_dnssec_derive_trust_tree_dnskey_rrset(
217 ldns_dnssec_trust_tree *new_tree,
218 ldns_dnssec_data_chain *data_chain,
220 ldns_rr *cur_sig_rr);
223 * Sub function for derive_trust_tree that is used for DS rrsets
225 * \param[in] new_tree The trust tree that we are building
226 * \param[in] data_chain The data chain containing the data for the trust tree
227 * \param[in] cur_rr The currently relevant DS RR
229 void ldns_dnssec_derive_trust_tree_ds_rrset(
230 ldns_dnssec_trust_tree *new_tree,
231 ldns_dnssec_data_chain *data_chain,
235 * Sub function for derive_trust_tree that is used when there are no
238 * \param[in] new_tree The trust tree that we are building
239 * \param[in] data_chain The data chain containing the data for the trust tree
241 void ldns_dnssec_derive_trust_tree_no_sig(
242 ldns_dnssec_trust_tree *new_tree,
243 ldns_dnssec_data_chain *data_chain);
246 * Returns OK if there is a trusted path in the tree to one of
247 * the DNSKEY or DS RRs in the given list
249 * \param *tree The trust tree so search
250 * \param *keys A ldns_rr_list of DNSKEY and DS rrs to look for
251 * \return LDNS_STATUS_OK if there is a trusted path to one of
252 * the keys, or the *first* error encountered
253 * if there were no paths
255 ldns_status ldns_dnssec_trust_tree_contains_keys(
256 ldns_dnssec_trust_tree *tree,
260 * Verifies a list of signatures for one rrset.
262 * \param[in] rrset the rrset to verify
263 * \param[in] rrsig a list of signatures to check
264 * \param[in] keys a list of keys to check with
265 * \param[out] good_keys if this is a (initialized) list, the pointer to keys
266 * from keys that validate one of the signatures
268 * \return status LDNS_STATUS_OK if there is at least one correct key
270 ldns_status ldns_verify(ldns_rr_list *rrset,
272 const ldns_rr_list *keys,
273 ldns_rr_list *good_keys);
276 * Verifies a list of signatures for one rrset, but disregard the time.
277 * Inception and Expiration are not checked.
279 * \param[in] rrset the rrset to verify
280 * \param[in] rrsig a list of signatures to check
281 * \param[in] keys a list of keys to check with
282 * \param[out] good_keys if this is a (initialized) list, the pointer to keys
283 * from keys that validate one of the signatures
285 * \return status LDNS_STATUS_OK if there is at least one correct key
287 ldns_status ldns_verify_notime(ldns_rr_list *rrset,
289 const ldns_rr_list *keys,
290 ldns_rr_list *good_keys);
293 * Tries to build an authentication chain from the given
294 * keys down to the queried domain.
296 * If we find a valid trust path, return the valid keys for the domain.
298 * \param[in] res the current resolver
299 * \param[in] domain the domain we want valid keys for
300 * \param[in] keys the current set of trusted keys
301 * \param[out] status pointer to the status variable where the result
302 * code will be stored
303 * \return the set of trusted keys for the domain, or NULL if no
304 * trust path could be built.
306 ldns_rr_list *ldns_fetch_valid_domain_keys(const ldns_resolver * res,
307 const ldns_rdf * domain,
308 const ldns_rr_list * keys,
309 ldns_status *status);
312 * Validates the DNSKEY RRset for the given domain using the provided
315 * \param[in] res the current resolver
316 * \param[in] domain the domain we want valid keys for
317 * \param[in] keys the current set of trusted keys
318 * \return the set of trusted keys for the domain, or NULL if the RRSET
319 * could not be validated
321 ldns_rr_list *ldns_validate_domain_dnskey (const ldns_resolver *res,
322 const ldns_rdf *domain,
323 const ldns_rr_list *keys);
326 * Validates the DS RRset for the given domain using the provided trusted keys.
328 * \param[in] res the current resolver
329 * \param[in] domain the domain we want valid keys for
330 * \param[in] keys the current set of trusted keys
331 * \return the set of trusted keys for the domain, or NULL if the RRSET could not be validated
333 ldns_rr_list *ldns_validate_domain_ds(const ldns_resolver *res,
336 const ldns_rr_list * keys);
339 * Verifies a list of signatures for one RRset using a valid trust path.
341 * \param[in] res the current resolver
342 * \param[in] rrset the rrset to verify
343 * \param[in] rrsigs a list of signatures to check
344 * \param[out] validating_keys if this is a (initialized) list, the
345 * keys from keys that validate one of
346 * the signatures are added to it
347 * \return status LDNS_STATUS_OK if there is at least one correct key
349 ldns_status ldns_verify_trusted(ldns_resolver *res,
351 ldns_rr_list *rrsigs,
352 ldns_rr_list *validating_keys);
355 * denial is not just a river in egypt
357 * \param[in] rr The (query) RR to check the denial of existence for
358 * \param[in] nsecs The list of NSEC RRs that are supposed to deny the
359 * existence of the RR
360 * \param[in] rrsigs The RRSIG RR covering the NSEC RRs
361 * \return LDNS_STATUS_OK if the NSEC RRs deny the existence, error code
362 * containing the reason they do not otherwise
364 ldns_status ldns_dnssec_verify_denial(ldns_rr *rr,
366 ldns_rr_list *rrsigs);
369 * Denial of existence using NSEC3 records
370 * Since NSEC3 is a bit more complicated than normal denial, some
371 * context arguments are needed
373 * \param[in] rr The (query) RR to check the denial of existence for
374 * \param[in] nsecs The list of NSEC3 RRs that are supposed to deny the
375 * existence of the RR
376 * \param[in] rrsigs The RRSIG rr covering the NSEC RRs
377 * \param[in] packet_rcode The RCODE value of the packet that provided the
379 * \param[in] packet_qtype The original query RR type
380 * \param[in] packet_nodata True if the providing packet had an empty ANSWER
382 * \return LDNS_STATUS_OK if the NSEC3 RRs deny the existence, error code
383 * containing the reason they do not otherwise
385 ldns_status ldns_dnssec_verify_denial_nsec3(ldns_rr *rr,
387 ldns_rr_list *rrsigs,
388 ldns_pkt_rcode packet_rcode,
389 ldns_rr_type packet_qtype,
393 * Verifies the already processed data in the buffers
394 * This function should probably not be used directly.
396 * \param[in] rawsig_buf Buffer containing signature data to use
397 * \param[in] verify_buf Buffer containing data to verify
398 * \param[in] key_buf Buffer containing key data to use
399 * \param[in] algo Signing algorithm
400 * \return status LDNS_STATUS_OK if the data verifies. Error if not.
402 ldns_status ldns_verify_rrsig_buffers(ldns_buffer *rawsig_buf,
403 ldns_buffer *verify_buf,
404 ldns_buffer *key_buf,
408 * Like ldns_verify_rrsig_buffers, but uses raw data.
410 * \param[in] sig signature data to use
411 * \param[in] siglen length of signature data to use
412 * \param[in] verify_buf Buffer containing data to verify
413 * \param[in] key key data to use
414 * \param[in] keylen length of key data to use
415 * \param[in] algo Signing algorithm
416 * \return status LDNS_STATUS_OK if the data verifies. Error if not.
418 ldns_status ldns_verify_rrsig_buffers_raw(unsigned char* sig,
420 ldns_buffer *verify_buf,
426 * Verifies an rrsig. All keys in the keyset are tried.
427 * \param[in] rrset the rrset to check
428 * \param[in] rrsig the signature of the rrset
429 * \param[in] keys the keys to try
430 * \param[out] good_keys if this is a (initialized) list, the pointer to keys
431 * from keys that validate one of the signatures
433 * \return a list of keys which validate the rrsig + rrset. Returns
434 * status LDNS_STATUS_OK if at least one key matched. Else an error.
436 ldns_status ldns_verify_rrsig_keylist(ldns_rr_list *rrset,
438 const ldns_rr_list *keys,
439 ldns_rr_list *good_keys);
442 * Verifies an rrsig. All keys in the keyset are tried. Time is not checked.
443 * \param[in] rrset the rrset to check
444 * \param[in] rrsig the signature of the rrset
445 * \param[in] keys the keys to try
446 * \param[out] good_keys if this is a (initialized) list, the pointer to keys
447 * from keys that validate one of the signatures
449 * \return a list of keys which validate the rrsig + rrset. Returns
450 * status LDNS_STATUS_OK if at least one key matched. Else an error.
452 ldns_status ldns_verify_rrsig_keylist_notime(ldns_rr_list *rrset,
454 const ldns_rr_list *keys,
455 ldns_rr_list *good_keys);
458 * verify an rrsig with 1 key
459 * \param[in] rrset the rrset
460 * \param[in] rrsig the rrsig to verify
461 * \param[in] key the key to use
462 * \return status message wether verification succeeded.
464 ldns_status ldns_verify_rrsig(ldns_rr_list *rrset,
469 * verifies a buffer with signature data for a buffer with rrset data
472 * \param[in] sig the signature data
473 * \param[in] rrset the rrset data, sorted and processed for verification
474 * \param[in] key the EVP key structure
475 * \param[in] digest_type The digest type of the signature
478 ldns_status ldns_verify_rrsig_evp(ldns_buffer *sig,
481 const EVP_MD *digest_type);
485 * Like ldns_verify_rrsig_evp, but uses raw signature data.
486 * \param[in] sig the signature data, wireformat uncompressed
487 * \param[in] siglen length of the signature data
488 * \param[in] rrset the rrset data, sorted and processed for verification
489 * \param[in] key the EVP key structure
490 * \param[in] digest_type The digest type of the signature
493 ldns_status ldns_verify_rrsig_evp_raw(unsigned char *sig,
497 const EVP_MD *digest_type);
501 * verifies a buffer with signature data (DSA) for a buffer with rrset data
502 * with a buffer with key data.
504 * \param[in] sig the signature data
505 * \param[in] rrset the rrset data, sorted and processed for verification
506 * \param[in] key the key data
508 ldns_status ldns_verify_rrsig_dsa(ldns_buffer *sig,
513 * verifies a buffer with signature data (RSASHA1) for a buffer with rrset data
514 * with a buffer with key data.
516 * \param[in] sig the signature data
517 * \param[in] rrset the rrset data, sorted and processed for verification
518 * \param[in] key the key data
520 ldns_status ldns_verify_rrsig_rsasha1(ldns_buffer *sig,
525 * verifies a buffer with signature data (RSAMD5) for a buffer with rrset data
526 * with a buffer with key data.
528 * \param[in] sig the signature data
529 * \param[in] rrset the rrset data, sorted and processed for verification
530 * \param[in] key the key data
532 ldns_status ldns_verify_rrsig_rsamd5(ldns_buffer *sig,
537 * Like ldns_verify_rrsig_dsa, but uses raw signature and key data.
538 * \param[in] sig raw uncompressed wireformat signature data
539 * \param[in] siglen length of signature data
540 * \param[in] rrset ldns buffer with prepared rrset data.
541 * \param[in] key raw uncompressed wireformat key data
542 * \param[in] keylen length of key data
544 ldns_status ldns_verify_rrsig_dsa_raw(unsigned char* sig,
551 * Like ldns_verify_rrsig_rsasha1, but uses raw signature and key data.
552 * \param[in] sig raw uncompressed wireformat signature data
553 * \param[in] siglen length of signature data
554 * \param[in] rrset ldns buffer with prepared rrset data.
555 * \param[in] key raw uncompressed wireformat key data
556 * \param[in] keylen length of key data
558 ldns_status ldns_verify_rrsig_rsasha1_raw(unsigned char* sig,
565 * Like ldns_verify_rrsig_rsasha256, but uses raw signature and key data.
566 * \param[in] sig raw uncompressed wireformat signature data
567 * \param[in] siglen length of signature data
568 * \param[in] rrset ldns buffer with prepared rrset data.
569 * \param[in] key raw uncompressed wireformat key data
570 * \param[in] keylen length of key data
573 ldns_status ldns_verify_rrsig_rsasha256_raw(unsigned char* sig,
580 * Like ldns_verify_rrsig_rsasha512, but uses raw signature and key data.
581 * \param[in] sig raw uncompressed wireformat signature data
582 * \param[in] siglen length of signature data
583 * \param[in] rrset ldns buffer with prepared rrset data.
584 * \param[in] key raw uncompressed wireformat key data
585 * \param[in] keylen length of key data
587 ldns_status ldns_verify_rrsig_rsasha512_raw(unsigned char* sig,
594 * Like ldns_verify_rrsig_rsamd5, but uses raw signature and key data.
595 * \param[in] sig raw uncompressed wireformat signature data
596 * \param[in] siglen length of signature data
597 * \param[in] rrset ldns buffer with prepared rrset data.
598 * \param[in] key raw uncompressed wireformat key data
599 * \param[in] keylen length of key data
601 ldns_status ldns_verify_rrsig_rsamd5_raw(unsigned char* sig,