xref: /freebsd/contrib/unbound/validator/autotrust.h (revision a9e8641da961bcf3d24afc85fd657f2083a872a2)
1 /*
2  * validator/autotrust.h - RFC5011 trust anchor management for unbound.
3  *
4  * Copyright (c) 2009, NLnet Labs. All rights reserved.
5  *
6  * This software is open source.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * Redistributions of source code must retain the above copyright notice,
13  * this list of conditions and the following disclaimer.
14  *
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.
18  *
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.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
25  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
26  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
27  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
28  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
32  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33  * POSSIBILITY OF SUCH DAMAGE.
34  */
35 
36 /**
37  * \file
38  *
39  * Contains autotrust definitions.
40  */
41 
42 #ifndef VALIDATOR_AUTOTRUST_H
43 #define VALIDATOR_AUTOTRUST_H
44 #include "util/rbtree.h"
45 #include "util/data/packed_rrset.h"
46 struct val_anchors;
47 struct trust_anchor;
48 struct ub_packed_rrset_key;
49 struct module_env;
50 struct val_env;
51 
52 /** Autotrust anchor states */
53 typedef enum {
54 	AUTR_STATE_START   = 0,
55 	AUTR_STATE_ADDPEND = 1,
56 	AUTR_STATE_VALID   = 2,
57 	AUTR_STATE_MISSING = 3,
58 	AUTR_STATE_REVOKED = 4,
59 	AUTR_STATE_REMOVED = 5
60 } autr_state_t;
61 
62 /**
63  * Autotrust metadata for one trust anchor key.
64  */
65 struct autr_ta {
66 	/** next key */
67 	struct autr_ta* next;
68 	/** the RR */
69 	ldns_rr* rr;
70 	/** last update of key state (new pending count keeps date the same) */
71 	time_t last_change;
72 	/** 5011 state */
73 	autr_state_t s;
74 	/** pending count */
75 	uint8_t pending_count;
76 	/** fresh TA was seen */
77 	uint8_t fetched;
78 	/** revoked TA was seen */
79 	uint8_t revoked;
80 };
81 
82 /**
83  * Autotrust metadata for a trust point.
84  * This is part of the struct trust_anchor data.
85  */
86 struct autr_point_data {
87 	/** file to store the trust point in. chrootdir already applied. */
88 	char* file;
89 	/** rbtree node for probe sort, key is struct trust_anchor */
90 	rbnode_t pnode;
91 
92 	/** the keys */
93 	struct autr_ta* keys;
94 
95 	/** last queried DNSKEY set
96 	 * Not all failures are captured in this entry.
97 	 * If the validator did not even start (e.g. timeout or localservfail),
98 	 * then the last_queried and query_failed values are not updated.
99 	 */
100 	time_t last_queried;
101 	/** last successful DNSKEY set */
102 	time_t last_success;
103 	/** next probe time */
104 	time_t next_probe_time;
105 
106 	/** when to query if !failed */
107 	uint32_t query_interval;
108 	/** when to retry if failed */
109 	uint32_t retry_time;
110 
111 	/**
112 	 * How many times did it fail. diagnostic only (has no effect).
113 	 * Only updated if there was a dnskey rrset that failed to verify.
114 	 */
115 	uint8_t query_failed;
116 	/** true if the trust point has been revoked */
117 	uint8_t revoked;
118 };
119 
120 /**
121  * Autotrust global metadata.
122  */
123 struct autr_global_data {
124 	/** rbtree of autotrust anchors sorted by next probe time.
125 	 * When time is equal, sorted by anchor class, name. */
126 	rbtree_t probe;
127 };
128 
129 /**
130  * Create new global 5011 data structure.
131  * @return new structure or NULL on malloc failure.
132  */
133 struct autr_global_data* autr_global_create(void);
134 
135 /**
136  * Delete global 5011 data structure.
137  * @param global: global autotrust state to delete.
138  */
139 void autr_global_delete(struct autr_global_data* global);
140 
141 /**
142  * See if autotrust anchors are configured and how many.
143  * @param anchors: the trust anchors structure.
144  * @return number of autotrust trust anchors
145  */
146 size_t autr_get_num_anchors(struct val_anchors* anchors);
147 
148 /**
149  * Process probe timer.  Add new probes if needed.
150  * @param env: module environment with time, with anchors and with the mesh.
151  * @return time of next probe (in seconds from now).
152  * 	If 0, then there is no next probe anymore (trust points deleted).
153  */
154 uint32_t autr_probe_timer(struct module_env* env);
155 
156 /** probe tree compare function */
157 int probetree_cmp(const void* x, const void* y);
158 
159 /**
160  * Read autotrust file.
161  * @param anchors: the anchors structure.
162  * @param nm: name of the file (copied).
163  * @return false on failure.
164  */
165 int autr_read_file(struct val_anchors* anchors, const char* nm);
166 
167 /**
168  * Write autotrust file.
169  * @param env: environment with scratch space.
170  * @param tp: trust point to write.
171  */
172 void autr_write_file(struct module_env* env, struct trust_anchor* tp);
173 
174 /**
175  * Delete autr anchor, deletes the autr data but does not do
176  * unlinking from trees, caller does that.
177  * @param tp: trust point to delete.
178  */
179 void autr_point_delete(struct trust_anchor* tp);
180 
181 /**
182  * Perform autotrust processing.
183  * @param env: qstate environment with the anchors structure.
184  * @param ve: validator environment for verification of rrsigs.
185  * @param tp: trust anchor to process.
186  * @param dnskey_rrset: DNSKEY rrset probed (can be NULL if bad prime result).
187  * 	allocated in a region. Has not been validated yet.
188  * @return false if trust anchor was revoked completely.
189  * 	Otherwise logs errors to log, does not change return value.
190  * 	On errors, likely the trust point has been unchanged.
191  */
192 int autr_process_prime(struct module_env* env, struct val_env* ve,
193 	struct trust_anchor* tp, struct ub_packed_rrset_key* dnskey_rrset);
194 
195 /**
196  * Debug printout of rfc5011 tracked anchors
197  * @param anchors: all the anchors.
198  */
199 void autr_debug_print(struct val_anchors* anchors);
200 
201 /** callback for query answer to 5011 probe */
202 void probe_answer_cb(void* arg, int rcode, ldns_buffer* buf,
203 	enum sec_status sec, char* errinf);
204 
205 #endif /* VALIDATOR_AUTOTRUST_H */
206