manpages: Remove some unneeded .Pp's.
[dragonfly.git] / contrib / ldns / ldns / dnssec_verify.h
1 /** dnssec_verify */
2
3 #ifndef LDNS_DNSSEC_VERIFY_H
4 #define LDNS_DNSSEC_VERIFY_H
5
6 #define LDNS_DNSSEC_TRUST_TREE_MAX_PARENTS 10
7
8 #include <ldns/dnssec.h>
9
10 /**
11  * Chain structure that contains all DNSSEC data needed to
12  * verify an rrset
13  */
14 typedef struct ldns_dnssec_data_chain_struct ldns_dnssec_data_chain;
15 struct ldns_dnssec_data_chain_struct
16 {
17         ldns_rr_list *rrset;
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;
23         bool packet_nodata;
24 };
25
26 /**
27  * Creates a new dnssec_chain structure
28  * \return ldns_dnssec_data_chain *
29  */
30 ldns_dnssec_data_chain *ldns_dnssec_data_chain_new();
31
32 /**
33  * Frees a dnssec_data_chain structure
34  *
35  * \param[in] *chain The chain to free
36  */
37 void ldns_dnssec_data_chain_free(ldns_dnssec_data_chain *chain);
38
39 /**
40  * Frees a dnssec_data_chain structure, and all data
41  * contained therein
42  *
43  * \param[in] *chain The dnssec_data_chain to free
44  */
45 void ldns_dnssec_data_chain_deep_free(ldns_dnssec_data_chain *chain);
46
47 /**
48  * Prints the dnssec_data_chain to the given file stream
49  * 
50  * \param[in] *out The file stream to print to
51  * \param[in] *chain The dnssec_data_chain to print
52  */
53 void ldns_dnssec_data_chain_print(FILE *out, const ldns_dnssec_data_chain *chain);
54
55 /**
56  * Build an ldns_dnssec_data_chain, which contains all
57  * DNSSEC data that is needed to derive the trust tree later
58  *
59  * The data_set will be cloned
60  *
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
67  *
68  * \return the DNSSEC data chain
69  */
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,
73                                                                                    const ldns_pkt *pkt,
74                                                                                    ldns_rr *orig_rr);
75
76 /**
77  * Tree structure that contains the relation of DNSSEC data,
78  * and their cryptographic status.
79  *
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
85  * that chain.
86  *
87  * Example tree:
88  *     key   key    key
89  *       \    |    /
90  *        \   |   /
91  *         \  |  /
92  *            ds
93  *            |
94  *           key
95  *            |
96  *           key
97  *            |
98  *            rr
99  *
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
104  */
105 typedef struct ldns_dnssec_trust_tree_struct ldns_dnssec_trust_tree;
106 struct ldns_dnssec_trust_tree_struct
107 {
108         ldns_rr *rr;
109         /* the complete rrset this rr was in */
110         ldns_rr_list *rrset;
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];
116         size_t parent_count;
117 };
118
119 /**
120  * Creates a new (empty) dnssec_trust_tree structure
121  *
122  * \return ldns_dnssec_trust_tree *
123  */
124 ldns_dnssec_trust_tree *ldns_dnssec_trust_tree_new();
125
126 /**
127  * Frees the dnssec_trust_tree recursively
128  *
129  * There is no deep free; all data in the trust tree
130  * consists of pointers to a data_chain
131  *
132  * \param[in] tree The tree to free
133  */
134 void ldns_dnssec_trust_tree_free(ldns_dnssec_trust_tree *tree);
135
136 /**
137  * returns the depth of the trust tree
138  *
139  * \param[in] tree tree to calculate the depth of
140  * \return The depth of the tree
141  */
142 size_t ldns_dnssec_trust_tree_depth(ldns_dnssec_trust_tree *tree);
143
144 /**
145  * Prints the dnssec_trust_tree structure to the given file
146  * stream.
147  *
148  * If a link status is not LDNS_STATUS_OK; the status and
149  * relevant signatures are printed too
150  *
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
155  */
156 void ldns_dnssec_trust_tree_print(FILE *out,
157                                                     ldns_dnssec_trust_tree *tree,
158                                                     size_t tabs,
159                                                     bool extended);
160
161 /**
162  * Adds a trust tree as a parent for the given trust tree
163  *
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
167  *                              connection
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
170  */
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);
175
176 /**
177  * Generates a dnssec_trust_ttree for the given rr from the
178  * given data_chain
179  *
180  * This does not clone the actual data; Don't free the
181  * data_chain before you are done with this tree
182  *
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 *
186  */
187 ldns_dnssec_trust_tree *ldns_dnssec_derive_trust_tree(
188                             ldns_dnssec_data_chain *data_chain,
189                                            ldns_rr *rr);
190
191 /**
192  * Sub function for derive_trust_tree that is used for a
193  * 'normal' rrset
194  *
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
198  */
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);
203
204 /**
205  * Sub function for derive_trust_tree that is used for DNSKEY rrsets
206  *
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
211  */
212 void ldns_dnssec_derive_trust_tree_dnskey_rrset(
213          ldns_dnssec_trust_tree *new_tree,
214             ldns_dnssec_data_chain *data_chain,
215             ldns_rr *cur_rr,
216             ldns_rr *cur_sig_rr);
217
218 /**
219  * Sub function for derive_trust_tree that is used for DS rrsets
220  *
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
224  */
225 void ldns_dnssec_derive_trust_tree_ds_rrset(
226          ldns_dnssec_trust_tree *new_tree,
227             ldns_dnssec_data_chain *data_chain,
228             ldns_rr *cur_rr);
229
230 /**
231  * Sub function for derive_trust_tree that is used when there are no
232  * signatures
233  *
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
236  */
237 void ldns_dnssec_derive_trust_tree_no_sig(
238          ldns_dnssec_trust_tree *new_tree,
239             ldns_dnssec_data_chain *data_chain);
240
241 /**
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
244  *
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
250  */
251 ldns_status ldns_dnssec_trust_tree_contains_keys(
252                          ldns_dnssec_trust_tree *tree,
253                          ldns_rr_list *keys);
254
255 /**
256  * Verifies a list of signatures for one rrset.
257  *
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
263  *                        are added to it
264  * \return status LDNS_STATUS_OK if there is at least one correct key
265  */
266 ldns_status ldns_verify(ldns_rr_list *rrset,
267                                     ldns_rr_list *rrsig,
268                                     const ldns_rr_list *keys,
269                                     ldns_rr_list *good_keys);   
270
271 /**
272  * Verifies a list of signatures for one rrset, but disregard the time.
273  * Inception and Expiration are not checked.
274  *
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
280  *                        are added to it
281  * \return status LDNS_STATUS_OK if there is at least one correct key
282  */
283 ldns_status ldns_verify_notime(ldns_rr_list *rrset,
284                                     ldns_rr_list *rrsig,
285                                     const ldns_rr_list *keys,
286                                     ldns_rr_list *good_keys);   
287
288 /**
289  * Tries to build an authentication chain from the given 
290  * keys down to the queried domain.
291  *
292  * If we find a valid trust path, return the valid keys for the domain.
293  * 
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.
301  */
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);
306
307 /**
308  * Validates the DNSKEY RRset for the given domain using the provided 
309  * trusted keys.
310  *
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
316  */
317 ldns_rr_list *ldns_validate_domain_dnskey (const ldns_resolver *res,
318                                                                    const ldns_rdf *domain,
319                                                                    const ldns_rr_list *keys);
320
321 /**
322  * Validates the DS RRset for the given domain using the provided trusted keys.
323  *
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
328  */
329 ldns_rr_list *ldns_validate_domain_ds(const ldns_resolver *res,
330                                                            const ldns_rdf *
331                                                            domain,
332                                                            const ldns_rr_list * keys);
333
334 /**
335  * Verifies a list of signatures for one RRset using a valid trust path.
336  *
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
344  */
345 ldns_status ldns_verify_trusted(ldns_resolver *res,
346                                                   ldns_rr_list *rrset,
347                                                   ldns_rr_list *rrsigs,
348                                                   ldns_rr_list *validating_keys);
349
350 /**
351  * denial is not just a river in egypt
352  *
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
359  */
360 ldns_status ldns_dnssec_verify_denial(ldns_rr *rr,
361                                                            ldns_rr_list *nsecs,
362                                                            ldns_rr_list *rrsigs);
363
364 /**
365  * Denial of existence using NSEC3 records
366  * Since NSEC3 is a bit more complicated than normal denial, some
367  * context arguments are needed
368  *
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
374  *                         NSEC3 RRs
375  * \param[in] packet_qtype The original query RR type
376  * \param[in] packet_nodata True if the providing packet had an empty ANSWER
377  *                          section
378  * \return LDNS_STATUS_OK if the NSEC3 RRs deny the existence, error code
379  *                        containing the reason they do not otherwise
380  */
381 ldns_status ldns_dnssec_verify_denial_nsec3(ldns_rr *rr,
382                                                                     ldns_rr_list *nsecs,
383                                                                     ldns_rr_list *rrsigs,
384                                                                     ldns_pkt_rcode packet_rcode,
385                                                                     ldns_rr_type packet_qtype,
386                                                                     bool packet_nodata);
387
388 /**
389  * Verifies the already processed data in the buffers
390  * This function should probably not be used directly.
391  *
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.
397  */
398 ldns_status ldns_verify_rrsig_buffers(ldns_buffer *rawsig_buf,
399                                                            ldns_buffer *verify_buf,
400                                                            ldns_buffer *key_buf,
401                                                            uint8_t algo);
402
403 /**
404  * Like ldns_verify_rrsig_buffers, but uses raw data.
405  *
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.
413  */
414 ldns_status ldns_verify_rrsig_buffers_raw(unsigned char* sig,
415                                                                   size_t siglen, 
416                                                                   ldns_buffer *verify_buf,
417                                                                   unsigned char* key,
418                                                                   size_t keylen, 
419                                                                   uint8_t algo);
420
421 /**
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
428  *                        are added to it
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.
431  */
432 ldns_status ldns_verify_rrsig_keylist(ldns_rr_list *rrset,
433                                                            ldns_rr *rrsig,
434                                                            const ldns_rr_list *keys,
435                                                            ldns_rr_list *good_keys);
436
437 /**
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
444  *                        are added to it
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.
447  */
448 ldns_status ldns_verify_rrsig_keylist_notime(ldns_rr_list *rrset,
449                                                            ldns_rr *rrsig,
450                                                            const ldns_rr_list *keys,
451                                                            ldns_rr_list *good_keys);
452
453 /**
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.
459  */
460 ldns_status ldns_verify_rrsig(ldns_rr_list *rrset,
461                                                 ldns_rr *rrsig,
462                                                 ldns_rr *key);
463
464 /**
465  * verifies a buffer with signature data for a buffer with rrset data 
466  * with an EVP_PKEY
467  *
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
472  */
473 #ifdef HAVE_SSL
474 ldns_status ldns_verify_rrsig_evp(ldns_buffer *sig,
475                                                     ldns_buffer *rrset,
476                                                     EVP_PKEY *key,
477                                                     const EVP_MD *digest_type);
478 #endif
479
480 /**
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
487  */
488 #ifdef HAVE_SSL
489 ldns_status ldns_verify_rrsig_evp_raw(unsigned char *sig,
490                                                            size_t siglen,
491                                                            ldns_buffer *rrset,
492                                                            EVP_PKEY *key,
493                                                            const EVP_MD *digest_type);
494 #endif
495
496 /**
497  * verifies a buffer with signature data (DSA) for a buffer with rrset data 
498  * with a buffer with key data.
499  *
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
503  */
504 ldns_status ldns_verify_rrsig_dsa(ldns_buffer *sig,
505                                                     ldns_buffer *rrset,
506                                                     ldns_buffer *key);
507
508 /**
509  * verifies a buffer with signature data (RSASHA1) for a buffer with rrset data 
510  * with a buffer with key data.
511  *
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
515  */
516 ldns_status ldns_verify_rrsig_rsasha1(ldns_buffer *sig,
517                                                            ldns_buffer *rrset,
518                                                            ldns_buffer *key);
519
520 /**
521  * verifies a buffer with signature data (RSAMD5) for a buffer with rrset data 
522  * with a buffer with key data.
523  *
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
527  */
528 ldns_status ldns_verify_rrsig_rsamd5(ldns_buffer *sig,
529                                                           ldns_buffer *rrset,
530                                                           ldns_buffer *key);
531
532 /**
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
539  */
540 ldns_status ldns_verify_rrsig_dsa_raw(unsigned char* sig,
541                                                            size_t siglen,
542                                                            ldns_buffer* rrset,
543                                                            unsigned char* key,
544                                                            size_t keylen);
545
546 /**
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
553  */
554 ldns_status ldns_verify_rrsig_rsasha1_raw(unsigned char* sig,
555                                                                   size_t siglen,
556                                                                   ldns_buffer* rrset,
557                                                                   unsigned char* key,
558                                                                   size_t keylen);
559
560 /**
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
567  */
568
569 ldns_status ldns_verify_rrsig_rsasha256_raw(unsigned char* sig,
570                                                                     size_t siglen,
571                                                                     ldns_buffer* rrset,
572                                                                     unsigned char* key,
573                                                                     size_t keylen);
574
575 /**
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
582  */
583 ldns_status ldns_verify_rrsig_rsasha512_raw(unsigned char* sig,
584                                                                     size_t siglen,
585                                                                     ldns_buffer* rrset,
586                                                                     unsigned char* key,
587                                                                     size_t keylen);
588
589 /**
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
596  */
597 ldns_status ldns_verify_rrsig_rsamd5_raw(unsigned char* sig,
598                                                                  size_t siglen,
599                                                                  ldns_buffer* rrset,
600                                                                  unsigned char* key,
601                                                                  size_t keylen);
602
603 #endif
604