1 /*
2  * util/module.h - DNS handling module interface
3  *
4  * Copyright (c) 2007, 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 interface for DNS handling modules.
40  *
41  * The module interface uses the DNS modules as state machines.  The
42  * state machines are activated in sequence to operate on queries.  Once
43  * they are done, the reply is passed back.  In the usual setup the mesh
44  * is the caller of the state machines and once things are done sends replies
45  * and invokes result callbacks.
46  *
47  * The module provides a number of functions, listed in the module_func_block.
48  * The module is inited and destroyed and memory usage queries, for the
49  * module as a whole, for entire-module state (such as a cache).  And per-query
50  * functions are called, operate to move the state machine and cleanup of
51  * the per-query state.
52  *
53  * Most per-query state should simply be allocated in the query region.
54  * This is destroyed at the end of the query.
55  *
56  * The module environment contains services and information and caches
57  * shared by the modules and the rest of the system.  It also contains
58  * function pointers for module-specific tasks (like sending queries).
59  *
60  * *** Example module calls for a normal query
61  *
62  * In this example, the query does not need recursion, all the other data
63  * can be found in the cache.  This makes the example shorter.
64  *
65  * At the start of the program the iterator module is initialised.
66  * The iterator module sets up its global state, such as donotquery lists
67  * and private address trees.
68  *
69  * A query comes in, and a mesh entry is created for it.  The mesh
70  * starts the resolution process.  The validator module is the first
71  * in the list of modules, and it is started on this new query.  The
72  * operate() function is called.  The validator decides it needs not do
73  * anything yet until there is a result and returns wait_module, that
74  * causes the next module in the list to be started.
75  *
76  * The next module is the iterator.  It is started on the passed query and
77  * decides to perform a lookup.  For this simple example, the delegation
78  * point information is available, and all the iterator wants to do is
79  * send a UDP query.  The iterator uses env.send_query() to send the
80  * query.  Then the iterator suspends (returns from the operate call).
81  *
82  * When the UDP reply comes back (and on errors and timeouts), the
83  * operate function is called for the query, on the iterator module,
84  * with the event that there is a reply.  The iterator decides that this
85  * is enough, the work is done.  It returns the value finished from the
86  * operate call, which causes the previous module to be started.
87  *
88  * The previous module, the validator module, is started with the event
89  * that the iterator module is done.  The validator decides to validate
90  * the query.  Once it is done (which could take recursive lookups, but
91  * in this example no recursive lookups are needed), it returns from the
92  * operate function with finished.
93  *
94  * There is no previous module from the validator module, and the mesh
95  * takes this to mean that the query is finally done.  The mesh invokes
96  * callbacks and sends packets to queriers.
97  *
98  * If other modules had been waiting (recursively) on the answer to this
99  * query, then the mesh will tell them about it.  It calls the inform_super
100  * routine on all the waiting modules, and once that is done it calls all of
101  * them with the operate() call.  During inform_super the query that is done
102  * still exists and information can be copied from it (but the module should
103  * not really re-entry codepoints and services).  During the operate call
104  * the modules can use stored state to continue operation with the results.
105  * (network buffers are used to contain the answer packet during the
106  * inform_super phase, but after that the network buffers will be cleared
107  * of their contents so that other tasks can be performed).
108  *
109  * *** Example module calls for recursion
110  *
111  * A module is called in operate, and it decides that it wants to perform
112  * recursion.  That is, it wants the full state-machine-list to operate on
113  * a different query.  It calls env.attach_sub() to create a new query state.
114  * The routine returns the newly created state, and potentially the module
115  * can edit the module-states for the newly created query (i.e. pass along
116  * some information, like delegation points).  The module then suspends,
117  * returns from the operate routine.
118  *
119  * The mesh meanwhile will have the newly created query (or queries) on
120  * a waiting list, and will call operate() on this query (or queries).
121  * It starts again at the start of the module list for them.  The query
122  * (or queries) continue to operate their state machines, until they are
123  * done.  When they are done the mesh calls inform_super on the module that
124  * wanted the recursion.  After that the mesh calls operate() on the module
125  * that wanted to do the recursion, and during this phase the module could,
126  * for example, decide to create more recursions.
127  *
128  * If the module decides it no longer wants the recursive information
129  * it can call detach_subs.  Those queries will still run to completion,
130  * potentially filling the cache with information.  Inform_super is not
131  * called any more.
132  *
133  * The iterator module will fetch items from the cache, so a recursion
134  * attempt may complete very quickly if the item is in cache.  The calling
135  * module has to wait for completion or eventual timeout.  A recursive query
136  * that times out returns a servfail rcode (servfail is also returned for
137  * other errors during the lookup).
138  *
139  * Results are passed in the qstate, the rcode member is used to pass
140  * errors without requiring memory allocation, so that the code can continue
141  * in out-of-memory conditions.  If the rcode member is 0 (NOERROR) then
142  * the dns_msg entry contains a filled out message.  This message may
143  * also contain an rcode that is nonzero, but in this case additional
144  * information (query, additional) can be passed along.
145  *
146  * The rcode and dns_msg are used to pass the result from the the rightmost
147  * module towards the leftmost modules and then towards the user.
148  *
149  * If you want to avoid recursion-cycles where queries need other queries
150  * that need the first one, use detect_cycle() to see if that will happen.
151  *
152  */
153 
154 #ifndef UTIL_MODULE_H
155 #define UTIL_MODULE_H
156 #include "util/storage/lruhash.h"
157 #include "util/data/msgreply.h"
158 #include "util/data/msgparse.h"
159 struct sldns_buffer;
160 struct alloc_cache;
161 struct rrset_cache;
162 struct key_cache;
163 struct config_file;
164 struct slabhash;
165 struct query_info;
166 struct edns_data;
167 struct regional;
168 struct worker;
169 struct comm_base;
170 struct auth_zones;
171 struct outside_network;
172 struct module_qstate;
173 struct ub_randstate;
174 struct mesh_area;
175 struct mesh_state;
176 struct val_anchors;
177 struct val_neg_cache;
178 struct iter_forwards;
179 struct iter_hints;
180 struct respip_set;
181 struct respip_client_info;
182 struct respip_addr_info;
183 
184 /** Maximum number of modules in operation */
185 #define MAX_MODULE 16
186 
187 /** Maximum number of known edns options */
188 #define MAX_KNOWN_EDNS_OPTS 256
189 
190 enum inplace_cb_list_type {
191 	/* Inplace callbacks for when a resolved reply is ready to be sent to the
192 	 * front.*/
193 	inplace_cb_reply = 0,
194 	/* Inplace callbacks for when a reply is given from the cache. */
195 	inplace_cb_reply_cache,
196 	/* Inplace callbacks for when a reply is given with local data
197 	 * (or Chaos reply). */
198 	inplace_cb_reply_local,
199 	/* Inplace callbacks for when the reply is servfail. */
200 	inplace_cb_reply_servfail,
201 	/* Inplace callbacks for when a query is ready to be sent to the back.*/
202 	inplace_cb_query,
203 	/* Inplace callback for when a reply is received from the back. */
204 	inplace_cb_query_response,
205 	/* Inplace callback for when EDNS is parsed on a reply received from the
206 	 * back. */
207 	inplace_cb_edns_back_parsed,
208 	/* Total number of types. Used for array initialization.
209 	 * Should always be last. */
210 	inplace_cb_types_total
211 };
212 
213 
214 /** Known edns option. Can be populated during modules' init. */
215 struct edns_known_option {
216 	/** type of this edns option */
217 	uint16_t opt_code;
218 	/** whether the option needs to bypass the cache stage */
219 	int bypass_cache_stage;
220 	/** whether the option needs mesh aggregation */
221 	int no_aggregation;
222 };
223 
224 /**
225  * Inplace callback list of registered routines to be called.
226  */
227 struct inplace_cb {
228 	/** next in list */
229 	struct inplace_cb* next;
230 	/** Inplace callback routine */
231 	void* cb;
232 	void* cb_arg;
233 	/** module id */
234 	int id;
235 };
236 
237 /**
238  * Inplace callback function called before replying.
239  * Called as func(qinfo, qstate, rep, rcode, edns, opt_list_out, repinfo,
240  *                region, id, python_callback)
241  * Where:
242  *	qinfo: the query info.
243  *	qstate: the module state. NULL when calling before the query reaches the
244  *		mesh states.
245  *	rep: reply_info. Could be NULL.
246  *	rcode: the return code.
247  *	edns: the edns_data of the reply. When qstate is NULL, it is also used as
248  *		the edns input.
249  *	opt_list_out: the edns options list for the reply.
250  *	repinfo: reply information for a communication point. NULL when calling
251  *		during the mesh states; the same could be found from
252  *		qstate->mesh_info->reply_list.
253  *	region: region to store data.
254  *	id: module id.
255  *	python_callback: only used for registering a python callback function.
256  */
257 typedef int inplace_cb_reply_func_type(struct query_info* qinfo,
258 	struct module_qstate* qstate, struct reply_info* rep, int rcode,
259 	struct edns_data* edns, struct edns_option** opt_list_out,
260 	struct comm_reply* repinfo, struct regional* region,
261 	struct timeval* start_time, int id, void* callback);
262 
263 /**
264  * Inplace callback function called before sending the query to a nameserver.
265  * Called as func(qinfo, flags, qstate, addr, addrlen, zone, zonelen, region,
266  *                id, python_callback)
267  * Where:
268  *	qinfo: query info.
269  *	flags: flags of the query.
270  *	qstate: query state.
271  *	addr: to which server to send the query.
272  *	addrlen: length of addr.
273  *	zone: name of the zone of the delegation point. wireformat dname.
274  *		This is the delegation point name for which the server is deemed
275  *		authoritative.
276  *	zonelen: length of zone.
277  *	region: region to store data.
278  *	id: module id.
279  *	python_callback: only used for registering a python callback function.
280  */
281 typedef int inplace_cb_query_func_type(struct query_info* qinfo, uint16_t flags,
282 	struct module_qstate* qstate, struct sockaddr_storage* addr,
283 	socklen_t addrlen, uint8_t* zone, size_t zonelen, struct regional* region,
284 	int id, void* callback);
285 
286 /**
287  * Inplace callback function called after parsing edns on query reply.
288  * Called as func(qstate, id, cb_args)
289  * Where:
290  *	qstate: the query state.
291  *	id: module id.
292  *	cb_args: argument passed when registering callback.
293  */
294 typedef int inplace_cb_edns_back_parsed_func_type(struct module_qstate* qstate,
295 	int id, void* cb_args);
296 
297 /**
298  * Inplace callback function called after parsing query response.
299  * Called as func(qstate, response, id, cb_args)
300  * Where:
301  *	qstate: the query state.
302  *	response: query response.
303  *	id: module id.
304  *	cb_args: argument passed when registering callback.
305  */
306 typedef int inplace_cb_query_response_func_type(struct module_qstate* qstate,
307 	struct dns_msg* response, int id, void* cb_args);
308 
309 /**
310  * Function called when looking for (expired) cached answers during the serve
311  * expired logic.
312  * Called as func(qstate, lookup_qinfo)
313  * Where:
314  *	qstate: the query state.
315  *	lookup_qinfo: the qinfo to lookup for.
316  */
317 typedef struct dns_msg* serve_expired_lookup_func_type(
318 	struct module_qstate* qstate, struct query_info* lookup_qinfo);
319 
320 /**
321  * Module environment.
322  * Services and data provided to the module.
323  */
324 struct module_env {
325 	/* --- data --- */
326 	/** config file with config options */
327 	struct config_file* cfg;
328 	/** shared message cache */
329 	struct slabhash* msg_cache;
330 	/** shared rrset cache */
331 	struct rrset_cache* rrset_cache;
332 	/** shared infrastructure cache (edns, lameness) */
333 	struct infra_cache* infra_cache;
334 	/** shared key cache */
335 	struct key_cache* key_cache;
336 
337 	/* --- services --- */
338 	/**
339 	 * Send serviced DNS query to server. UDP/TCP and EDNS is handled.
340 	 * operate() should return with wait_reply. Later on a callback
341 	 * will cause operate() to be called with event timeout or reply.
342 	 * The time until a timeout is calculated from roundtrip timing,
343 	 * several UDP retries are attempted.
344 	 * @param qinfo: query info.
345 	 * @param flags: host order flags word, with opcode and CD bit.
346 	 * @param dnssec: if set, EDNS record will have bits set.
347 	 *	If EDNS_DO bit is set, DO bit is set in EDNS records.
348 	 *	If BIT_CD is set, CD bit is set in queries with EDNS records.
349 	 * @param want_dnssec: if set, the validator wants DNSSEC.  Without
350 	 * 	EDNS, the answer is likely to be useless for this domain.
351 	 * @param nocaps: do not use caps_for_id, use the qname as given.
352 	 *	(ignored if caps_for_id is disabled).
353 	 * @param addr: where to.
354 	 * @param addrlen: length of addr.
355 	 * @param zone: delegation point name.
356 	 * @param zonelen: length of zone name.
357 	 * @param tcp_upstream: use TCP for upstream queries.
358 	 * @param ssl_upstream: use SSL for upstream queries.
359 	 * @param tls_auth_name: if ssl_upstream, use this name with TLS
360 	 * 	authentication.
361 	 * @param q: which query state to reactivate upon return.
362 	 * @return: false on failure (memory or socket related). no query was
363 	 *	sent. Or returns an outbound entry with qsent and qstate set.
364 	 *	This outbound_entry will be used on later module invocations
365 	 *	that involve this query (timeout, error or reply).
366 	 */
367 	struct outbound_entry* (*send_query)(struct query_info* qinfo,
368 		uint16_t flags, int dnssec, int want_dnssec, int nocaps,
369 		struct sockaddr_storage* addr, socklen_t addrlen,
370 		uint8_t* zone, size_t zonelen, int tcp_upstream, int ssl_upstream,
371 		char* tls_auth_name, struct module_qstate* q);
372 
373 	/**
374 	 * Detach-subqueries.
375 	 * Remove all sub-query references from this query state.
376 	 * Keeps super-references of those sub-queries correct.
377 	 * Updates stat items in mesh_area structure.
378 	 * @param qstate: used to find mesh state.
379 	 */
380 	void (*detach_subs)(struct module_qstate* qstate);
381 
382 	/**
383 	 * Attach subquery.
384 	 * Creates it if it does not exist already.
385 	 * Keeps sub and super references correct.
386 	 * Updates stat items in mesh_area structure.
387 	 * Pass if it is priming query or not.
388 	 * return:
389 	 * o if error (malloc) happened.
390 	 * o need to initialise the new state (module init; it is a new state).
391 	 *   so that the next run of the query with this module is successful.
392 	 * o no init needed, attachment successful.
393 	 *
394 	 * @param qstate: the state to find mesh state, and that wants to
395 	 * 	receive the results from the new subquery.
396 	 * @param qinfo: what to query for (copied).
397 	 * @param qflags: what flags to use (RD, CD flag or not).
398 	 * @param prime: if it is a (stub) priming query.
399 	 * @param valrec: validation lookup recursion, does not need validation
400 	 * @param newq: If the new subquery needs initialisation, it is
401 	 * 	returned, otherwise NULL is returned.
402 	 * @return: false on error, true if success (and init may be needed).
403 	 */
404 	int (*attach_sub)(struct module_qstate* qstate,
405 		struct query_info* qinfo, uint16_t qflags, int prime,
406 		int valrec, struct module_qstate** newq);
407 
408 	/**
409 	 * Add detached query.
410 	 * Creates it if it does not exist already.
411 	 * Does not make super/sub references.
412 	 * Performs a cycle detection - for double check - and fails if there is
413 	 * 	one.
414 	 * Updates stat items in mesh_area structure.
415 	 * Pass if it is priming query or not.
416 	 * return:
417 	 * 	o if error (malloc) happened.
418 	 * 	o need to initialise the new state (module init; it is a new state).
419 	 * 	  so that the next run of the query with this module is successful.
420 	 * 	o no init needed, attachment successful.
421 	 * 	o added subquery, created if it did not exist already.
422 	 *
423 	 * @param qstate: the state to find mesh state, and that wants to receive
424 	 * 	the results from the new subquery.
425 	 * @param qinfo: what to query for (copied).
426 	 * @param qflags: what flags to use (RD / CD flag or not).
427 	 * @param prime: if it is a (stub) priming query.
428 	 * @param valrec: if it is a validation recursion query (lookup of key, DS).
429 	 * @param newq: If the new subquery needs initialisation, it is returned,
430 	 * 	otherwise NULL is returned.
431 	 * @param sub: The added mesh state, created if it did not exist already.
432 	 * @return: false on error, true if success (and init may be needed).
433 	 */
434 	int (*add_sub)(struct module_qstate* qstate,
435 		struct query_info* qinfo, uint16_t qflags, int prime,
436 		int valrec, struct module_qstate** newq,
437 		struct mesh_state** sub);
438 
439 	/**
440 	 * Kill newly attached sub. If attach_sub returns newq for
441 	 * initialisation, but that fails, then this routine will cleanup and
442 	 * delete the freshly created sub.
443 	 * @param newq: the new subquery that is no longer needed.
444 	 * 	It is removed.
445 	 */
446 	void (*kill_sub)(struct module_qstate* newq);
447 
448 	/**
449 	 * Detect if adding a dependency for qstate on name,type,class will
450 	 * create a dependency cycle.
451 	 * @param qstate: given mesh querystate.
452 	 * @param qinfo: query info for dependency.
453 	 * @param flags: query flags of dependency, RD/CD flags.
454 	 * @param prime: if dependency is a priming query or not.
455 	 * @param valrec: validation lookup recursion, does not need validation
456 	 * @return true if the name,type,class exists and the given
457 	 * 	qstate mesh exists as a dependency of that name. Thus
458 	 * 	if qstate becomes dependent on name,type,class then a
459 	 * 	cycle is created.
460 	 */
461 	int (*detect_cycle)(struct module_qstate* qstate,
462 		struct query_info* qinfo, uint16_t flags, int prime,
463 		int valrec);
464 
465 	/** region for temporary usage. May be cleared after operate() call. */
466 	struct regional* scratch;
467 	/** buffer for temporary usage. May be cleared after operate() call. */
468 	struct sldns_buffer* scratch_buffer;
469 	/** internal data for daemon - worker thread. */
470 	struct worker* worker;
471 	/** the worker event base */
472 	struct comm_base* worker_base;
473 	/** the outside network */
474 	struct outside_network* outnet;
475 	/** mesh area with query state dependencies */
476 	struct mesh_area* mesh;
477 	/** allocation service */
478 	struct alloc_cache* alloc;
479 	/** random table to generate random numbers */
480 	struct ub_randstate* rnd;
481 	/** time in seconds, converted to integer */
482 	time_t* now;
483 	/** time in microseconds. Relatively recent. */
484 	struct timeval* now_tv;
485 	/** is validation required for messages, controls client-facing
486 	 * validation status (AD bits) and servfails */
487 	int need_to_validate;
488 	/** trusted key storage; these are the configured keys, if not NULL,
489 	 * otherwise configured by validator. These are the trust anchors,
490 	 * and are not primed and ready for validation, but on the bright
491 	 * side, they are read only memory, thus no locks and fast. */
492 	struct val_anchors* anchors;
493 	/** negative cache, configured by the validator. if not NULL,
494 	 * contains NSEC record lookup trees. */
495 	struct val_neg_cache* neg_cache;
496 	/** the 5011-probe timer (if any) */
497 	struct comm_timer* probe_timer;
498 	/** auth zones */
499 	struct auth_zones* auth_zones;
500 	/** Mapping of forwarding zones to targets.
501 	 * iterator forwarder information. per-thread, created by worker */
502 	struct iter_forwards* fwds;
503 	/**
504 	 * iterator forwarder information. per-thread, created by worker.
505 	 * The hints -- these aren't stored in the cache because they don't
506 	 * expire. The hints are always used to "prime" the cache. Note
507 	 * that both root hints and stub zone "hints" are stored in this
508 	 * data structure.
509 	 */
510 	struct iter_hints* hints;
511 	/** module specific data. indexed by module id. */
512 	void* modinfo[MAX_MODULE];
513 
514 	/* Shared linked list of inplace callback functions */
515 	struct inplace_cb* inplace_cb_lists[inplace_cb_types_total];
516 
517 	/**
518 	 * Shared array of known edns options (size MAX_KNOWN_EDNS_OPTS).
519 	 * Filled by edns literate modules during init.
520 	 */
521 	struct edns_known_option* edns_known_options;
522 	/* Number of known edns options */
523 	size_t edns_known_options_num;
524 	/** EDNS client string information */
525 	struct edns_strings* edns_strings;
526 
527 	/* Make every mesh state unique, do not aggregate mesh states. */
528 	int unique_mesh;
529 };
530 
531 /**
532  * External visible states of the module state machine
533  * Modules may also have an internal state.
534  * Modules are supposed to run to completion or until blocked.
535  */
536 enum module_ext_state {
537 	/** initial state - new query */
538 	module_state_initial = 0,
539 	/** waiting for reply to outgoing network query */
540 	module_wait_reply,
541 	/** module is waiting for another module */
542 	module_wait_module,
543 	/** module is waiting for another module; that other is restarted */
544 	module_restart_next,
545 	/** module is waiting for sub-query */
546 	module_wait_subquery,
547 	/** module could not finish the query */
548 	module_error,
549 	/** module is finished with query */
550 	module_finished
551 };
552 
553 /**
554  * Events that happen to modules, that start or wakeup modules.
555  */
556 enum module_ev {
557 	/** new query */
558 	module_event_new = 0,
559 	/** query passed by other module */
560 	module_event_pass,
561 	/** reply inbound from server */
562 	module_event_reply,
563 	/** no reply, timeout or other error */
564 	module_event_noreply,
565 	/** reply is there, but capitalisation check failed */
566 	module_event_capsfail,
567 	/** next module is done, and its reply is awaiting you */
568 	module_event_moddone,
569 	/** error */
570 	module_event_error
571 };
572 
573 /**
574  * Linked list of sockaddrs
575  * May be allocated such that only 'len' bytes of addr exist for the structure.
576  */
577 struct sock_list {
578 	/** next in list */
579 	struct sock_list* next;
580 	/** length of addr */
581 	socklen_t len;
582 	/** sockaddr */
583 	struct sockaddr_storage addr;
584 };
585 
586 struct respip_action_info;
587 
588 /**
589  * Struct to hold relevant data for serve expired
590  */
591 struct serve_expired_data {
592 	struct comm_timer* timer;
593 	serve_expired_lookup_func_type* get_cached_answer;
594 };
595 
596 /**
597  * Module state, per query.
598  */
599 struct module_qstate {
600 	/** which query is being answered: name, type, class */
601 	struct query_info qinfo;
602 	/** flags uint16 from query */
603 	uint16_t query_flags;
604 	/** if this is a (stub or root) priming query (with hints) */
605 	int is_priming;
606 	/** if this is a validation recursion query that does not get
607 	 * validation itself */
608 	int is_valrec;
609 
610 	/** comm_reply contains server replies */
611 	struct comm_reply* reply;
612 	/** the reply message, with message for client and calling module */
613 	struct dns_msg* return_msg;
614 	/** the rcode, in case of error, instead of a reply message */
615 	int return_rcode;
616 	/** origin of the reply (can be NULL from cache, list for cnames) */
617 	struct sock_list* reply_origin;
618 	/** IP blacklist for queries */
619 	struct sock_list* blacklist;
620 	/** region for this query. Cleared when query process finishes. */
621 	struct regional* region;
622 	/** failure reason information if val-log-level is high */
623 	struct config_strlist* errinf;
624 
625 	/** which module is executing */
626 	int curmod;
627 	/** module states */
628 	enum module_ext_state ext_state[MAX_MODULE];
629 	/** module specific data for query. indexed by module id. */
630 	void* minfo[MAX_MODULE];
631 	/** environment for this query */
632 	struct module_env* env;
633 	/** mesh related information for this query */
634 	struct mesh_state* mesh_info;
635 	/** how many seconds before expiry is this prefetched (0 if not) */
636 	time_t prefetch_leeway;
637 	/** serve expired data */
638 	struct serve_expired_data* serve_expired_data;
639 
640 	/** incoming edns options from the front end */
641 	struct edns_option* edns_opts_front_in;
642 	/** outgoing edns options to the back end */
643 	struct edns_option* edns_opts_back_out;
644 	/** incoming edns options from the back end */
645 	struct edns_option* edns_opts_back_in;
646 	/** outgoing edns options to the front end */
647 	struct edns_option* edns_opts_front_out;
648 	/** whether modules should answer from the cache */
649 	int no_cache_lookup;
650 	/** whether modules should store answer in the cache */
651 	int no_cache_store;
652 	/** whether to refetch a fresh answer on finishing this state*/
653 	int need_refetch;
654 	/** whether the query (or a subquery) was ratelimited */
655 	int was_ratelimited;
656 
657 	/**
658 	 * Attributes of clients that share the qstate that may affect IP-based
659 	 * actions.
660 	 */
661 	struct respip_client_info* client_info;
662 
663 	/** Extended result of response-ip action processing, mainly
664 	 *  for logging purposes. */
665 	struct respip_action_info* respip_action_info;
666 
667 	/** whether the reply should be dropped */
668 	int is_drop;
669 };
670 
671 /**
672  * Module functionality block
673  */
674 struct module_func_block {
675 	/** text string name of module */
676 	const char* name;
677 
678 	/**
679 	 * init the module. Called once for the global state.
680 	 * This is the place to apply settings from the config file.
681 	 * @param env: module environment.
682 	 * @param id: module id number.
683 	 * return: 0 on error
684 	 */
685 	int (*init)(struct module_env* env, int id);
686 
687 	/**
688 	 * de-init, delete, the module. Called once for the global state.
689 	 * @param env: module environment.
690 	 * @param id: module id number.
691 	 */
692 	void (*deinit)(struct module_env* env, int id);
693 
694 	/**
695 	 * accept a new query, or work further on existing query.
696 	 * Changes the qstate->ext_state to be correct on exit.
697 	 * @param ev: event that causes the module state machine to
698 	 *	(re-)activate.
699 	 * @param qstate: the query state.
700 	 *	Note that this method is not allowed to change the
701 	 *	query state 'identity', that is query info, qflags,
702 	 *	and priming status.
703 	 *	Attach a subquery to get results to a different query.
704 	 * @param id: module id number that operate() is called on.
705 	 * @param outbound: if not NULL this event is due to the reply/timeout
706 	 *	or error on this outbound query.
707 	 * @return: if at exit the ext_state is:
708 	 *	o wait_module: next module is started. (with pass event).
709 	 *	o error or finished: previous module is resumed.
710 	 *	o otherwise it waits until that event happens (assumes
711 	 *	  the service routine to make subrequest or send message
712 	 *	  have been called.
713 	 */
714 	void (*operate)(struct module_qstate* qstate, enum module_ev event,
715 		int id, struct outbound_entry* outbound);
716 
717 	/**
718 	 * inform super querystate about the results from this subquerystate.
719 	 * Is called when the querystate is finished.  The method invoked is
720 	 * the one from the current module active in the super querystate.
721 	 * @param qstate: the query state that is finished.
722 	 *	Examine return_rcode and return_reply in the qstate.
723 	 * @param id: module id for this module.
724 	 *	This coincides with the current module for the super qstate.
725 	 * @param super: the super querystate that needs to be informed.
726 	 */
727 	void (*inform_super)(struct module_qstate* qstate, int id,
728 		struct module_qstate* super);
729 
730 	/**
731 	 * clear module specific data
732 	 */
733 	void (*clear)(struct module_qstate* qstate, int id);
734 
735 	/**
736 	 * How much memory is the module specific data using.
737 	 * @param env: module environment.
738 	 * @param id: the module id.
739 	 * @return the number of bytes that are alloced.
740 	 */
741 	size_t (*get_mem)(struct module_env* env, int id);
742 };
743 
744 /**
745  * Debug utility: module external qstate to string
746  * @param s: the state value.
747  * @return descriptive string.
748  */
749 const char* strextstate(enum module_ext_state s);
750 
751 /**
752  * Debug utility: module event to string
753  * @param e: the module event value.
754  * @return descriptive string.
755  */
756 const char* strmodulevent(enum module_ev e);
757 
758 /**
759  * Initialize the edns known options by allocating the required space.
760  * @param env: the module environment.
761  * @return false on failure (no memory).
762  */
763 int edns_known_options_init(struct module_env* env);
764 
765 /**
766  * Free the allocated space for the known edns options.
767  * @param env: the module environment.
768  */
769 void edns_known_options_delete(struct module_env* env);
770 
771 /**
772  * Register a known edns option. Overwrite the flags if it is already
773  * registered. Used before creating workers to register known edns options.
774  * @param opt_code: the edns option code.
775  * @param bypass_cache_stage: whether the option interacts with the cache.
776  * @param no_aggregation: whether the option implies more specific
777  *	aggregation.
778  * @param env: the module environment.
779  * @return true on success, false on failure (registering more options than
780  *	allowed or trying to register after the environment is copied to the
781  *	threads.)
782  */
783 int edns_register_option(uint16_t opt_code, int bypass_cache_stage,
784 	int no_aggregation, struct module_env* env);
785 
786 /**
787  * Register an inplace callback function.
788  * @param cb: pointer to the callback function.
789  * @param type: inplace callback type.
790  * @param cbarg: argument for the callback function, or NULL.
791  * @param env: the module environment.
792  * @param id: module id.
793  * @return true on success, false on failure (out of memory or trying to
794  *	register after the environment is copied to the threads.)
795  */
796 int
797 inplace_cb_register(void* cb, enum inplace_cb_list_type type, void* cbarg,
798 	struct module_env* env, int id);
799 
800 /**
801  * Delete callback for specified type and module id.
802  * @param env: the module environment.
803  * @param type: inplace callback type.
804  * @param id: module id.
805  */
806 void
807 inplace_cb_delete(struct module_env* env, enum inplace_cb_list_type type,
808 	int id);
809 
810 /**
811  * Delete all the inplace callback linked lists.
812  * @param env: the module environment.
813  */
814 void inplace_cb_lists_delete(struct module_env* env);
815 
816 /**
817  * Check if an edns option is known.
818  * @param opt_code: the edns option code.
819  * @param env: the module environment.
820  * @return pointer to registered option if the edns option is known,
821  *	NULL otherwise.
822  */
823 struct edns_known_option* edns_option_is_known(uint16_t opt_code,
824 	struct module_env* env);
825 
826 /**
827  * Check if an edns option needs to bypass the reply from cache stage.
828  * @param list: the edns options.
829  * @param env: the module environment.
830  * @return true if an edns option needs to bypass the cache stage,
831  *	false otherwise.
832  */
833 int edns_bypass_cache_stage(struct edns_option* list,
834 	struct module_env* env);
835 
836 /**
837  * Check if an unique mesh state is required. Might be triggered by EDNS option
838  * or set for the complete env.
839  * @param list: the edns options.
840  * @param env: the module environment.
841  * @return true if an edns option needs a unique mesh state,
842  *	false otherwise.
843  */
844 int unique_mesh_state(struct edns_option* list, struct module_env* env);
845 
846 /**
847  * Log the known edns options.
848  * @param level: the desired verbosity level.
849  * @param env: the module environment.
850  */
851 void log_edns_known_options(enum verbosity_value level,
852 	struct module_env* env);
853 
854 /**
855  * Copy state that may have happened in the subquery and is always relevant to
856  * the super.
857  * @param qstate: query state that finished.
858  * @param id: module id.
859  * @param super: the qstate to inform.
860  */
861 void copy_state_to_super(struct module_qstate* qstate, int id,
862 	struct module_qstate* super);
863 
864 #endif /* UTIL_MODULE_H */
865