2 * services/authzone.h - authoritative zone that is locally hosted.
4 * Copyright (c) 2017, NLnet Labs. All rights reserved.
6 * This software is open source.
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
12 * Redistributions of source code must retain the above copyright notice,
13 * this list of conditions and the following disclaimer.
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.
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.
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.
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.
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;
63 struct auth_nextprobe;
70 * Authoritative zones, shared.
73 /** lock on the authzone trees */
75 /** rbtree of struct auth_zone */
77 /** rbtree of struct auth_xfer */
79 /** do we have downstream enabled */
81 /** number of queries upstream */
83 /** number of queries downstream */
84 size_t num_query_down;
85 /** first auth zone containing rpz item in linked list */
86 struct auth_zone* rpz_first;
87 /** rw lock for rpz linked list, needed when iterating or editing linked
89 lock_rw_type rpz_lock;
93 * Auth zone. Authoritative data, that is fetched from instead of sending
94 * packets to the internet.
97 /** rbtree node, key is name and class */
100 /** zone name, in uncompressed wireformat */
102 /** length of zone name */
104 /** number of labels in zone name */
106 /** the class of this zone, in host byteorder.
107 * uses 'dclass' to not conflict with c++ keyword class. */
110 /** lock on the data in the structure
111 * For the node, parent, name, namelen, namelabs, dclass, you
112 * need to also hold the zones_tree lock to change them (or to
113 * delete this zone) */
116 /** auth data for this zone
117 * rbtree of struct auth_data */
120 /** zonefile name (or NULL for no zonefile) */
122 /** fallback to the internet on failure or ttl-expiry of auth zone */
123 int fallback_enabled;
124 /** the zone has expired (enabled by the xfer worker), fallback
125 * happens if that option is enabled. */
127 /** zone is a slave zone (it has masters) */
129 /** for downstream: this zone answers queries towards the downstream
132 /** for upstream: this zone answers queries that unbound intends to
137 /** zone has been deleted */
139 /** deletelist pointer, unused normally except during delete */
140 struct auth_zone* delete_next;
141 /* not protected by auth_zone lock, must be last items in struct */
142 /** next auth zone containing RPZ data, or NULL */
143 struct auth_zone* rpz_az_next;
144 /** previous auth zone containing RPZ data, or NULL */
145 struct auth_zone* rpz_az_prev;
149 * Auth data. One domain name, and the RRs to go with it.
152 /** rbtree node, key is name only */
156 /** length of name */
158 /** number of labels in name */
160 /** the data rrsets, with different types, linked list.
161 * if the list if NULL the node would be an empty non-terminal,
162 * but in this data structure such nodes that represent an empty
163 * non-terminal are not needed; they just don't exist.
165 struct auth_rrset* rrsets;
173 struct auth_rrset* next;
174 /** RR type in host byteorder */
176 /** RRset data item */
177 struct packed_rrset_data* data;
181 * Authoritative zone transfer structure.
182 * Create and destroy needs the auth_zones* biglock.
183 * The structure consists of different tasks. Each can be unowned (-1) or
184 * owner by a worker (worker-num). A worker can pick up a task and then do
185 * it. This means the events (timeouts, sockets) are for that worker.
187 * (move this to tasks).
188 * They don't have locks themselves, the worker (that owns it) uses it,
189 * also as part of callbacks, hence it has separate zonename pointers for
190 * lookup in the main zonetree. If the zone has no transfers, this
191 * structure is not created.
194 /** rbtree node, key is name and class */
197 /** lock on this structure, and on the workernum elements of the
198 * tasks. First hold the tree-lock in auth_zones, find the auth_xfer,
199 * lock this lock. Then a worker can reassign itself to fill up
201 * Once it has the task assigned to it, the worker can access the
202 * other elements of the task structure without a lock, because that
203 * is necessary for the eventloop and callbacks from that. */
204 lock_basic_type lock;
206 /** zone name, in uncompressed wireformat */
208 /** length of zone name */
210 /** number of labels in zone name */
212 /** the class of this zone, in host byteorder.
213 * uses 'dclass' to not conflict with c++ keyword class. */
216 /** task to wait for next-probe-timeout,
217 * once timeouted, see if a SOA probe is needed, or already
219 struct auth_nextprobe* task_nextprobe;
221 /** task for SOA probe. Check if the zone can be updated */
222 struct auth_probe* task_probe;
224 /** Task for transfer. Transferring and updating the zone. This
225 * includes trying (potentially) several upstream masters. Downloading
226 * and storing the zone */
227 struct auth_transfer* task_transfer;
229 /** a notify was received, but a zone transfer or probe was already
231 * However, the zone transfer could signal a newer serial number.
232 * The serial number of that notify is saved below. The transfer and
233 * probe tasks should check this once done to see if they need to
234 * restart the transfer task for the newer notify serial.
235 * Hold the lock to access this member (and the serial).
238 /** true if the notify_received has a serial number */
239 int notify_has_serial;
240 /** serial number of the notify */
241 uint32_t notify_serial;
242 /** the list of masters for checking notifies. This list is
243 * empty on start, and a copy of the list from the probe_task when
244 * it is done looking them up. */
245 struct auth_master* allow_notify_list;
247 /* protected by the lock on the structure, information about
248 * the loaded authority zone. */
249 /** is the zone currently considered expired? after expiry also older
250 * serial numbers are allowed (not just newer) */
252 /** do we have a zone (if 0, no zone data at all) */
255 /** current serial (from SOA), if we have no zone, 0 */
257 /** retry time (from SOA), time to wait with next_probe
258 * if no master responds */
260 /** refresh time (from SOA), time to wait with next_probe
261 * if everything is fine */
263 /** expiry time (from SOA), time until zone data is not considered
264 * valid any more, if no master responds within this time, either
265 * with the current zone or a new zone. */
268 /** zone lease start time (start+expiry is expiration time).
269 * this is renewed every SOA probe and transfer. On zone load
270 * from zonefile it is also set (with probe set soon to check) */
275 * The next probe task.
276 * This task consists of waiting for the probetimeout. It is a task because
277 * it needs an event in the eventtable. Once the timeout has passed, that
278 * worker can (potentially) become the auth_probe worker, or if another worker
279 * is already doing that, do nothing. Tasks becomes unowned.
280 * The probe worker, if it detects nothing has to be done picks up this task,
283 struct auth_nextprobe {
284 /* Worker pointer. NULL means unowned. */
285 struct worker* worker;
286 /* module env for this task */
287 struct module_env* env;
289 /** increasing backoff for failures */
291 /** Timeout for next probe (for SOA) */
293 /** timeout callback for next_probe or expiry(if that is sooner).
294 * it is on the worker's event_base */
295 struct comm_timer* timer;
300 * Send a SOA UDP query to see if the zone needs to be updated (or similar,
301 * potential, HTTP probe query) and check serial number.
302 * If yes, start the auth_transfer task. If no, make sure auth_nextprobe
303 * timeout wait task is running.
304 * Needs to be a task, because the UDP query needs an event entry.
305 * This task could also be started by eg. a NOTIFY being received, even though
306 * another worker is performing the nextprobe task (and that worker keeps
307 * waiting uninterrupted).
310 /* Worker pointer. NULL means unowned. */
311 struct worker* worker;
312 /* module env for this task */
313 struct module_env* env;
315 /** list of upstream masters for this zone, from config */
316 struct auth_master* masters;
318 /** for the hostname lookups, which master is current */
319 struct auth_master* lookup_target;
320 /** are we looking up A or AAAA, first A, then AAAA (if ip6 enabled) */
322 /** we only want to do lookups for making config work (for notify),
323 * don't proceed with UDP SOA probe queries */
325 /** we have seen a new lease this scan, because one of the masters
326 * replied with the current SOA serial version */
329 /** once notified, or the timeout has been reached. a scan starts. */
330 /** the scan specific target (notify source), or NULL if none */
331 struct auth_master* scan_specific;
332 /** scan tries all the upstream masters. the scan current target.
333 * or NULL if not working on sequential scan */
334 struct auth_master* scan_target;
335 /** if not NULL, the specific addr for the current master */
336 struct auth_addr* scan_addr;
338 /** dns id of packet in flight */
340 /** the SOA probe udp event.
341 * on the workers event base. */
342 struct comm_point* cp;
343 /** is the cp for ip6 or ip4 */
345 /** timeout for packets.
346 * on the workers event base. */
347 struct comm_timer* timer;
348 /** timeout in msec */
354 * Once done, make sure the nextprobe waiting task is running, whether done
355 * with failure or success. If failure, use shorter timeout for wait time.
357 struct auth_transfer {
358 /* Worker pointer. NULL means unowned. */
359 struct worker* worker;
360 /* module env for this task */
361 struct module_env* env;
363 /** xfer data that has been transferred, the data is applied
364 * once the transfer has completed correctly */
365 struct auth_chunk* chunks_first;
366 /** last element in chunks list (to append new data at the end) */
367 struct auth_chunk* chunks_last;
369 /** list of upstream masters for this zone, from config */
370 struct auth_master* masters;
372 /** for the hostname lookups, which master is current */
373 struct auth_master* lookup_target;
374 /** are we looking up A or AAAA, first A, then AAAA (if ip6 enabled) */
377 /** once notified, or the timeout has been reached. a scan starts. */
378 /** the scan specific target (notify source), or NULL if none */
379 struct auth_master* scan_specific;
380 /** scan tries all the upstream masters. the scan current target.
381 * or NULL if not working on sequential scan */
382 struct auth_master* scan_target;
383 /** what address we are scanning for the master, or NULL if the
384 * master is in IP format itself */
385 struct auth_addr* scan_addr;
386 /** the zone transfer in progress (or NULL if in scan). It is
387 * from this master */
388 struct auth_master* master;
390 /** failed ixfr transfer, retry with axfr (to the current master),
391 * the IXFR was 'REFUSED', 'SERVFAIL', 'NOTIMPL' or the contents of
392 * the IXFR did not apply cleanly (out of sync, delete of nonexistent
393 * data or add of duplicate data). Flag is cleared once the retry
394 * with axfr is done. */
396 /** we saw an ixfr-indicating timeout, count of them */
397 int ixfr_possible_timeout_count;
398 /** we are doing IXFR right now */
400 /** did we detect the current AXFR/IXFR serial number yet, 0 not yet,
401 * 1 we saw the first, 2 we saw the second, 3 must be last SOA in xfr*/
403 /** number of RRs scanned for AXFR/IXFR detection */
405 /** we are doing an IXFR but we detected an AXFR contents */
407 /** the serial number for the current AXFR/IXFR incoming reply,
408 * for IXFR, the outermost SOA records serial */
409 uint32_t incoming_xfr_serial;
411 /** dns id of AXFR query */
413 /** the transfer (TCP) to the master.
414 * on the workers event base. */
415 struct comm_point* cp;
416 /** timeout for the transfer.
417 * on the workers event base. */
418 struct comm_timer* timer;
421 /** list of addresses */
424 struct auth_addr* next;
426 struct sockaddr_storage addr;
431 /** auth zone master upstream, and the config settings for it */
433 /** next master in list */
434 struct auth_master* next;
435 /** master IP address (and port), or hostname, string */
437 /** for http, filename */
439 /** use HTTP for this master */
441 /** use IXFR for this master */
443 /** this is an allow notify member, the master can send notifies
444 * to us, but we don't send SOA probes, or zone transfer from it */
446 /** use ssl for channel */
448 /** the port number (for urls) */
450 /** if the host is a hostname, the list of resolved addrs, if any*/
451 struct auth_addr* list;
454 /** auth zone master zone transfer data chunk */
456 /** next chunk in list */
457 struct auth_chunk* next;
458 /** the data from this chunk, this is what was received.
459 * for an IXFR that means results from comm_net tcp actions,
460 * packets. also for an AXFR. For HTTP a zonefile chunk. */
462 /** length of allocated data */
467 * Create auth zones structure
469 struct auth_zones* auth_zones_create(void);
472 * Apply configuration to auth zones. Reads zonefiles.
473 * @param az: auth zones structure
474 * @param cfg: config to apply.
475 * @param setup: if true, also sets up values in the auth zones structure
476 * @param is_rpz: set to 1 if at least one RPZ zone is configured.
477 * @return false on failure.
479 int auth_zones_apply_cfg(struct auth_zones* az, struct config_file* cfg,
480 int setup, int* is_rpz);
482 /** initial pick up of worker timeouts, ties events to worker event loop
483 * @param az: auth zones structure
484 * @param env: worker env, of first worker that receives the events (if any)
487 void auth_xfer_pickup_initial(struct auth_zones* az, struct module_env* env);
490 * Cleanup auth zones. This removes all events from event bases.
491 * Stops the xfr tasks. But leaves zone data.
492 * @param az: auth zones structure.
494 void auth_zones_cleanup(struct auth_zones* az);
497 * Delete auth zones structure
499 void auth_zones_delete(struct auth_zones* az);
502 * Write auth zone data to file, in zonefile format.
504 int auth_zone_write_file(struct auth_zone* z, const char* fname);
507 * Use auth zones to lookup the answer to a query.
508 * The query is from the iterator. And the auth zones attempts to provide
509 * the answer instead of going to the internet.
511 * @param az: auth zones structure.
512 * @param qinfo: query info to lookup.
513 * @param region: region to use to allocate the reply in.
514 * @param msg: reply is stored here (if one).
515 * @param fallback: if true, fallback to making a query to the internet.
516 * @param dp_nm: name of delegation point to look for. This zone is used
517 * to answer the query.
518 * If the dp_nm is not found, fallback is set to true and false returned.
519 * @param dp_nmlen: length of dp_nm.
520 * @return 0: failure (an error of some sort, like servfail).
521 * if 0 and fallback is true, fallback to the internet.
522 * if 0 and fallback is false, like getting servfail.
523 * If true, an answer is available.
525 int auth_zones_lookup(struct auth_zones* az, struct query_info* qinfo,
526 struct regional* region, struct dns_msg** msg, int* fallback,
527 uint8_t* dp_nm, size_t dp_nmlen);
530 * Answer query from auth zone. Create authoritative answer.
531 * @param az: auth zones structure.
532 * @param env: the module environment.
533 * @param qinfo: query info (parsed).
534 * @param edns: edns info (parsed).
535 * @param buf: buffer with query ID and flags, also for reply.
536 * @param repinfo: reply information for a communication point.
537 * @param temp: temporary storage region.
538 * @return false if not answered
540 int auth_zones_answer(struct auth_zones* az, struct module_env* env,
541 struct query_info* qinfo, struct edns_data* edns,
542 struct comm_reply* repinfo, struct sldns_buffer* buf, struct regional* temp);
545 * Find the auth zone that is above the given qname.
546 * Return NULL when there is no auth_zone above the give name, otherwise
547 * returns the closest auth_zone above the qname that pertains to it.
548 * @param az: auth zones structure.
549 * @param name: query to look up for.
550 * @param name_len: length of name.
551 * @param dclass: class of zone to find.
552 * @return NULL or auth_zone that pertains to the query.
554 struct auth_zone* auth_zones_find_zone(struct auth_zones* az,
555 uint8_t* name, size_t name_len, uint16_t dclass);
557 /** find an auth zone by name (exact match by name or NULL returned) */
558 struct auth_zone* auth_zone_find(struct auth_zones* az, uint8_t* nm,
559 size_t nmlen, uint16_t dclass);
561 /** find an xfer zone by name (exact match by name or NULL returned) */
562 struct auth_xfer* auth_xfer_find(struct auth_zones* az, uint8_t* nm,
563 size_t nmlen, uint16_t dclass);
565 /** create an auth zone. returns wrlocked zone. caller must have wrlock
566 * on az. returns NULL on malloc failure */
567 struct auth_zone* auth_zone_create(struct auth_zones* az, uint8_t* nm,
568 size_t nmlen, uint16_t dclass);
570 /** set auth zone zonefile string. caller must have lock on zone */
571 int auth_zone_set_zonefile(struct auth_zone* z, char* zonefile);
573 /** set auth zone fallback. caller must have lock on zone.
574 * fallbackstr is "yes" or "no". false on parse failure. */
575 int auth_zone_set_fallback(struct auth_zone* z, char* fallbackstr);
577 /** see if the auth zone for the name can fallback
578 * @param az: auth zones
579 * @param nm: name of delegation point.
580 * @param nmlen: length of nm.
581 * @param dclass: class of zone to look for.
582 * @return true if fallback_enabled is true. false if not.
583 * if the zone does not exist, fallback is true (more lenient)
584 * also true if zone does not do upstream requests.
586 int auth_zones_can_fallback(struct auth_zones* az, uint8_t* nm, size_t nmlen,
589 /** process notify for auth zones.
590 * first checks the access list. Then processes the notify. This starts
591 * the probe sequence or it notes the serial number (if any)
592 * @param az: auth zones structure.
593 * @param env: module env of the worker that is handling the notify. it will
594 * pick up the task probe (or transfer), unless already in progress by
596 * @param nm: name of the zone. Uncompressed. from query.
597 * @param nmlen: length of name.
598 * @param dclass: class of zone.
599 * @param addr: source address of notify
600 * @param addrlen: length of addr.
601 * @param has_serial: if true, the notify has a serial attached.
602 * @param serial: the serial number, if has_serial is true.
603 * @param refused: is set to true on failure to note refused access.
604 * @return fail on failures (refused is false) and when access is
605 * denied (refused is true). True when processed.
607 int auth_zones_notify(struct auth_zones* az, struct module_env* env,
608 uint8_t* nm, size_t nmlen, uint16_t dclass,
609 struct sockaddr_storage* addr, socklen_t addrlen, int has_serial,
610 uint32_t serial, int* refused);
612 /** process notify packet and read serial number from SOA.
613 * returns 0 if no soa record in the notify */
614 int auth_zone_parse_notify_serial(struct sldns_buffer* pkt, uint32_t *serial);
616 /** for the zone and if not already going, starts the probe sequence.
617 * false if zone cannot be found. This is like a notify arrived and was
618 * accepted for that zone. */
619 int auth_zones_startprobesequence(struct auth_zones* az,
620 struct module_env* env, uint8_t* nm, size_t nmlen, uint16_t dclass);
622 /** read auth zone from zonefile. caller must lock zone. false on failure */
623 int auth_zone_read_zonefile(struct auth_zone* z, struct config_file* cfg);
625 /** find serial number of zone or false if none (no SOA record) */
626 int auth_zone_get_serial(struct auth_zone* z, uint32_t* serial);
628 /** compare auth_zones for sorted rbtree */
629 int auth_zone_cmp(const void* z1, const void* z2);
631 /** compare auth_data for sorted rbtree */
632 int auth_data_cmp(const void* z1, const void* z2);
634 /** compare auth_xfer for sorted rbtree */
635 int auth_xfer_cmp(const void* z1, const void* z2);
637 /** Create auth_xfer structure.
638 * Caller must have wrlock on az. Returns locked xfer zone.
639 * @param az: zones structure.
640 * @param z: zone with name and class
641 * @return xfer zone or NULL
643 struct auth_xfer* auth_xfer_create(struct auth_zones* az, struct auth_zone* z);
646 * Set masters in auth xfer structure from config.
647 * @param list: pointer to start of list. The malloced list is returned here.
648 * @param c: the config items to copy over.
649 * @param with_http: if true, http urls are also included, before the masters.
650 * @return false on failure.
652 int xfer_set_masters(struct auth_master** list, struct config_auth* c,
655 /** xfer nextprobe timeout callback, this is part of task_nextprobe */
656 void auth_xfer_timer(void* arg);
658 /** callback for commpoint udp replies to task_probe */
659 int auth_xfer_probe_udp_callback(struct comm_point* c, void* arg, int err,
660 struct comm_reply* repinfo);
661 /** callback for task_transfer tcp connections */
662 int auth_xfer_transfer_tcp_callback(struct comm_point* c, void* arg, int err,
663 struct comm_reply* repinfo);
664 /** callback for task_transfer http connections */
665 int auth_xfer_transfer_http_callback(struct comm_point* c, void* arg, int err,
666 struct comm_reply* repinfo);
667 /** xfer probe timeout callback, part of task_probe */
668 void auth_xfer_probe_timer_callback(void* arg);
669 /** xfer transfer timeout callback, part of task_transfer */
670 void auth_xfer_transfer_timer_callback(void* arg);
671 /** mesh callback for task_probe on lookup of host names */
672 void auth_xfer_probe_lookup_callback(void* arg, int rcode,
673 struct sldns_buffer* buf, enum sec_status sec, char* why_bogus,
674 int was_ratelimited);
675 /** mesh callback for task_transfer on lookup of host names */
676 void auth_xfer_transfer_lookup_callback(void* arg, int rcode,
677 struct sldns_buffer* buf, enum sec_status sec, char* why_bogus,
678 int was_ratelimited);
681 * Compares two 32-bit serial numbers as defined in RFC1982. Returns
682 * <0 if a < b, 0 if a == b, and >0 if a > b. The result is undefined
683 * if a != b but neither is greater or smaller (see RFC1982 section
686 int compare_serial(uint32_t a, uint32_t b);
688 #endif /* SERVICES_AUTHZONE_H */