xref: /freebsd/contrib/unbound/services/authzone.h (revision b2efd602aea8b3cbc3fb215b9611946d04fceb10)
1 /*
2  * services/authzone.h - authoritative zone that is locally hosted.
3  *
4  * Copyright (c) 2017, 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
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.
34  */
35 
36 /**
37  * \file
38  *
39  * This file contains the functions for an authority zone.  This zone
40  * is queried by the iterator, just like a stub or forward zone, but then
41  * the data is locally held.
42  */
43 
44 #ifndef SERVICES_AUTHZONE_H
45 #define SERVICES_AUTHZONE_H
46 #include "util/rbtree.h"
47 #include "util/locks.h"
48 #include "services/mesh.h"
49 #include "services/rpz.h"
50 struct ub_packed_rrset_key;
51 struct regional;
52 struct config_file;
53 struct config_auth;
54 struct query_info;
55 struct dns_msg;
56 struct edns_data;
57 struct module_env;
58 struct worker;
59 struct comm_point;
60 struct comm_timer;
61 struct comm_reply;
62 struct auth_rrset;
63 struct auth_nextprobe;
64 struct auth_probe;
65 struct auth_transfer;
66 struct auth_master;
67 struct auth_chunk;
68 
69 /**
70  * Authoritative zones, shared.
71  */
72 struct auth_zones {
73 	/** lock on the authzone trees. It is locked after views, respip,
74 	 * local_zones and before fwds and stubs. */
75 	lock_rw_type lock;
76 	/** rbtree of struct auth_zone */
77 	rbtree_type ztree;
78 	/** rbtree of struct auth_xfer */
79 	rbtree_type xtree;
80 	/** do we have downstream enabled */
81 	int have_downstream;
82 	/** first auth zone containing rpz item in linked list */
83 	struct auth_zone* rpz_first;
84 	/** rw lock for rpz linked list, needed when iterating or editing linked
85 	 * list. */
86 	lock_rw_type rpz_lock;
87 };
88 
89 /**
90  * Auth zone.  Authoritative data, that is fetched from instead of sending
91  * packets to the internet.
92  */
93 struct auth_zone {
94 	/** rbtree node, key is name and class */
95 	rbnode_type node;
96 
97 	/** zone name, in uncompressed wireformat */
98 	uint8_t* name;
99 	/** length of zone name */
100 	size_t namelen;
101 	/** number of labels in zone name */
102 	int namelabs;
103 	/** the class of this zone, in host byteorder.
104 	 * uses 'dclass' to not conflict with c++ keyword class. */
105 	uint16_t dclass;
106 
107 	/** lock on the data in the structure
108 	 * For the node, parent, name, namelen, namelabs, dclass, you
109 	 * need to also hold the zones_tree lock to change them (or to
110 	 * delete this zone) */
111 	lock_rw_type lock;
112 
113 	/** auth data for this zone
114 	 * rbtree of struct auth_data */
115 	rbtree_type data;
116 
117 	/** zonefile name (or NULL for no zonefile) */
118 	char* zonefile;
119 	/** fallback to the internet on failure or ttl-expiry of auth zone */
120 	int fallback_enabled;
121 	/** the time when zone was transferred from upstream */
122 	time_t soa_zone_acquired;
123 	/** the zone has expired (enabled by the xfer worker), fallback
124 	 * happens if that option is enabled. */
125 	int zone_expired;
126 	/** zone is a slave zone (it has masters) */
127 	int zone_is_slave;
128 	/** for downstream: this zone answers queries towards the downstream
129 	 * clients */
130 	int for_downstream;
131 	/** for upstream: this zone answers queries that unbound intends to
132 	 * send upstream. */
133 	int for_upstream;
134 	/** check ZONEMD records */
135 	int zonemd_check;
136 	/** reject absence of ZONEMD records */
137 	int zonemd_reject_absence;
138 	/** RPZ zones */
139 	struct rpz* rpz;
140 	/** store the env (worker thread specific) for the zonemd callbacks
141 	 * from the mesh with the results of the lookup, if nonNULL, some
142 	 * worker has already picked up the zonemd verification task and
143 	 * this worker does not have to do it as well. */
144 	struct module_env* zonemd_callback_env;
145 	/** for the zonemd callback, the type of data looked up */
146 	uint16_t zonemd_callback_qtype;
147 	/** zone has been deleted */
148 	int zone_deleted;
149 	/** deletelist pointer, unused normally except during delete */
150 	struct auth_zone* delete_next;
151 	/* not protected by auth_zone lock, must be last items in struct */
152 	/** next auth zone containing RPZ data, or NULL */
153 	struct auth_zone* rpz_az_next;
154 	/** previous auth zone containing RPZ data, or NULL */
155 	struct auth_zone* rpz_az_prev;
156 };
157 
158 /**
159  * Auth data. One domain name, and the RRs to go with it.
160  */
161 struct auth_data {
162 	/** rbtree node, key is name only */
163 	rbnode_type node;
164 	/** domain name */
165 	uint8_t* name;
166 	/** length of name */
167 	size_t namelen;
168 	/** number of labels in name */
169 	int namelabs;
170 	/** the data rrsets, with different types, linked list.
171 	 * if the list if NULL the node would be an empty non-terminal,
172 	 * but in this data structure such nodes that represent an empty
173 	 * non-terminal are not needed; they just don't exist.
174 	 */
175 	struct auth_rrset* rrsets;
176 };
177 
178 /**
179  * A auth data RRset
180  */
181 struct auth_rrset {
182 	/** next in list */
183 	struct auth_rrset* next;
184 	/** RR type in host byteorder */
185 	uint16_t type;
186 	/** RRset data item */
187 	struct packed_rrset_data* data;
188 };
189 
190 /**
191  * Authoritative zone transfer structure.
192  * Create and destroy needs the auth_zones* biglock.
193  * The structure consists of different tasks.  Each can be unowned (-1) or
194  * owner by a worker (worker-num).  A worker can pick up a task and then do
195  * it.  This means the events (timeouts, sockets) are for that worker.
196  *
197  * (move this to tasks).
198  * They don't have locks themselves, the worker (that owns it) uses it,
199  * also as part of callbacks, hence it has separate zonename pointers for
200  * lookup in the main zonetree.  If the zone has no transfers, this
201  * structure is not created.
202  */
203 struct auth_xfer {
204 	/** rbtree node, key is name and class */
205 	rbnode_type node;
206 
207 	/** lock on this structure, and on the workernum elements of the
208 	 * tasks.  First hold the tree-lock in auth_zones, find the auth_xfer,
209 	 * lock this lock.  Then a worker can reassign itself to fill up
210 	 * one of the tasks.
211 	 * Once it has the task assigned to it, the worker can access the
212 	 * other elements of the task structure without a lock, because that
213 	 * is necessary for the eventloop and callbacks from that.
214 	 * The auth_zone->lock is locked before this lock.
215 	 */
216 	lock_basic_type lock;
217 
218 	/** zone name, in uncompressed wireformat */
219 	uint8_t* name;
220 	/** length of zone name */
221 	size_t namelen;
222 	/** number of labels in zone name */
223 	int namelabs;
224 	/** the class of this zone, in host byteorder.
225 	 * uses 'dclass' to not conflict with c++ keyword class. */
226 	uint16_t dclass;
227 
228 	/** task to wait for next-probe-timeout,
229 	 * once timeouted, see if a SOA probe is needed, or already
230 	 * in progress */
231 	struct auth_nextprobe* task_nextprobe;
232 
233 	/** task for SOA probe.  Check if the zone can be updated */
234 	struct auth_probe* task_probe;
235 
236 	/** Task for transfer.  Transferring and updating the zone.  This
237 	 * includes trying (potentially) several upstream masters.  Downloading
238 	 * and storing the zone */
239 	struct auth_transfer* task_transfer;
240 
241 	/** a notify was received, but a zone transfer or probe was already
242 	 * acted on.
243 	 * However, the zone transfer could signal a newer serial number.
244 	 * The serial number of that notify is saved below.  The transfer and
245 	 * probe tasks should check this once done to see if they need to
246 	 * restart the transfer task for the newer notify serial.
247 	 * Hold the lock to access this member (and the serial).
248 	 */
249 	int notify_received;
250 	/** true if the notify_received has a serial number */
251 	int notify_has_serial;
252 	/** serial number of the notify */
253 	uint32_t notify_serial;
254 	/** the list of masters for checking notifies.  This list is
255 	 * empty on start, and a copy of the list from the probe_task when
256 	 * it is done looking them up. */
257 	struct auth_master* allow_notify_list;
258 
259 	/* protected by the lock on the structure, information about
260 	 * the loaded authority zone. */
261 	/** is the zone currently considered expired? after expiry also older
262          * serial numbers are allowed (not just newer) */
263 	int zone_expired;
264 	/** do we have a zone (if 0, no zone data at all) */
265 	int have_zone;
266 	/** the time when zone was transferred from upstream */
267 	time_t soa_zone_acquired;
268 
269 	/** current serial (from SOA), if we have no zone, 0 */
270 	uint32_t serial;
271 	/** retry time (from SOA), time to wait with next_probe
272 	 * if no master responds */
273 	time_t retry;
274 	/** refresh time (from SOA), time to wait with next_probe
275 	 * if everything is fine */
276 	time_t refresh;
277 	/** expiry time (from SOA), time until zone data is not considered
278 	 * valid any more, if no master responds within this time, either
279 	 * with the current zone or a new zone. */
280 	time_t expiry;
281 
282 	/** zone lease start time (start+expiry is expiration time).
283 	 * this is renewed every SOA probe and transfer.  On zone load
284 	 * from zonefile it is also set (with probe set soon to check) */
285 	time_t lease_time;
286 };
287 
288 /**
289  * The next probe task.
290  * This task consists of waiting for the probetimeout.  It is a task because
291  * it needs an event in the eventtable.  Once the timeout has passed, that
292  * worker can (potentially) become the auth_probe worker, or if another worker
293  * is already doing that, do nothing.  Tasks becomes unowned.
294  * The probe worker, if it detects nothing has to be done picks up this task,
295  * if unowned.
296  */
297 struct auth_nextprobe {
298 	/* Worker pointer. NULL means unowned. */
299 	struct worker* worker;
300 	/* module env for this task */
301 	struct module_env* env;
302 
303 	/** increasing backoff for failures */
304 	time_t backoff;
305 	/** Timeout for next probe (for SOA) */
306 	time_t next_probe;
307 	/** timeout callback for next_probe or expiry(if that is sooner).
308 	 * it is on the worker's event_base */
309 	struct comm_timer* timer;
310 };
311 
312 /**
313  * The probe task.
314  * Send a SOA UDP query to see if the zone needs to be updated (or similar,
315  * potential, HTTP probe query) and check serial number.
316  * If yes, start the auth_transfer task.  If no, make sure auth_nextprobe
317  * timeout wait task is running.
318  * Needs to be a task, because the UDP query needs an event entry.
319  * This task could also be started by eg. a NOTIFY being received, even though
320  * another worker is performing the nextprobe task (and that worker keeps
321  * waiting uninterrupted).
322  */
323 struct auth_probe {
324 	/* Worker pointer. NULL means unowned. */
325 	struct worker* worker;
326 	/* module env for this task */
327 	struct module_env* env;
328 
329 	/** list of upstream masters for this zone, from config */
330 	struct auth_master* masters;
331 
332 	/** for the hostname lookups, which master is current */
333 	struct auth_master* lookup_target;
334 	/** are we looking up A or AAAA, first A, then AAAA (if ip6 enabled) */
335 	int lookup_aaaa;
336 	/** we only want to do lookups for making config work (for notify),
337 	 * don't proceed with UDP SOA probe queries */
338 	int only_lookup;
339 	/** we have seen a new lease this scan, because one of the masters
340 	 * replied with the current SOA serial version */
341 	int have_new_lease;
342 
343 	/** once notified, or the timeout has been reached. a scan starts. */
344 	/** the scan specific target (notify source), or NULL if none */
345 	struct auth_master* scan_specific;
346 	/** scan tries all the upstream masters. the scan current target.
347 	 * or NULL if not working on sequential scan */
348 	struct auth_master* scan_target;
349 	/** if not NULL, the specific addr for the current master */
350 	struct auth_addr* scan_addr;
351 
352 	/** dns id of packet in flight */
353 	uint16_t id;
354 	/** the SOA probe udp event.
355 	 * on the workers event base. */
356 	struct comm_point* cp;
357 	/** is the cp for ip6 or ip4 */
358 	int cp_is_ip6;
359 	/** timeout for packets.
360 	 * on the workers event base. */
361 	struct comm_timer* timer;
362 	/** timeout in msec */
363 	int timeout;
364 };
365 
366 /**
367  * The transfer task.
368  * Once done, make sure the nextprobe waiting task is running, whether done
369  * with failure or success.  If failure, use shorter timeout for wait time.
370  */
371 struct auth_transfer {
372 	/* Worker pointer. NULL means unowned. */
373 	struct worker* worker;
374 	/* module env for this task */
375 	struct module_env* env;
376 
377 	/** xfer data that has been transferred, the data is applied
378 	 * once the transfer has completed correctly */
379 	struct auth_chunk* chunks_first;
380 	/** last element in chunks list (to append new data at the end) */
381 	struct auth_chunk* chunks_last;
382 
383 	/** list of upstream masters for this zone, from config */
384 	struct auth_master* masters;
385 
386 	/** for the hostname lookups, which master is current */
387 	struct auth_master* lookup_target;
388 	/** are we looking up A or AAAA, first A, then AAAA (if ip6 enabled) */
389 	int lookup_aaaa;
390 
391 	/** once notified, or the timeout has been reached. a scan starts. */
392 	/** the scan specific target (notify source), or NULL if none */
393 	struct auth_master* scan_specific;
394 	/** scan tries all the upstream masters. the scan current target.
395 	 * or NULL if not working on sequential scan */
396 	struct auth_master* scan_target;
397 	/** what address we are scanning for the master, or NULL if the
398 	 * master is in IP format itself */
399 	struct auth_addr* scan_addr;
400 	/** the zone transfer in progress (or NULL if in scan).  It is
401 	 * from this master */
402 	struct auth_master* master;
403 
404 	/** failed ixfr transfer, retry with axfr (to the current master),
405 	 * the IXFR was 'REFUSED', 'SERVFAIL', 'NOTIMPL' or the contents of
406 	 * the IXFR did not apply cleanly (out of sync, delete of nonexistent
407 	 * data or add of duplicate data).  Flag is cleared once the retry
408 	 * with axfr is done. */
409 	int ixfr_fail;
410 	/** we saw an ixfr-indicating timeout, count of them */
411 	int ixfr_possible_timeout_count;
412 	/** we are doing IXFR right now */
413 	int on_ixfr;
414 	/** did we detect the current AXFR/IXFR serial number yet, 0 not yet,
415 	 * 1 we saw the first, 2 we saw the second, 3 must be last SOA in xfr*/
416 	int got_xfr_serial;
417 	/** number of RRs scanned for AXFR/IXFR detection */
418 	size_t rr_scan_num;
419 	/** we are doing an IXFR but we detected an AXFR contents */
420 	int on_ixfr_is_axfr;
421 	/** the serial number for the current AXFR/IXFR incoming reply,
422 	 * for IXFR, the outermost SOA records serial */
423 	uint32_t incoming_xfr_serial;
424 
425 	/** dns id of AXFR query */
426 	uint16_t id;
427 	/** the transfer (TCP) to the master.
428 	 * on the workers event base. */
429 	struct comm_point* cp;
430 	/** timeout for the transfer.
431 	 * on the workers event base. */
432 	struct comm_timer* timer;
433 };
434 
435 /** list of addresses */
436 struct auth_addr {
437 	/** next in list */
438 	struct auth_addr* next;
439 	/** IP address */
440 	struct sockaddr_storage addr;
441 	/** addr length */
442 	socklen_t addrlen;
443 };
444 
445 /** auth zone master upstream, and the config settings for it */
446 struct auth_master {
447 	/** next master in list */
448 	struct auth_master* next;
449 	/** master IP address (and port), or hostname, string */
450 	char* host;
451 	/** for http, filename */
452 	char* file;
453 	/** use HTTP for this master */
454 	int http;
455 	/** use IXFR for this master */
456 	int ixfr;
457 	/** this is an allow notify member, the master can send notifies
458 	 * to us, but we don't send SOA probes, or zone transfer from it */
459 	int allow_notify;
460 	/** use ssl for channel */
461 	int ssl;
462 	/** the port number (for urls) */
463 	int port;
464 	/** if the host is a hostname, the list of resolved addrs, if any*/
465 	struct auth_addr* list;
466 };
467 
468 /** auth zone master zone transfer data chunk */
469 struct auth_chunk {
470 	/** next chunk in list */
471 	struct auth_chunk* next;
472 	/** the data from this chunk, this is what was received.
473 	 * for an IXFR that means results from comm_net tcp actions,
474 	 * packets. also for an AXFR. For HTTP a zonefile chunk. */
475 	uint8_t* data;
476 	/** length of allocated data */
477 	size_t len;
478 };
479 
480 /**
481  * Create auth zones structure
482  */
483 struct auth_zones* auth_zones_create(void);
484 
485 /**
486  * Apply configuration to auth zones.  Reads zonefiles.
487  * @param az: auth zones structure
488  * @param cfg: config to apply.
489  * @param setup: if true, also sets up values in the auth zones structure
490  * @param is_rpz: set to 1 if at least one RPZ zone is configured.
491  * @param env: environment for offline verification.
492  * @param mods: modules in environment.
493  * @return false on failure.
494  */
495 int auth_zones_apply_cfg(struct auth_zones* az, struct config_file* cfg,
496 	int setup, int* is_rpz, struct module_env* env,
497 	struct module_stack* mods);
498 
499 /** initial pick up of worker timeouts, ties events to worker event loop
500  * @param az: auth zones structure
501  * @param env: worker env, of first worker that receives the events (if any)
502  * 	in its eventloop.
503  */
504 void auth_xfer_pickup_initial(struct auth_zones* az, struct module_env* env);
505 
506 /**
507  * Cleanup auth zones.  This removes all events from event bases.
508  * Stops the xfr tasks.  But leaves zone data.
509  * @param az: auth zones structure.
510  */
511 void auth_zones_cleanup(struct auth_zones* az);
512 
513 /**
514  * Delete auth zones structure
515  */
516 void auth_zones_delete(struct auth_zones* az);
517 
518 /**
519  * Write auth zone data to file, in zonefile format.
520  */
521 int auth_zone_write_file(struct auth_zone* z, const char* fname);
522 
523 /**
524  * Use auth zones to lookup the answer to a query.
525  * The query is from the iterator.  And the auth zones attempts to provide
526  * the answer instead of going to the internet.
527  *
528  * @param az: auth zones structure.
529  * @param qinfo: query info to lookup.
530  * @param region: region to use to allocate the reply in.
531  * @param msg: reply is stored here (if one).
532  * @param fallback: if true, fallback to making a query to the internet.
533  * @param dp_nm: name of delegation point to look for.  This zone is used
534  *	to answer the query.
535  *	If the dp_nm is not found, fallback is set to true and false returned.
536  * @param dp_nmlen: length of dp_nm.
537  * @return 0: failure (an error of some sort, like servfail).
538  *         if 0 and fallback is true, fallback to the internet.
539  *         if 0 and fallback is false, like getting servfail.
540  *         If true, an answer is available.
541  */
542 int auth_zones_lookup(struct auth_zones* az, struct query_info* qinfo,
543 	struct regional* region, struct dns_msg** msg, int* fallback,
544 	uint8_t* dp_nm, size_t dp_nmlen);
545 
546 /**
547  * Answer query from auth zone.  Create authoritative answer.
548  * @param az: auth zones structure.
549  * @param env: the module environment.
550  * @param qinfo: query info (parsed).
551  * @param edns: edns info (parsed).
552  * @param buf: buffer with query ID and flags, also for reply.
553  * @param repinfo: reply information for a communication point.
554  * @param temp: temporary storage region.
555  * @return false if not answered
556  */
557 int auth_zones_downstream_answer(struct auth_zones* az, struct module_env* env,
558 	struct query_info* qinfo, struct edns_data* edns,
559 	struct comm_reply* repinfo, struct sldns_buffer* buf,
560 	struct regional* temp);
561 
562 /**
563  * Find the auth zone that is above the given qname.
564  * Return NULL when there is no auth_zone above the give name, otherwise
565  * returns the closest auth_zone above the qname that pertains to it.
566  * @param az: auth zones structure.
567  * @param name: query to look up for.
568  * @param name_len: length of name.
569  * @param dclass: class of zone to find.
570  * @return NULL or auth_zone that pertains to the query.
571  */
572 struct auth_zone* auth_zones_find_zone(struct auth_zones* az,
573 	uint8_t* name, size_t name_len, uint16_t dclass);
574 
575 /** find an auth zone by name (exact match by name or NULL returned) */
576 struct auth_zone* auth_zone_find(struct auth_zones* az, uint8_t* nm,
577 	size_t nmlen, uint16_t dclass);
578 
579 /** find an xfer zone by name (exact match by name or NULL returned) */
580 struct auth_xfer* auth_xfer_find(struct auth_zones* az, uint8_t* nm,
581 	size_t nmlen, uint16_t dclass);
582 
583 /** create an auth zone. returns wrlocked zone. caller must have wrlock
584  * on az. returns NULL on malloc failure */
585 struct auth_zone* auth_zone_create(struct auth_zones* az, uint8_t* nm,
586 	size_t nmlen, uint16_t dclass);
587 
588 /** set auth zone zonefile string. caller must have lock on zone */
589 int auth_zone_set_zonefile(struct auth_zone* z, char* zonefile);
590 
591 /** set auth zone fallback. caller must have lock on zone.
592  * fallbackstr is "yes" or "no". false on parse failure. */
593 int auth_zone_set_fallback(struct auth_zone* z, char* fallbackstr);
594 
595 /** see if the auth zone for the name can fallback
596  * @param az: auth zones
597  * @param nm: name of delegation point.
598  * @param nmlen: length of nm.
599  * @param dclass: class of zone to look for.
600  * @return true if fallback_enabled is true. false if not.
601  * if the zone does not exist, fallback is true (more lenient)
602  * also true if zone does not do upstream requests.
603  */
604 int auth_zones_can_fallback(struct auth_zones* az, uint8_t* nm, size_t nmlen,
605 	uint16_t dclass);
606 
607 /** process notify for auth zones.
608  * first checks the access list.  Then processes the notify. This starts
609  * the probe sequence or it notes the serial number (if any)
610  * @param az: auth zones structure.
611  * @param env: module env of the worker that is handling the notify. it will
612  * 	pick up the task probe (or transfer), unless already in progress by
613  * 	another worker.
614  * @param nm: name of the zone.  Uncompressed. from query.
615  * @param nmlen: length of name.
616  * @param dclass: class of zone.
617  * @param addr: source address of notify
618  * @param addrlen: length of addr.
619  * @param has_serial: if true, the notify has a serial attached.
620  * @param serial: the serial number, if has_serial is true.
621  * @param refused: is set to true on failure to note refused access.
622  * @return fail on failures (refused is false) and when access is
623  * 	denied (refused is true).  True when processed.
624  */
625 int auth_zones_notify(struct auth_zones* az, struct module_env* env,
626 	uint8_t* nm, size_t nmlen, uint16_t dclass,
627 	struct sockaddr_storage* addr, socklen_t addrlen, int has_serial,
628 	uint32_t serial, int* refused);
629 
630 /** process notify packet and read serial number from SOA.
631  * returns 0 if no soa record in the notify */
632 int auth_zone_parse_notify_serial(struct sldns_buffer* pkt, uint32_t *serial);
633 
634 /** for the zone and if not already going, starts the probe sequence.
635  * false if zone cannot be found.  This is like a notify arrived and was
636  * accepted for that zone. */
637 int auth_zones_startprobesequence(struct auth_zones* az,
638 	struct module_env* env, uint8_t* nm, size_t nmlen, uint16_t dclass);
639 
640 /** read auth zone from zonefile. caller must lock zone. false on failure */
641 int auth_zone_read_zonefile(struct auth_zone* z, struct config_file* cfg);
642 
643 /** find the apex SOA RRset, if it exists. NULL if no SOA RRset. */
644 struct auth_rrset* auth_zone_get_soa_rrset(struct auth_zone* z);
645 
646 /** find serial number of zone or false if none (no SOA record) */
647 int auth_zone_get_serial(struct auth_zone* z, uint32_t* serial);
648 
649 /** Find auth_zone SOA and populate the values in xfr(soa values). */
650 int xfr_find_soa(struct auth_zone* z, struct auth_xfer* xfr);
651 
652 /** compare auth_zones for sorted rbtree */
653 int auth_zone_cmp(const void* z1, const void* z2);
654 
655 /** compare auth_data for sorted rbtree */
656 int auth_data_cmp(const void* z1, const void* z2);
657 
658 /** compare auth_xfer for sorted rbtree */
659 int auth_xfer_cmp(const void* z1, const void* z2);
660 
661 /** Create auth_xfer structure.
662  * Caller must have wrlock on az. Returns locked xfer zone.
663  * @param az: zones structure.
664  * @param z: zone with name and class
665  * @return xfer zone or NULL
666  */
667 struct auth_xfer* auth_xfer_create(struct auth_zones* az, struct auth_zone* z);
668 
669 /**
670  * Set masters in auth xfer structure from config.
671  * @param list: pointer to start of list.  The malloced list is returned here.
672  * @param c: the config items to copy over.
673  * @param with_http: if true, http urls are also included, before the masters.
674  * @return false on failure.
675  */
676 int xfer_set_masters(struct auth_master** list, struct config_auth* c,
677 	int with_http);
678 
679 /** xfer nextprobe timeout callback, this is part of task_nextprobe */
680 void auth_xfer_timer(void* arg);
681 
682 /** callback for commpoint udp replies to task_probe */
683 int auth_xfer_probe_udp_callback(struct comm_point* c, void* arg, int err,
684         struct comm_reply* repinfo);
685 /** callback for task_transfer tcp connections */
686 int auth_xfer_transfer_tcp_callback(struct comm_point* c, void* arg, int err,
687         struct comm_reply* repinfo);
688 /** callback for task_transfer http connections */
689 int auth_xfer_transfer_http_callback(struct comm_point* c, void* arg, int err,
690         struct comm_reply* repinfo);
691 /** xfer probe timeout callback, part of task_probe */
692 void auth_xfer_probe_timer_callback(void* arg);
693 /** xfer transfer timeout callback, part of task_transfer */
694 void auth_xfer_transfer_timer_callback(void* arg);
695 /** mesh callback for task_probe on lookup of host names */
696 void auth_xfer_probe_lookup_callback(void* arg, int rcode,
697 	struct sldns_buffer* buf, enum sec_status sec, char* why_bogus,
698 	int was_ratelimited);
699 /** mesh callback for task_transfer on lookup of host names */
700 void auth_xfer_transfer_lookup_callback(void* arg, int rcode,
701 	struct sldns_buffer* buf, enum sec_status sec, char* why_bogus,
702 	int was_ratelimited);
703 
704 /*
705  * Compares two 32-bit serial numbers as defined in RFC1982.  Returns
706  * <0 if a < b, 0 if a == b, and >0 if a > b.  The result is undefined
707  * if a != b but neither is greater or smaller (see RFC1982 section
708  * 3.2.).
709  */
710 int compare_serial(uint32_t a, uint32_t b);
711 
712 /**
713  * Generate ZONEMD digest for the auth zone.
714  * @param z: the auth zone to digest.
715  * 	omits zonemd at apex and its RRSIG from the digest.
716  * @param scheme: the collation scheme to use.  Numbers as defined for ZONEMD.
717  * @param hashalgo: the hash algo, from the registry defined for ZONEMD type.
718  * @param hash: the result buffer.
719  * @param buflen: size of the result buffer, must be large enough. or the
720  * 	routine fails.
721  * @param resultlen: size of the hash in the result buffer of the result.
722  * @param region: temp region for allocs during canonicalisation.
723  * @param buf: temp buffer during canonicalisation.
724  * @param reason: failure reason, returns a string, NULL on success.
725  * @return false on failure.
726  */
727 int auth_zone_generate_zonemd_hash(struct auth_zone* z, int scheme,
728 	int hashalgo, uint8_t* hash, size_t buflen, size_t* resultlen,
729 	struct regional* region, struct sldns_buffer* buf, char** reason);
730 
731 /** ZONEMD scheme definitions */
732 #define ZONEMD_SCHEME_SIMPLE 1
733 
734 /** ZONEMD hash algorithm definition for SHA384 */
735 #define ZONEMD_ALGO_SHA384 1
736 /** ZONEMD hash algorithm definition for SHA512 */
737 #define ZONEMD_ALGO_SHA512 2
738 
739 /** returns true if a zonemd hash algo is supported */
740 int zonemd_hashalgo_supported(int hashalgo);
741 /** returns true if a zonemd scheme is supported */
742 int zonemd_scheme_supported(int scheme);
743 
744 /**
745  * Check ZONEMD digest for the auth zone.
746  * @param z: auth zone to digest.
747  * @param scheme: zonemd scheme.
748  * @param hashalgo: zonemd hash algorithm.
749  * @param hash: the hash to check.
750  * @param hashlen: length of hash buffer.
751  * @param region: temp region for allocs during canonicalisation.
752  * @param buf: temp buffer during canonicalisation.
753  * @param reason: string returned with failure reason.
754  * 	If the hash cannot be checked, but it is allowed, for unknown
755  * 	algorithms, the routine returns success, and the reason is nonNULL,
756  * 	with the allowance reason.
757  * @return false on failure.
758  */
759 int auth_zone_generate_zonemd_check(struct auth_zone* z, int scheme,
760 	int hashalgo, uint8_t* hash, size_t hashlen, struct regional* region,
761 	struct sldns_buffer* buf, char** reason);
762 
763 /**
764  * Perform ZONEMD checks and verification for the auth zone.
765  * This includes DNSSEC verification if applicable.
766  * @param z: auth zone to check.  Caller holds lock. wrlock.
767  * @param env: with temp region, buffer and config.
768  * @param mods: module stack for validator env.
769  * @param result: if not NULL, result string strdupped in here.
770  * @param offline: if true, there is no spawned lookup when online is needed.
771  * 	Those zones are skipped for ZONEMD checking.
772  * @param only_online: if true, only for ZONEMD that need online lookup
773  * 	of DNSKEY chain of trust are processed.
774  */
775 void auth_zone_verify_zonemd(struct auth_zone* z, struct module_env* env,
776 	struct module_stack* mods, char** result, int offline,
777 	int only_online);
778 
779 /** mesh callback for zonemd on lookup of dnskey */
780 void auth_zonemd_dnskey_lookup_callback(void* arg, int rcode,
781 	struct sldns_buffer* buf, enum sec_status sec, char* why_bogus,
782 	int was_ratelimited);
783 
784 /**
785  * Check the ZONEMD records that need online DNSSEC chain lookups,
786  * for them spawn the lookup process to get it checked out.
787  * Attaches the lookup process to the worker event base and mesh state.
788  * @param az: auth zones, every zones is checked.
789  * @param env: env of the worker where the task is attached.
790  */
791 void auth_zones_pickup_zonemd_verify(struct auth_zones* az,
792 	struct module_env* env);
793 
794 /** Get memory usage for auth zones. The routine locks and unlocks
795  * for reading. */
796 size_t auth_zones_get_mem(struct auth_zones* zones);
797 
798 /**
799  * Initial pick up of the auth zone nextprobe timeout and that turns
800  * into further zone transfer work, if any. Also sets the lease time.
801  * @param x: xfer structure, locked by caller.
802  * @param env: environment of the worker that picks up the task.
803  */
804 void auth_xfer_pickup_initial_zone(struct auth_xfer* x,
805 	struct module_env* env);
806 
807 /**
808  * Initial pick up of the auth zone, it sets the acquired time.
809  * @param z: the zone, write locked by caller.
810  * @param env: environment of the worker, with current time.
811  */
812 void auth_zone_pickup_initial_zone(struct auth_zone* z,
813 	struct module_env* env);
814 
815 /**
816  * Delete auth xfer structure
817  * @param xfr: delete this xfer and its tasks.
818  */
819 void auth_xfer_delete(struct auth_xfer* xfr);
820 
821 /**
822  * Disown tasks from the xfr that belong to this worker.
823  * Only tasks for the worker in question, the comm point and timer
824  * delete functions need to run in the thread of that worker to be
825  * able to delete the callback from the event base.
826  * @param xfr: xfr structure
827  * @param worker: the worker for which to stop tasks.
828  */
829 void xfr_disown_tasks(struct auth_xfer* xfr, struct worker* worker);
830 
831 #endif /* SERVICES_AUTHZONE_H */
832