module.h revision 369939
151084Speter/* 239239Sgibbs * util/module.h - DNS handling module interface 339239Sgibbs * 439239Sgibbs * Copyright (c) 2007, NLnet Labs. All rights reserved. 539239Sgibbs * 639239Sgibbs * This software is open source. 7131318Snjl * 8131038Snjl * Redistribution and use in source and binary forms, with or without 9131038Snjl * modification, are permitted provided that the following conditions 10131319Snjl * are met: 11131038Snjl * 12301410Slandonf * Redistributions of source code must retain the above copyright notice, 13299690Semaste * this list of conditions and the following disclaimer. 14299684Sdim * 15299241Sadrian * Redistributions in binary form must reproduce the above copyright notice, 16299241Sadrian * this list of conditions and the following disclaimer in the documentation 17301410Slandonf * and/or other materials provided with the distribution. 18299690Semaste * 19299684Sdim * Neither the name of the NLNET LABS nor the names of its contributors may 20299241Sadrian * be used to endorse or promote products derived from this software without 21299241Sadrian * specific prior written permission. 22209128Sraj * 23209128Sraj * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 24209128Sraj * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 25209128Sraj * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 26262625Simp * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 27271045Sian * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 28209128Sraj * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 29248290Sbrooks * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 30209128Sraj * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 31271045Sian * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 32262614Simp * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 33209128Sraj * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 34209128Sraj */ 35193640Sariff 36193889Sariff/** 37193889Sariff * \file 38193640Sariff * 39193640Sariff * This file contains the interface for DNS handling modules. 40193640Sariff * 41214655Sobrien * The module interface uses the DNS modules as state machines. The 42193889Sariff * state machines are activated in sequence to operate on queries. Once 43193640Sariff * they are done, the reply is passed back. In the usual setup the mesh 44193640Sariff * is the caller of the state machines and once things are done sends replies 45193640Sariff * and invokes result callbacks. 46214655Sobrien * 47193889Sariff * The module provides a number of functions, listed in the module_func_block. 48193640Sariff * The module is inited and destroyed and memory usage queries, for the 49193640Sariff * module as a whole, for entire-module state (such as a cache). And per-query 50155435Simp * functions are called, operate to move the state machine and cleanup of 51129738Simp * the per-query state. 52129738Simp * 53131128Simp * Most per-query state should simply be allocated in the query region. 54110069Speter * This is destroyed at the end of the query. 55131335Simp * 56129740Simp * The module environment contains services and information and caches 57129740Simp * shared by the modules and the rest of the system. It also contains 58131128Simp * function pointers for module-specific tasks (like sending queries). 59129740Simp * 60297685Semaste * *** Example module calls for a normal query 61297685Semaste * 62297685Semaste * In this example, the query does not need recursion, all the other data 63297685Semaste * can be found in the cache. This makes the example shorter. 64259016Sray * 65196775Sed * At the start of the program the iterator module is initialised. 66196775Sed * The iterator module sets up its global state, such as donotquery lists 67186681Sed * and private address trees. 68186681Sed * 69192901Sthompsa * A query comes in, and a mesh entry is created for it. The mesh 70129740Simp * starts the resolution process. The validator module is the first 71139459Simp * in the list of modules, and it is started on this new query. The 72131128Simp * operate() function is called. The validator decides it needs not do 73139459Simp * anything yet until there is a result and returns wait_module, that 74192901Sthompsa * causes the next module in the list to be started. 75139459Simp * 76139459Simp * The next module is the iterator. It is started on the passed query and 77139459Simp * decides to perform a lookup. For this simple example, the delegation 78139459Simp * point information is available, and all the iterator wants to do is 79139659Simp * send a UDP query. The iterator uses env.send_query() to send the 80251842Sscottl * query. Then the iterator suspends (returns from the operate call). 81298002Simp * 82139659Simp * When the UDP reply comes back (and on errors and timeouts), the 83139659Simp * operate function is called for the query, on the iterator module, 84139659Simp * with the event that there is a reply. The iterator decides that this 85139659Simp * is enough, the work is done. It returns the value finished from the 86195534Sscottl * operate call, which causes the previous module to be started. 87195534Sscottl * 88199535Smav * The previous module, the validator module, is started with the event 89328681Smav * that the iterator module is done. The validator decides to validate 90328681Smav * the query. Once it is done (which could take recursive lookups, but 91301771Simp * in this example no recursive lookups are needed), it returns from the 92195534Sscottl * operate function with finished. 93139659Simp * 94139659Simp * There is no previous module from the validator module, and the mesh 95139659Simp * takes this to mean that the query is finally done. The mesh invokes 96199535Smav * callbacks and sends packets to queriers. 97229997Sken * 98232073Sdim * If other modules had been waiting (recursively) on the answer to this 99229997Sken * query, then the mesh will tell them about it. It calls the inform_super 100229997Sken * routine on all the waiting modules, and once that is done it calls all of 101232073Sdim * them with the operate() call. During inform_super the query that is done 102232073Sdim * still exists and information can be copied from it (but the module should 103229997Sken * not really re-entry codepoints and services). During the operate call 104286807Smav * the modules can use stored state to continue operation with the results. 105319152Sngie * (network buffers are used to contain the answer packet during the 106287621Smav * inform_super phase, but after that the network buffers will be cleared 107229997Sken * of their contents so that other tasks can be performed). 108268767Smav * 109268767Smav * *** Example module calls for recursion 110232073Sdim * 111229997Sken * A module is called in operate, and it decides that it wants to perform 112229997Sken * recursion. That is, it wants the full state-machine-list to operate on 113139659Simp * a different query. It calls env.attach_sub() to create a new query state. 114152862Sru * The routine returns the newly created state, and potentially the module 115139659Simp * can edit the module-states for the newly created query (i.e. pass along 116139659Simp * some information, like delegation points). The module then suspends, 117139659Simp * returns from the operate routine. 118235911Smav * 119235911Smav * The mesh meanwhile will have the newly created query (or queries) on 120235911Smav * a waiting list, and will call operate() on this query (or queries). 121168477Sscottl * It starts again at the start of the module list for them. The query 122139659Simp * (or queries) continue to operate their state machines, until they are 123139659Simp * done. When they are done the mesh calls inform_super on the module that 124216088Sken * wanted the recursion. After that the mesh calls operate() on the module 125233578Speter * that wanted to do the recursion, and during this phase the module could, 126284227Sbr * for example, decide to create more recursions. 127284227Sbr * 128284227Sbr * If the module decides it no longer wants the recursive information 129284227Sbr * it can call detach_subs. Those queries will still run to completion, 130306572Smarkj * potentially filling the cache with information. Inform_super is not 131284227Sbr * called any more. 132284227Sbr * 133233578Speter * The iterator module will fetch items from the cache, so a recursion 134233578Speter * attempt may complete very quickly if the item is in cache. The calling 135271873Ssmh * module has to wait for completion or eventual timeout. A recursive query 136233578Speter * that times out returns a servfail rcode (servfail is also returned for 137233578Speter * other errors during the lookup). 138233578Speter * 139233578Speter * Results are passed in the qstate, the rcode member is used to pass 140233578Speter * errors without requiring memory allocation, so that the code can continue 141233578Speter * in out-of-memory conditions. If the rcode member is 0 (NOERROR) then 142233578Speter * the dns_msg entry contains a filled out message. This message may 143233578Speter * also contain an rcode that is nonzero, but in this case additional 144248084Sattilio * information (query, additional) can be passed along. 145233578Speter * 146233578Speter * The rcode and dns_msg are used to pass the result from the the rightmost 147233578Speter * module towards the leftmost modules and then towards the user. 148285339Soshogbo * 149285339Soshogbo * If you want to avoid recursion-cycles where queries need other queries 150285339Soshogbo * that need the first one, use detect_cycle() to see if that will happen. 151233578Speter * 152237483Smarius */ 153233578Speter 154233578Speter#ifndef UTIL_MODULE_H 155233578Speter#define UTIL_MODULE_H 156233578Speter#include "util/storage/lruhash.h" 157233578Speter#include "util/data/msgreply.h" 158233578Speter#include "util/data/msgparse.h" 159233578Speterstruct sldns_buffer; 160233578Speterstruct alloc_cache; 161233578Speterstruct rrset_cache; 162321610Smavstruct key_cache; 163332540Smavstruct config_file; 164233578Speterstruct slabhash; 165268075Sdelphijstruct query_info; 166233578Speterstruct edns_data; 167233578Speterstruct regional; 168237483Smariusstruct worker; 169286718Speterstruct comm_base; 170332540Smavstruct auth_zones; 171233578Speterstruct outside_network; 172233578Speterstruct module_qstate; 173233578Speterstruct ub_randstate; 174233578Speterstruct mesh_area; 175233578Speterstruct mesh_state; 176233578Speterstruct val_anchors; 177233578Speterstruct val_neg_cache; 178233578Speterstruct iter_forwards; 179233578Speterstruct iter_hints; 180233578Speterstruct respip_set; 181233578Speterstruct respip_client_info; 182233578Speterstruct respip_addr_info; 183233578Speter 184233578Speter/** Maximum number of modules in operation */ 185260183Sdelphij#define MAX_MODULE 16 186233578Speter 187233578Speter/** Maximum number of known edns options */ 188233578Speter#define MAX_KNOWN_EDNS_OPTS 256 189248659Smm 190233578Speterenum inplace_cb_list_type { 191233578Speter /* Inplace callbacks for when a resolved reply is ready to be sent to the 192233578Speter * front.*/ 193233578Speter inplace_cb_reply = 0, 194248659Smm /* Inplace callbacks for when a reply is given from the cache. */ 195233578Speter inplace_cb_reply_cache, 196233578Speter /* Inplace callbacks for when a reply is given with local data 197246586Sdelphij * (or Chaos reply). */ 198233578Speter inplace_cb_reply_local, 199233578Speter /* Inplace callbacks for when the reply is servfail. */ 200286763Smav inplace_cb_reply_servfail, 201258717Savg /* Inplace callbacks for when a query is ready to be sent to the back.*/ 202233578Speter inplace_cb_query, 203233578Speter /* Inplace callback for when a reply is received from the back. */ 204233578Speter inplace_cb_query_response, 205233578Speter /* Inplace callback for when EDNS is parsed on a reply received from the 206301010Sallanjude * back. */ 207233578Speter inplace_cb_edns_back_parsed, 208332547Smav /* Total number of types. Used for array initialization. 209233578Speter * Should always be last. */ 210233578Speter inplace_cb_types_total 211233578Speter}; 212233578Speter 213233578Speter 214258717Savg/** Known edns option. Can be populated during modules' init. */ 215241739Smariusstruct edns_known_option { 216233578Speter /** type of this edns option */ 217233578Speter uint16_t opt_code; 218233578Speter /** whether the option needs to bypass the cache stage */ 219233578Speter int bypass_cache_stage; 220233578Speter /** whether the option needs mesh aggregation */ 221233578Speter int no_aggregation; 222332525Smav}; 223332525Smav 224332525Smav/** 225339111Smav * Inplace callback list of registered routines to be called. 226233578Speter */ 227233578Speterstruct inplace_cb { 228233578Speter /** next in list */ 229233578Speter struct inplace_cb* next; 230233578Speter /** Inplace callback routine */ 231233578Speter void* cb; 232332525Smav void* cb_arg; 233233578Speter /** module id */ 234233578Speter int id; 235233578Speter}; 236233578Speter 237325534Savg/** 238325534Savg * Inplace callback function called before replying. 239325534Savg * Called as func(qinfo, qstate, rep, rcode, edns, opt_list_out, repinfo, 240325534Savg * region, id, python_callback) 241325534Savg * Where: 242237483Smarius * qinfo: the query info. 243233578Speter * qstate: the module state. NULL when calling before the query reaches the 244233578Speter * mesh states. 245233578Speter * rep: reply_info. Could be NULL. 246233578Speter * rcode: the return code. 247233578Speter * edns: the edns_data of the reply. When qstate is NULL, it is also used as 248233578Speter * the edns input. 249233578Speter * opt_list_out: the edns options list for the reply. 250233578Speter * repinfo: reply information for a communication point. NULL when calling 251233578Speter * during the mesh states; the same could be found from 252233578Speter * qstate->mesh_info->reply_list. 253233578Speter * region: region to store data. 254233578Speter * id: module id. 255233578Speter * python_callback: only used for registering a python callback function. 256233578Speter */ 257233578Spetertypedef int inplace_cb_reply_func_type(struct query_info* qinfo, 258233578Speter struct module_qstate* qstate, struct reply_info* rep, int rcode, 259233578Speter struct edns_data* edns, struct edns_option** opt_list_out, 260233578Speter struct comm_reply* repinfo, struct regional* region, 261233578Speter struct timeval* start_time, int id, void* callback); 262233578Speter 263233578Speter/** 264233578Speter * Inplace callback function called before sending the query to a nameserver. 265233578Speter * Called as func(qinfo, flags, qstate, addr, addrlen, zone, zonelen, region, 266332537Smav * id, python_callback) 267233578Speter * Where: 268233578Speter * qinfo: query info. 269233578Speter * flags: flags of the query. 270233578Speter * qstate: query state. 271233578Speter * addr: to which server to send the query. 272233578Speter * addrlen: length of addr. 273233578Speter * zone: name of the zone of the delegation point. wireformat dname. 274233578Speter * This is the delegation point name for which the server is deemed 275233578Speter * authoritative. 276233578Speter * zonelen: length of zone. 277233578Speter * region: region to store data. 278233578Speter * id: module id. 279233578Speter * python_callback: only used for registering a python callback function. 280233578Speter */ 281233578Spetertypedef int inplace_cb_query_func_type(struct query_info* qinfo, uint16_t flags, 282325534Savg struct module_qstate* qstate, struct sockaddr_storage* addr, 283325534Savg socklen_t addrlen, uint8_t* zone, size_t zonelen, struct regional* region, 284325534Savg int id, void* callback); 285325534Savg 286325534Savg/** 287325534Savg * Inplace callback function called after parsing edns on query reply. 288325534Savg * Called as func(qstate, id, cb_args) 289325534Savg * Where: 290325534Savg * qstate: the query state. 291325534Savg * id: module id. 292325534Savg * cb_args: argument passed when registering callback. 293325534Savg */ 294325534Savgtypedef int inplace_cb_edns_back_parsed_func_type(struct module_qstate* qstate, 295325534Savg int id, void* cb_args); 296325534Savg 297325534Savg/** 298325534Savg * Inplace callback function called after parsing query response. 299325534Savg * Called as func(qstate, response, id, cb_args) 300325534Savg * Where: 301325534Savg * qstate: the query state. 302325534Savg * response: query response. 303325534Savg * id: module id. 304325534Savg * cb_args: argument passed when registering callback. 305325534Savg */ 306325534Savgtypedef int inplace_cb_query_response_func_type(struct module_qstate* qstate, 307325534Savg struct dns_msg* response, int id, void* cb_args); 308325534Savg 309325534Savg/** 310284227Sbr * Function called when looking for (expired) cached answers during the serve 311284227Sbr * expired logic. 312284227Sbr * Called as func(qstate, lookup_qinfo) 313339966Smarkj * Where: 314284227Sbr * qstate: the query state. 315284227Sbr * lookup_qinfo: the qinfo to lookup for. 316284227Sbr */ 317284227Sbrtypedef struct dns_msg* serve_expired_lookup_func_type( 318284227Sbr struct module_qstate* qstate, struct query_info* lookup_qinfo); 319284227Sbr 320284227Sbr/** 321307144Sed * Module environment. 322307144Sed * Services and data provided to the module. 323307144Sed */ 324307144Sedstruct module_env { 325307144Sed /* --- data --- */ 326307144Sed /** config file with config options */ 327307144Sed struct config_file* cfg; 328307144Sed /** shared message cache */ 329307144Sed struct slabhash* msg_cache; 330307144Sed /** shared rrset cache */ 331307144Sed struct rrset_cache* rrset_cache; 332307144Sed /** shared infrastructure cache (edns, lameness) */ 333307144Sed struct infra_cache* infra_cache; 334307144Sed /** shared key cache */ 335307144Sed struct key_cache* key_cache; 336307144Sed 337307144Sed /* --- services --- */ 338307144Sed /** 339285307Sed * Send serviced DNS query to server. UDP/TCP and EDNS is handled. 340289747Sed * operate() should return with wait_reply. Later on a callback 341285307Sed * will cause operate() to be called with event timeout or reply. 342285307Sed * The time until a timeout is calculated from roundtrip timing, 343285307Sed * several UDP retries are attempted. 344285307Sed * @param qinfo: query info. 345285307Sed * @param flags: host order flags word, with opcode and CD bit. 346254481Spjd * @param dnssec: if set, EDNS record will have bits set. 347242949Sobrien * If EDNS_DO bit is set, DO bit is set in EDNS records. 348242949Sobrien * If BIT_CD is set, CD bit is set in queries with EDNS records. 349242949Sobrien * @param want_dnssec: if set, the validator wants DNSSEC. Without 350242949Sobrien * EDNS, the answer is likely to be useless for this domain. 351328515Scognet * @param nocaps: do not use caps_for_id, use the qname as given. 352328515Scognet * (ignored if caps_for_id is disabled). 353328515Scognet * @param addr: where to. 354328515Scognet * @param addrlen: length of addr. 355328515Scognet * @param zone: delegation point name. 356328515Scognet * @param zonelen: length of zone name. 357328515Scognet * @param ssl_upstream: use SSL for upstream queries. 358328515Scognet * @param tls_auth_name: if ssl_upstream, use this name with TLS 359328515Scognet * authentication. 360328515Scognet * @param q: wich query state to reactivate upon return. 361328515Scognet * @return: false on failure (memory or socket related). no query was 362272444Sjkim * sent. Or returns an outbound entry with qsent and qstate set. 363272444Sjkim * This outbound_entry will be used on later module invocations 364231844Sjkim * that involve this query (timeout, error or reply). 365245582Sjkim */ 366231844Sjkim struct outbound_entry* (*send_query)(struct query_info* qinfo, 367231844Sjkim uint16_t flags, int dnssec, int want_dnssec, int nocaps, 368231844Sjkim struct sockaddr_storage* addr, socklen_t addrlen, 369231844Sjkim uint8_t* zone, size_t zonelen, int ssl_upstream, 370231844Sjkim char* tls_auth_name, struct module_qstate* q); 371231844Sjkim 372285797Sjkim /** 373231844Sjkim * Detach-subqueries. 374272444Sjkim * Remove all sub-query references from this query state. 375231844Sjkim * Keeps super-references of those sub-queries correct. 376231844Sjkim * Updates stat items in mesh_area structure. 377231844Sjkim * @param qstate: used to find mesh state. 378278970Sjkim */ 379243347Sjkim void (*detach_subs)(struct module_qstate* qstate); 380231844Sjkim 381231844Sjkim /** 382231844Sjkim * Attach subquery. 383231844Sjkim * Creates it if it does not exist already. 384231844Sjkim * Keeps sub and super references correct. 385231844Sjkim * Updates stat items in mesh_area structure. 386231844Sjkim * Pass if it is priming query or not. 387231844Sjkim * return: 388231844Sjkim * o if error (malloc) happened. 389231844Sjkim * o need to initialise the new state (module init; it is a new state). 390285797Sjkim * so that the next run of the query with this module is successful. 391231844Sjkim * o no init needed, attachment successful. 392231844Sjkim * 393231844Sjkim * @param qstate: the state to find mesh state, and that wants to 394231844Sjkim * receive the results from the new subquery. 395231844Sjkim * @param qinfo: what to query for (copied). 396231844Sjkim * @param qflags: what flags to use (RD, CD flag or not). 397322877Sjkim * @param prime: if it is a (stub) priming query. 398231844Sjkim * @param valrec: validation lookup recursion, does not need validation 399231844Sjkim * @param newq: If the new subquery needs initialisation, it is 400231844Sjkim * returned, otherwise NULL is returned. 401231844Sjkim * @return: false on error, true if success (and init may be needed). 402231844Sjkim */ 403231844Sjkim int (*attach_sub)(struct module_qstate* qstate, 404231844Sjkim struct query_info* qinfo, uint16_t qflags, int prime, 405231844Sjkim int valrec, struct module_qstate** newq); 406231844Sjkim 407231844Sjkim /** 408231844Sjkim * Add detached query. 409231844Sjkim * Creates it if it does not exist already. 410245582Sjkim * Does not make super/sub references. 411231844Sjkim * Performs a cycle detection - for double check - and fails if there is 412231844Sjkim * one. 413231844Sjkim * Updates stat items in mesh_area structure. 414231844Sjkim * Pass if it is priming query or not. 415231844Sjkim * return: 416231844Sjkim * o if error (malloc) happened. 417231844Sjkim * o need to initialise the new state (module init; it is a new state). 418231844Sjkim * so that the next run of the query with this module is successful. 419298714Sjkim * o no init needed, attachment successful. 420231844Sjkim * o added subquery, created if it did not exist already. 421231844Sjkim * 422231844Sjkim * @param qstate: the state to find mesh state, and that wants to receive 423231844Sjkim * the results from the new subquery. 424231844Sjkim * @param qinfo: what to query for (copied). 425231844Sjkim * @param qflags: what flags to use (RD / CD flag or not). 426231844Sjkim * @param prime: if it is a (stub) priming query. 427231844Sjkim * @param valrec: if it is a validation recursion query (lookup of key, DS). 428231844Sjkim * @param newq: If the new subquery needs initialisation, it is returned, 429231844Sjkim * otherwise NULL is returned. 430231844Sjkim * @param sub: The added mesh state, created if it did not exist already. 431231844Sjkim * @return: false on error, true if success (and init may be needed). 432231844Sjkim */ 433231844Sjkim int (*add_sub)(struct module_qstate* qstate, 434231844Sjkim struct query_info* qinfo, uint16_t qflags, int prime, 435231844Sjkim int valrec, struct module_qstate** newq, 436231844Sjkim struct mesh_state** sub); 437231844Sjkim 438231844Sjkim /** 439231844Sjkim * Kill newly attached sub. If attach_sub returns newq for 440231844Sjkim * initialisation, but that fails, then this routine will cleanup and 441231844Sjkim * delete the freshly created sub. 442231844Sjkim * @param newq: the new subquery that is no longer needed. 443298714Sjkim * It is removed. 444231844Sjkim */ 445231844Sjkim void (*kill_sub)(struct module_qstate* newq); 446231844Sjkim 447231844Sjkim /** 448231844Sjkim * Detect if adding a dependency for qstate on name,type,class will 449231844Sjkim * create a dependency cycle. 450231844Sjkim * @param qstate: given mesh querystate. 451231844Sjkim * @param qinfo: query info for dependency. 452231844Sjkim * @param flags: query flags of dependency, RD/CD flags. 453231844Sjkim * @param prime: if dependency is a priming query or not. 454231844Sjkim * @param valrec: validation lookup recursion, does not need validation 455231844Sjkim * @return true if the name,type,class exists and the given 456231844Sjkim * qstate mesh exists as a dependency of that name. Thus 457249663Sjkim * if qstate becomes dependent on name,type,class then a 458246849Sjkim * cycle is created. 459231844Sjkim */ 460231844Sjkim int (*detect_cycle)(struct module_qstate* qstate, 461231844Sjkim struct query_info* qinfo, uint16_t flags, int prime, 462231844Sjkim int valrec); 463231844Sjkim 464231844Sjkim /** region for temporary usage. May be cleared after operate() call. */ 465231844Sjkim struct regional* scratch; 466231844Sjkim /** buffer for temporary usage. May be cleared after operate() call. */ 467245582Sjkim struct sldns_buffer* scratch_buffer; 468231844Sjkim /** internal data for daemon - worker thread. */ 469231844Sjkim struct worker* worker; 470231844Sjkim /** the worker event base */ 471231844Sjkim struct comm_base* worker_base; 472231844Sjkim /** the outside network */ 473231844Sjkim struct outside_network* outnet; 474231844Sjkim /** mesh area with query state dependencies */ 475231844Sjkim struct mesh_area* mesh; 476231844Sjkim /** allocation service */ 477231844Sjkim struct alloc_cache* alloc; 478245582Sjkim /** random table to generate random numbers */ 479231844Sjkim struct ub_randstate* rnd; 480245582Sjkim /** time in seconds, converted to integer */ 481231844Sjkim time_t* now; 482231844Sjkim /** time in microseconds. Relatively recent. */ 483231844Sjkim struct timeval* now_tv; 484231844Sjkim /** is validation required for messages, controls client-facing 485231844Sjkim * validation status (AD bits) and servfails */ 486231844Sjkim int need_to_validate; 487231844Sjkim /** trusted key storage; these are the configured keys, if not NULL, 488231844Sjkim * otherwise configured by validator. These are the trust anchors, 489231844Sjkim * and are not primed and ready for validation, but on the bright 490287168Sjkim * side, they are read only memory, thus no locks and fast. */ 491245582Sjkim struct val_anchors* anchors; 492231844Sjkim /** negative cache, configured by the validator. if not NULL, 493231844Sjkim * contains NSEC record lookup trees. */ 494231844Sjkim struct val_neg_cache* neg_cache; 495231844Sjkim /** the 5011-probe timer (if any) */ 496231844Sjkim struct comm_timer* probe_timer; 497231844Sjkim /** auth zones */ 498231844Sjkim struct auth_zones* auth_zones; 499231844Sjkim /** Mapping of forwarding zones to targets. 500231844Sjkim * iterator forwarder information. per-thread, created by worker */ 501272444Sjkim struct iter_forwards* fwds; 502231844Sjkim /** 503231844Sjkim * iterator forwarder information. per-thread, created by worker. 504231844Sjkim * The hints -- these aren't stored in the cache because they don't 505250838Sjkim * expire. The hints are always used to "prime" the cache. Note 506231844Sjkim * that both root hints and stub zone "hints" are stored in this 507231844Sjkim * data structure. 508238381Sjkim */ 509231844Sjkim struct iter_hints* hints; 510231844Sjkim /** module specific data. indexed by module id. */ 511231844Sjkim void* modinfo[MAX_MODULE]; 512298714Sjkim 513250838Sjkim /* Shared linked list of inplace callback functions */ 514231844Sjkim struct inplace_cb* inplace_cb_lists[inplace_cb_types_total]; 515231844Sjkim 516231844Sjkim /** 517231844Sjkim * Shared array of known edns options (size MAX_KNOWN_EDNS_OPTS). 518231844Sjkim * Filled by edns literate modules during init. 519250838Sjkim */ 520231844Sjkim struct edns_known_option* edns_known_options; 521238381Sjkim /* Number of known edns options */ 522231844Sjkim size_t edns_known_options_num; 523272444Sjkim /** EDNS client string information */ 524231844Sjkim struct edns_strings* edns_strings; 525231844Sjkim 526231844Sjkim /* Make every mesh state unique, do not aggregate mesh states. */ 527231844Sjkim int unique_mesh; 528231844Sjkim}; 529231844Sjkim 530285797Sjkim/** 531231844Sjkim * External visible states of the module state machine 532231844Sjkim * Modules may also have an internal state. 533245582Sjkim * Modules are supposed to run to completion or until blocked. 534249112Sjkim */ 535322877Sjkimenum module_ext_state { 536231844Sjkim /** initial state - new query */ 537231844Sjkim module_state_initial = 0, 538245582Sjkim /** waiting for reply to outgoing network query */ 539327557Sjkim module_wait_reply, 540316303Sjkim /** module is waiting for another module */ 541272444Sjkim module_wait_module, 542231844Sjkim /** module is waiting for another module; that other is restarted */ 543231844Sjkim module_restart_next, 544239340Sjkim /** module is waiting for sub-query */ 545316303Sjkim module_wait_subquery, 546149971Sobrien /** module could not finish the query */ 547260039Sdim module_error, 548149971Sobrien /** module is finished with query */ 549260039Sdim module_finished 550149971Sobrien}; 551260039Sdim 552149971Sobrien/** 553260039Sdim * Events that happen to modules, that start or wakeup modules. 554149971Sobrien */ 555149971Sobrienenum module_ev { 556149971Sobrien /** new query */ 557260039Sdim module_event_new = 0, 558149971Sobrien /** query passed by other module */ 559260039Sdim module_event_pass, 560149971Sobrien /** reply inbound from server */ 561260039Sdim module_event_reply, 562149971Sobrien /** no reply, timeout or other error */ 563260039Sdim module_event_noreply, 564149971Sobrien /** reply is there, but capitalisation check failed */ 565260039Sdim module_event_capsfail, 566149971Sobrien /** next module is done, and its reply is awaiting you */ 567361012Sdim module_event_moddone, 568149971Sobrien /** error */ 569260039Sdim module_event_error 570149971Sobrien}; 571149971Sobrien 572255332Scy/** 573260039Sdim * Linked list of sockaddrs 574255332Scy * May be allocated such that only 'len' bytes of addr exist for the structure. 575255332Scy */ 576255332Scystruct sock_list { 577260039Sdim /** next in list */ 578255332Scy struct sock_list* next; 579260039Sdim /** length of addr */ 580255332Scy socklen_t len; 581255332Scy /** sockaddr */ 582242949Sobrien struct sockaddr_storage addr; 583242949Sobrien}; 584242949Sobrien 585242949Sobrienstruct respip_action_info; 586242949Sobrien 587242949Sobrien/** 588336345Skevans * Struct to hold relevant data for serve expired 589285139Soshogbo */ 590285139Soshogbostruct serve_expired_data { 591285139Soshogbo struct comm_timer* timer; 592149969Sobrien serve_expired_lookup_func_type* get_cached_answer; 593171239Speter}; 594149969Sobrien 595149969Sobrien/** 596149969Sobrien * Module state, per query. 597149969Sobrien */ 598149969Sobrienstruct module_qstate { 599149969Sobrien /** which query is being answered: name, type, class */ 600149969Sobrien struct query_info qinfo; 601149969Sobrien /** flags uint16 from query */ 602149969Sobrien uint16_t query_flags; 603149969Sobrien /** if this is a (stub or root) priming query (with hints) */ 604149969Sobrien int is_priming; 605149969Sobrien /** if this is a validation recursion query that does not get 606149969Sobrien * validation itself */ 607149969Sobrien int is_valrec; 608149969Sobrien 609149969Sobrien /** comm_reply contains server replies */ 610149969Sobrien struct comm_reply* reply; 611149969Sobrien /** the reply message, with message for client and calling module */ 612149969Sobrien struct dns_msg* return_msg; 613149969Sobrien /** the rcode, in case of error, instead of a reply message */ 614149969Sobrien int return_rcode; 615149969Sobrien /** origin of the reply (can be NULL from cache, list for cnames) */ 616149969Sobrien struct sock_list* reply_origin; 617149969Sobrien /** IP blacklist for queries */ 618149969Sobrien struct sock_list* blacklist; 619149969Sobrien /** region for this query. Cleared when query process finishes. */ 620149969Sobrien struct regional* region; 621149969Sobrien /** failure reason information if val-log-level is high */ 622149969Sobrien struct config_strlist* errinf; 623149969Sobrien 624149969Sobrien /** which module is executing */ 625149969Sobrien int curmod; 626149969Sobrien /** module states */ 627149969Sobrien enum module_ext_state ext_state[MAX_MODULE]; 628149969Sobrien /** module specific data for query. indexed by module id. */ 629149969Sobrien void* minfo[MAX_MODULE]; 630149969Sobrien /** environment for this query */ 631149969Sobrien struct module_env* env; 632149969Sobrien /** mesh related information for this query */ 633149969Sobrien struct mesh_state* mesh_info; 634149969Sobrien /** how many seconds before expiry is this prefetched (0 if not) */ 635149969Sobrien time_t prefetch_leeway; 636345344Skib /** serve expired data */ 637345344Skib struct serve_expired_data* serve_expired_data; 638345344Skib 639345344Skib /** incoming edns options from the front end */ 640345344Skib struct edns_option* edns_opts_front_in; 641345344Skib /** outgoing edns options to the back end */ 642345344Skib struct edns_option* edns_opts_back_out; 643345344Skib /** incoming edns options from the back end */ 644345344Skib struct edns_option* edns_opts_back_in; 645345344Skib /** outgoing edns options to the front end */ 646345344Skib struct edns_option* edns_opts_front_out; 647315514Sae /** whether modules should answer from the cache */ 648315514Sae int no_cache_lookup; 649315514Sae /** whether modules should store answer in the cache */ 650315514Sae int no_cache_store; 651315514Sae /** whether to refetch a fresh answer on finishing this state*/ 652315514Sae int need_refetch; 653184588Sdfr /** whether the query (or a subquery) was ratelimited */ 654152862Sru int was_ratelimited; 655315514Sae 656286839Smarkm /** 657315514Sae * Attributes of clients that share the qstate that may affect IP-based 658315514Sae * actions. 659346783Skevans */ 660346783Skevans struct respip_client_info* client_info; 661315514Sae 662315514Sae /** Extended result of response-ip action processing, mainly 663315514Sae * for logging purposes. */ 664315514Sae struct respip_action_info* respip_action_info; 665301010Sallanjude 666301010Sallanjude /** whether the reply should be dropped */ 667253210Sandre int is_drop; 668253210Sandre}; 669242949Sobrien 670242949Sobrien/** 671242949Sobrien * Module functionality block 672242949Sobrien */ 673242949Sobrienstruct module_func_block { 674242949Sobrien /** text string name of module */ 675242949Sobrien const char* name; 676242949Sobrien 677242949Sobrien /** 678242949Sobrien * init the module. Called once for the global state. 679242949Sobrien * This is the place to apply settings from the config file. 680242949Sobrien * @param env: module environment. 681242949Sobrien * @param id: module id number. 682242949Sobrien * return: 0 on error 683242949Sobrien */ 684242949Sobrien int (*init)(struct module_env* env, int id); 685242949Sobrien 686242949Sobrien /** 687242949Sobrien * de-init, delete, the module. Called once for the global state. 688242949Sobrien * @param env: module environment. 689139659Simp * @param id: module id number. 690139960Simp */ 691139659Simp void (*deinit)(struct module_env* env, int id); 692139659Simp 693139960Simp /** 694139659Simp * accept a new query, or work further on existing query. 695250963Sachim * Changes the qstate->ext_state to be correct on exit. 696250963Sachim * @param ev: event that causes the module state machine to 697250963Sachim * (re-)activate. 698250963Sachim * @param qstate: the query state. 699250963Sachim * Note that this method is not allowed to change the 700194701Srpaulo * query state 'identity', that is query info, qflags, 701137718Sphk * and priming status. 702237981Smav * Attach a subquery to get results to a different query. 703143795Sphilip * @param id: module id number that operate() is called on. 704194701Srpaulo * @param outbound: if not NULL this event is due to the reply/timeout 705139960Simp * or error on this outbound query. 706137718Sphk * @return: if at exit the ext_state is: 707137718Sphk * o wait_module: next module is started. (with pass event). 708137718Sphk * o error or finished: previous module is resumed. 709209523Srpaulo * o otherwise it waits until that event happens (assumes 710139960Simp * the service routine to make subrequest or send message 711139960Simp * have been called. 712139960Simp */ 713139960Simp void (*operate)(struct module_qstate* qstate, enum module_ev event, 714139960Simp int id, struct outbound_entry* outbound); 715139960Simp 716139960Simp /** 717139960Simp * inform super querystate about the results from this subquerystate. 718105890Sjhb * Is called when the querystate is finished. The method invoked is 719114248Snjl * the one from the current module active in the super querystate. 720105890Sjhb * @param qstate: the query state that is finished. 721105890Sjhb * Examine return_rcode and return_reply in the qstate. 722114248Snjl * @param id: module id for this module. 723105890Sjhb * This coincides with the current module for the super qstate. 724105890Sjhb * @param super: the super querystate that needs to be informed. 725117356Sjhb */ 726105890Sjhb void (*inform_super)(struct module_qstate* qstate, int id, 727122766Snjl struct module_qstate* super); 728105890Sjhb 729105890Sjhb /** 730105890Sjhb * clear module specific data 731105890Sjhb */ 732105890Sjhb void (*clear)(struct module_qstate* qstate, int id); 733142397Snjl 734128256Snjl /** 735131314Snjl * How much memory is the module specific data using. 736105890Sjhb * @param env: module environment. 737318392Ssephe * @param id: the module id. 738151565Snjl * @return the number of bytes that are alloced. 739105890Sjhb */ 740142397Snjl size_t (*get_mem)(struct module_env* env, int id); 741105890Sjhb}; 742126429Snjl 743157774Siwasaki/** 744139659Simp * Debug utility: module external qstate to string 745139659Simp * @param s: the state value. 746139659Simp * @return descriptive string. 747139659Simp */ 748139659Simpconst char* strextstate(enum module_ext_state s); 749139659Simp 750139659Simp/** 751139659Simp * Debug utility: module event to string 752139659Simp * @param e: the module event value. 753139659Simp * @return descriptive string. 754183567Sstas */ 755221020Sbzconst char* strmodulevent(enum module_ev e); 756173573Sjhb 757242949Sobrien/** 758139659Simp * Initialize the edns known options by allocating the required space. 759139659Simp * @param env: the module environment. 760139659Simp * @return false on failure (no memory). 761139659Simp */ 762271146Simpint edns_known_options_init(struct module_env* env); 763271146Simp 764271146Simp/** 765139659Simp * Free the allocated space for the known edns options. 766139659Simp * @param env: the module environment. 767139659Simp */ 768139659Simpvoid edns_known_options_delete(struct module_env* env); 769228779Sdim 770228779Sdim/** 771228779Sdim * Register a known edns option. Overwrite the flags if it is already 772228779Sdim * registered. Used before creating workers to register known edns options. 773139960Simp * @param opt_code: the edns option code. 774139960Simp * @param bypass_cache_stage: whether the option interacts with the cache. 775139960Simp * @param no_aggregation: whether the option implies more specific 776139960Simp * aggregation. 777260401Sscottl * @param env: the module environment. 778139659Simp * @return true on success, false on failure (registering more options than 77965941Sgibbs * allowed or trying to register after the environment is copied to the 78095379Sgibbs * threads.) 78165941Sgibbs */ 782260401Sscottlint edns_register_option(uint16_t opt_code, int bypass_cache_stage, 783221020Sbz int no_aggregation, struct module_env* env); 784221020Sbz 785272017Srpaulo/** 786239674Srwatson * Register an inplace callback function. 787245378Srwatson * @param cb: pointer to the callback function. 788245376Srwatson * @param type: inplace callback type. 789239675Srwatson * @param cbarg: argument for the callback function, or NULL. 790239675Srwatson * @param env: the module environment. 791239675Srwatson * @param id: module id. 792245369Srwatson * @return true on success, false on failure (out of memory or trying to 793239675Srwatson * register after the environment is copied to the threads.) 794275050Sbr */ 795275050Sbrint 796272017Srpauloinplace_cb_register(void* cb, enum inplace_cb_list_type type, void* cbarg, 797272016Srpaulo struct module_env* env, int id); 798139960Simp 799184573Sscottl/** 800139659Simp * Delete callback for specified type and module id. 801154789Sambrisko * @param env: the module environment. 802139659Simp * @param type: inplace callback type. 803139659Simp * @param id: module id. 804139659Simp */ 805139659Simpvoid 806139659Simpinplace_cb_delete(struct module_env* env, enum inplace_cb_list_type type, 807183724Ssos int id); 808183724Ssos 809183724Ssos/** 810194984Sraj * Delete all the inplace callback linked lists. 811183724Ssos * @param env: the module environment. 812194984Sraj */ 813183724Ssosvoid inplace_cb_lists_delete(struct module_env* env); 814183724Ssos 815183724Ssos/** 816183724Ssos * Check if an edns option is known. 817183724Ssos * @param opt_code: the edns option code. 818183724Ssos * @param env: the module environment. 819183724Ssos * @return pointer to registered option if the edns option is known, 820183724Ssos * NULL otherwise. 821183724Ssos */ 822183724Ssosstruct edns_known_option* edns_option_is_known(uint16_t opt_code, 823183724Ssos struct module_env* env); 824183724Ssos 825183724Ssos/** 826183724Ssos * Check if an edns option needs to bypass the reply from cache stage. 827183724Ssos * @param list: the edns options. 828280451Smav * @param env: the module environment. 829183724Ssos * @return true if an edns option needs to bypass the cache stage, 830183724Ssos * false otherwise. 831183724Ssos */ 832183724Ssosint edns_bypass_cache_stage(struct edns_option* list, 833183724Ssos struct module_env* env); 834183724Ssos 835198623Smav/** 836183724Ssos * Check if an unique mesh state is required. Might be triggered by EDNS option 837183724Ssos * or set for the complete env. 838183724Ssos * @param list: the edns options. 839220185Sadrian * @param env: the module environment. 840220185Sadrian * @return true if an edns option needs a unique mesh state, 841220185Sadrian * false otherwise. 842220185Sadrian */ 843220185Sadrianint unique_mesh_state(struct edns_option* list, struct module_env* env); 844220185Sadrian 845185522Ssam/** 846243066Srpaulo * Log the known edns options. 847270036Sadrian * @param level: the desired verbosity level. 848270036Sadrian * @param env: the module environment. 849235680Sadrian */ 850235680Sadrianvoid log_edns_known_options(enum verbosity_value level, 851251487Sadrian struct module_env* env); 852251487Sadrian 853301181Sadrian/** 854301181Sadrian * Copy state that may have happened in the subquery and is always relevant to 855218058Sadrian * the super. 856218058Sadrian * @param qstate: query state that finished. 857291233Sadrian * @param id: module id. 858291233Sadrian * @param super: the qstate to inform. 859219185Sadrian */ 860219185Sadrianvoid copy_state_to_super(struct module_qstate* qstate, int id, 861291233Sadrian struct module_qstate* super); 862291233Sadrian 863228887Sadrian#endif /* UTIL_MODULE_H */ 864228887Sadrian