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>
11 * Chain structure that contains all DNSSEC data needed to
14 typedef struct ldns_dnssec_data_chain_struct ldns_dnssec_data_chain;
15 struct ldns_dnssec_data_chain_struct
18 ldns_rr_list *signatures;
19 ldns_rr_type parent_type;
20 ldns_dnssec_data_chain *parent;
21 ldns_pkt_rcode packet_rcode;
22 ldns_rr_type packet_qtype;
27 * Creates a new dnssec_chain structure
28 * \return ldns_dnssec_data_chain *
30 ldns_dnssec_data_chain *ldns_dnssec_data_chain_new();
33 * Frees a dnssec_data_chain structure
35 * \param[in] *chain The chain to free
37 void ldns_dnssec_data_chain_free(ldns_dnssec_data_chain *chain);
40 * Frees a dnssec_data_chain structure, and all data
43 * \param[in] *chain The dnssec_data_chain to free
45 void ldns_dnssec_data_chain_deep_free(ldns_dnssec_data_chain *chain);
48 * Prints the dnssec_data_chain to the given file stream
50 * \param[in] *out The file stream to print to
51 * \param[in] *chain The dnssec_data_chain to print
53 void ldns_dnssec_data_chain_print(FILE *out, const ldns_dnssec_data_chain *chain);
56 * Build an ldns_dnssec_data_chain, which contains all
57 * DNSSEC data that is needed to derive the trust tree later
59 * The data_set will be cloned
61 * \param[in] *res resolver structure for further needed queries
62 * \param[in] qflags resolution flags
63 * \param[in] *data_set The original rrset where the chain ends
64 * \param[in] *pkt optional, can contain the original packet
65 * (and hence the sigs and maybe the key)
66 * \param[in] *orig_rr The original Resource Record
68 * \return the DNSSEC data chain
70 ldns_dnssec_data_chain *ldns_dnssec_build_data_chain(ldns_resolver *res,
71 const uint16_t qflags,
72 const ldns_rr_list *data_set,
77 * Tree structure that contains the relation of DNSSEC data,
78 * and their cryptographic status.
80 * This tree is derived from a data_chain, and can be used
81 * to look whether there is a connection between an RRSET
82 * and a trusted key. The tree only contains pointers to the
83 * data_chain, and therefore one should *never* free() the
84 * data_chain when there is still a trust tree derived from
100 * For each signature there is a parent; if the parent
101 * pointer is null, it couldn't be found and there was no
102 * denial; otherwise is a tree which contains either a
103 * DNSKEY, a DS, or a NSEC rr
105 typedef struct ldns_dnssec_trust_tree_struct ldns_dnssec_trust_tree;
106 struct ldns_dnssec_trust_tree_struct
109 /* the complete rrset this rr was in */
111 ldns_dnssec_trust_tree *parents[LDNS_DNSSEC_TRUST_TREE_MAX_PARENTS];
112 ldns_status parent_status[LDNS_DNSSEC_TRUST_TREE_MAX_PARENTS];
113 /** for debugging, add signatures too (you might want
114 those if they contain errors) */
115 ldns_rr *parent_signature[LDNS_DNSSEC_TRUST_TREE_MAX_PARENTS];
120 * Creates a new (empty) dnssec_trust_tree structure
122 * \return ldns_dnssec_trust_tree *
124 ldns_dnssec_trust_tree *ldns_dnssec_trust_tree_new();
127 * Frees the dnssec_trust_tree recursively
129 * There is no deep free; all data in the trust tree
130 * consists of pointers to a data_chain
132 * \param[in] tree The tree to free
134 void ldns_dnssec_trust_tree_free(ldns_dnssec_trust_tree *tree);
137 * returns the depth of the trust tree
139 * \param[in] tree tree to calculate the depth of
140 * \return The depth of the tree
142 size_t ldns_dnssec_trust_tree_depth(ldns_dnssec_trust_tree *tree);
145 * Prints the dnssec_trust_tree structure to the given file
148 * If a link status is not LDNS_STATUS_OK; the status and
149 * relevant signatures are printed too
151 * \param[in] *out The file stream to print to
152 * \param[in] tree The trust tree to print
153 * \param[in] tabs Prepend each line with tabs*2 spaces
154 * \param[in] extended If true, add little explanation lines to the output
156 void ldns_dnssec_trust_tree_print(FILE *out,
157 ldns_dnssec_trust_tree *tree,
162 * Adds a trust tree as a parent for the given trust tree
164 * \param[in] *tree The tree to add the parent to
165 * \param[in] *parent The parent tree to add
166 * \param[in] *parent_signature The RRSIG relevant to this parent/child
168 * \param[in] parent_status The DNSSEC status for this parent, child and RRSIG
169 * \return LDNS_STATUS_OK if the addition succeeds, error otherwise
171 ldns_status ldns_dnssec_trust_tree_add_parent(ldns_dnssec_trust_tree *tree,
172 const ldns_dnssec_trust_tree *parent,
173 const ldns_rr *parent_signature,
174 const ldns_status parent_status);
177 * Generates a dnssec_trust_ttree for the given rr from the
180 * This does not clone the actual data; Don't free the
181 * data_chain before you are done with this tree
183 * \param[in] *data_chain The chain to derive the trust tree from
184 * \param[in] *rr The RR this tree will be about
185 * \return ldns_dnssec_trust_tree *
187 ldns_dnssec_trust_tree *ldns_dnssec_derive_trust_tree(
188 ldns_dnssec_data_chain *data_chain,
192 * Sub function for derive_trust_tree that is used for a
195 * \param[in] new_tree The trust tree that we are building
196 * \param[in] data_chain The data chain containing the data for the trust tree
197 * \param[in] cur_sig_rr The currently relevant signature
199 void ldns_dnssec_derive_trust_tree_normal_rrset(
200 ldns_dnssec_trust_tree *new_tree,
201 ldns_dnssec_data_chain *data_chain,
202 ldns_rr *cur_sig_rr);
205 * Sub function for derive_trust_tree that is used for DNSKEY rrsets
207 * \param[in] new_tree The trust tree that we are building
208 * \param[in] data_chain The data chain containing the data for the trust tree
209 * \param[in] cur_rr The currently relevant DNSKEY RR
210 * \param[in] cur_sig_rr The currently relevant signature
212 void ldns_dnssec_derive_trust_tree_dnskey_rrset(
213 ldns_dnssec_trust_tree *new_tree,
214 ldns_dnssec_data_chain *data_chain,
216 ldns_rr *cur_sig_rr);
219 * Sub function for derive_trust_tree that is used for DS rrsets
221 * \param[in] new_tree The trust tree that we are building
222 * \param[in] data_chain The data chain containing the data for the trust tree
223 * \param[in] cur_rr The currently relevant DS RR
225 void ldns_dnssec_derive_trust_tree_ds_rrset(
226 ldns_dnssec_trust_tree *new_tree,
227 ldns_dnssec_data_chain *data_chain,
231 * Sub function for derive_trust_tree that is used when there are no
234 * \param[in] new_tree The trust tree that we are building
235 * \param[in] data_chain The data chain containing the data for the trust tree
237 void ldns_dnssec_derive_trust_tree_no_sig(
238 ldns_dnssec_trust_tree *new_tree,
239 ldns_dnssec_data_chain *data_chain);
242 * Returns OK if there is a trusted path in the tree to one of
243 * the DNSKEY or DS RRs in the given list
245 * \param *tree The trust tree so search
246 * \param *keys A ldns_rr_list of DNSKEY and DS rrs to look for
247 * \return LDNS_STATUS_OK if there is a trusted path to one of
248 * the keys, or the *first* error encountered
249 * if there were no paths
251 ldns_status ldns_dnssec_trust_tree_contains_keys(
252 ldns_dnssec_trust_tree *tree,
256 * Verifies a list of signatures for one rrset.
258 * \param[in] rrset the rrset to verify
259 * \param[in] rrsig a list of signatures to check
260 * \param[in] keys a list of keys to check with
261 * \param[out] good_keys if this is a (initialized) list, the keys
262 * from keys that validate one of the signatures
264 * \return status LDNS_STATUS_OK if there is at least one correct key
266 ldns_status ldns_verify(ldns_rr_list *rrset,
268 const ldns_rr_list *keys,
269 ldns_rr_list *good_keys);
272 * Verifies a list of signatures for one rrset, but disregard the time.
273 * Inception and Expiration are not checked.
275 * \param[in] rrset the rrset to verify
276 * \param[in] rrsig a list of signatures to check
277 * \param[in] keys a list of keys to check with
278 * \param[out] good_keys if this is a (initialized) list, the keys
279 * from keys that validate one of the signatures
281 * \return status LDNS_STATUS_OK if there is at least one correct key
283 ldns_status ldns_verify_notime(ldns_rr_list *rrset,
285 const ldns_rr_list *keys,
286 ldns_rr_list *good_keys);
289 * Tries to build an authentication chain from the given
290 * keys down to the queried domain.
292 * If we find a valid trust path, return the valid keys for the domain.
294 * \param[in] res the current resolver
295 * \param[in] domain the domain we want valid keys for
296 * \param[in] keys the current set of trusted keys
297 * \param[out] status pointer to the status variable where the result
298 * code will be stored
299 * \return the set of trusted keys for the domain, or NULL if no
300 * trust path could be built.
302 ldns_rr_list *ldns_fetch_valid_domain_keys(const ldns_resolver * res,
303 const ldns_rdf * domain,
304 const ldns_rr_list * keys,
305 ldns_status *status);
308 * Validates the DNSKEY RRset for the given domain using the provided
311 * \param[in] res the current resolver
312 * \param[in] domain the domain we want valid keys for
313 * \param[in] keys the current set of trusted keys
314 * \return the set of trusted keys for the domain, or NULL if the RRSET
315 * could not be validated
317 ldns_rr_list *ldns_validate_domain_dnskey (const ldns_resolver *res,
318 const ldns_rdf *domain,
319 const ldns_rr_list *keys);
322 * Validates the DS RRset for the given domain using the provided trusted keys.
324 * \param[in] res the current resolver
325 * \param[in] domain the domain we want valid keys for
326 * \param[in] keys the current set of trusted keys
327 * \return the set of trusted keys for the domain, or NULL if the RRSET could not be validated
329 ldns_rr_list *ldns_validate_domain_ds(const ldns_resolver *res,
332 const ldns_rr_list * keys);
335 * Verifies a list of signatures for one RRset using a valid trust path.
337 * \param[in] res the current resolver
338 * \param[in] rrset the rrset to verify
339 * \param[in] rrsigs a list of signatures to check
340 * \param[out] validating_keys if this is a (initialized) list, the
341 * keys from keys that validate one of
342 * the signatures are added to it
343 * \return status LDNS_STATUS_OK if there is at least one correct key
345 ldns_status ldns_verify_trusted(ldns_resolver *res,
347 ldns_rr_list *rrsigs,
348 ldns_rr_list *validating_keys);
351 * denial is not just a river in egypt
353 * \param[in] rr The (query) RR to check the denial of existence for
354 * \param[in] nsecs The list of NSEC RRs that are supposed to deny the
355 * existence of the RR
356 * \param[in] rrsigs The RRSIG RR covering the NSEC RRs
357 * \return LDNS_STATUS_OK if the NSEC RRs deny the existence, error code
358 * containing the reason they do not otherwise
360 ldns_status ldns_dnssec_verify_denial(ldns_rr *rr,
362 ldns_rr_list *rrsigs);
365 * Denial of existence using NSEC3 records
366 * Since NSEC3 is a bit more complicated than normal denial, some
367 * context arguments are needed
369 * \param[in] rr The (query) RR to check the denial of existence for
370 * \param[in] nsecs The list of NSEC3 RRs that are supposed to deny the
371 * existence of the RR
372 * \param[in] rrsigs The RRSIG rr covering the NSEC RRs
373 * \param[in] packet_rcode The RCODE value of the packet that provided the
375 * \param[in] packet_qtype The original query RR type
376 * \param[in] packet_nodata True if the providing packet had an empty ANSWER
378 * \return LDNS_STATUS_OK if the NSEC3 RRs deny the existence, error code
379 * containing the reason they do not otherwise
381 ldns_status ldns_dnssec_verify_denial_nsec3(ldns_rr *rr,
383 ldns_rr_list *rrsigs,
384 ldns_pkt_rcode packet_rcode,
385 ldns_rr_type packet_qtype,
389 * Verifies the already processed data in the buffers
390 * This function should probably not be used directly.
392 * \param[in] rawsig_buf Buffer containing signature data to use
393 * \param[in] verify_buf Buffer containing data to verify
394 * \param[in] key_buf Buffer containing key data to use
395 * \param[in] algo Signing algorithm
396 * \return status LDNS_STATUS_OK if the data verifies. Error if not.
398 ldns_status ldns_verify_rrsig_buffers(ldns_buffer *rawsig_buf,
399 ldns_buffer *verify_buf,
400 ldns_buffer *key_buf,
404 * Like ldns_verify_rrsig_buffers, but uses raw data.
406 * \param[in] sig signature data to use
407 * \param[in] siglen length of signature data to use
408 * \param[in] verify_buf Buffer containing data to verify
409 * \param[in] key key data to use
410 * \param[in] keylen length of key data to use
411 * \param[in] algo Signing algorithm
412 * \return status LDNS_STATUS_OK if the data verifies. Error if not.
414 ldns_status ldns_verify_rrsig_buffers_raw(unsigned char* sig,
416 ldns_buffer *verify_buf,
422 * Verifies an rrsig. All keys in the keyset are tried.
423 * \param[in] rrset the rrset to check
424 * \param[in] rrsig the signature of the rrset
425 * \param[in] keys the keys to try
426 * \param[out] good_keys if this is a (initialized) list, the keys
427 * from keys that validate one of the signatures
429 * \return a list of keys which validate the rrsig + rrset. Returns
430 * status LDNS_STATUS_OK if at least one key matched. Else an error.
432 ldns_status ldns_verify_rrsig_keylist(ldns_rr_list *rrset,
434 const ldns_rr_list *keys,
435 ldns_rr_list *good_keys);
438 * Verifies an rrsig. All keys in the keyset are tried. Time is not checked.
439 * \param[in] rrset the rrset to check
440 * \param[in] rrsig the signature of the rrset
441 * \param[in] keys the keys to try
442 * \param[out] good_keys if this is a (initialized) list, the keys
443 * from keys that validate one of the signatures
445 * \return a list of keys which validate the rrsig + rrset. Returns
446 * status LDNS_STATUS_OK if at least one key matched. Else an error.
448 ldns_status ldns_verify_rrsig_keylist_notime(ldns_rr_list *rrset,
450 const ldns_rr_list *keys,
451 ldns_rr_list *good_keys);
454 * verify an rrsig with 1 key
455 * \param[in] rrset the rrset
456 * \param[in] rrsig the rrsig to verify
457 * \param[in] key the key to use
458 * \return status message wether verification succeeded.
460 ldns_status ldns_verify_rrsig(ldns_rr_list *rrset,
465 * verifies a buffer with signature data for a buffer with rrset data
468 * \param[in] sig the signature data
469 * \param[in] rrset the rrset data, sorted and processed for verification
470 * \param[in] key the EVP key structure
471 * \param[in] digest_type The digest type of the signature
474 ldns_status ldns_verify_rrsig_evp(ldns_buffer *sig,
477 const EVP_MD *digest_type);
481 * Like ldns_verify_rrsig_evp, but uses raw signature data.
482 * \param[in] sig the signature data, wireformat uncompressed
483 * \param[in] siglen length of the signature data
484 * \param[in] rrset the rrset data, sorted and processed for verification
485 * \param[in] key the EVP key structure
486 * \param[in] digest_type The digest type of the signature
489 ldns_status ldns_verify_rrsig_evp_raw(unsigned char *sig,
493 const EVP_MD *digest_type);
497 * verifies a buffer with signature data (DSA) for a buffer with rrset data
498 * with a buffer with key data.
500 * \param[in] sig the signature data
501 * \param[in] rrset the rrset data, sorted and processed for verification
502 * \param[in] key the key data
504 ldns_status ldns_verify_rrsig_dsa(ldns_buffer *sig,
509 * verifies a buffer with signature data (RSASHA1) for a buffer with rrset data
510 * with a buffer with key data.
512 * \param[in] sig the signature data
513 * \param[in] rrset the rrset data, sorted and processed for verification
514 * \param[in] key the key data
516 ldns_status ldns_verify_rrsig_rsasha1(ldns_buffer *sig,
521 * verifies a buffer with signature data (RSAMD5) for a buffer with rrset data
522 * with a buffer with key data.
524 * \param[in] sig the signature data
525 * \param[in] rrset the rrset data, sorted and processed for verification
526 * \param[in] key the key data
528 ldns_status ldns_verify_rrsig_rsamd5(ldns_buffer *sig,
533 * Like ldns_verify_rrsig_dsa, but uses raw signature and key data.
534 * \param[in] sig raw uncompressed wireformat signature data
535 * \param[in] siglen length of signature data
536 * \param[in] rrset ldns buffer with prepared rrset data.
537 * \param[in] key raw uncompressed wireformat key data
538 * \param[in] keylen length of key data
540 ldns_status ldns_verify_rrsig_dsa_raw(unsigned char* sig,
547 * Like ldns_verify_rrsig_rsasha1, but uses raw signature and key data.
548 * \param[in] sig raw uncompressed wireformat signature data
549 * \param[in] siglen length of signature data
550 * \param[in] rrset ldns buffer with prepared rrset data.
551 * \param[in] key raw uncompressed wireformat key data
552 * \param[in] keylen length of key data
554 ldns_status ldns_verify_rrsig_rsasha1_raw(unsigned char* sig,
561 * Like ldns_verify_rrsig_rsasha256, but uses raw signature and key data.
562 * \param[in] sig raw uncompressed wireformat signature data
563 * \param[in] siglen length of signature data
564 * \param[in] rrset ldns buffer with prepared rrset data.
565 * \param[in] key raw uncompressed wireformat key data
566 * \param[in] keylen length of key data
569 ldns_status ldns_verify_rrsig_rsasha256_raw(unsigned char* sig,
576 * Like ldns_verify_rrsig_rsasha512, but uses raw signature and key data.
577 * \param[in] sig raw uncompressed wireformat signature data
578 * \param[in] siglen length of signature data
579 * \param[in] rrset ldns buffer with prepared rrset data.
580 * \param[in] key raw uncompressed wireformat key data
581 * \param[in] keylen length of key data
583 ldns_status ldns_verify_rrsig_rsasha512_raw(unsigned char* sig,
590 * Like ldns_verify_rrsig_rsamd5, but uses raw signature and key data.
591 * \param[in] sig raw uncompressed wireformat signature data
592 * \param[in] siglen length of signature data
593 * \param[in] rrset ldns buffer with prepared rrset data.
594 * \param[in] key raw uncompressed wireformat key data
595 * \param[in] keylen length of key data
597 ldns_status ldns_verify_rrsig_rsamd5_raw(unsigned char* sig,