2 * libunbound/context.h - validating context for unbound internal use
4 * Copyright (c) 2007, 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 LIMITED
25 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
26 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
27 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
28 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
32 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33 * POSSIBILITY OF SUCH DAMAGE.
39 * This file contains the validator context structure.
41 #ifndef LIBUNBOUND_CONTEXT_H
42 #define LIBUNBOUND_CONTEXT_H
43 #include "util/locks.h"
44 #include "util/alloc.h"
45 #include "util/rbtree.h"
46 #include "services/modstack.h"
47 #include "libunbound/unbound.h"
48 #include "util/data/packed_rrset.h"
53 * The context structure
55 * Contains two pipes for async service
56 * qq : write queries to the async service pid/tid.
57 * rr : read results from the async service pid/tid.
61 /** mutex on query write pipe */
62 lock_basic_t qqpipe_lock;
63 /** the query write pipe */
65 /** mutex on result read pipe */
66 lock_basic_t rrpipe_lock;
67 /** the result read pipe */
70 /* --- shared data --- */
71 /** mutex for access to env.cfg, finalized and dothread */
74 * The context has been finalized
75 * This is after config when the first resolve is done.
76 * The modules are inited (module-init()) and shared caches created.
80 /** is bg worker created yet ? */
82 /** pid of bg worker process */
84 /** tid of bg worker thread */
87 /** do threading (instead of forking) for async resolution */
89 /** next thread number for new threads */
91 /** if logfile is overriden */
93 /** what logfile to use instead */
96 * List of alloc-cache-id points per threadnum for notinuse threads.
97 * Simply the entire struct alloc_cache with the 'super' member used
98 * to link a simply linked list. Reset super member to the superalloc
101 struct alloc_cache* alloc_list;
103 /** shared caches, and so on */
104 struct alloc_cache superalloc;
105 /** module env master value */
106 struct module_env* env;
108 struct module_stack mods;
109 /** local authority zones */
110 struct local_zones* local_zones;
111 /** random state used to seed new random state structures */
112 struct ub_randstate* seed_rnd;
114 /** next query number (to try) to use */
116 /** number of async queries outstanding */
119 * Tree of outstanding queries. Indexed by querynum
120 * Used when results come in for async to lookup.
121 * Used when cancel is done for lookup (and delete).
122 * Used to see if querynum is free for use.
123 * Content of type ctx_query.
129 * The queries outstanding for the libunbound resolver.
130 * These are outstanding for async resolution.
131 * But also, outstanding for sync resolution by one of the threads that
132 * has joined the threadpool.
135 /** node in rbtree, must be first entry, key is ptr to the querynum */
136 struct rbnode_t node;
137 /** query id number, key for node */
139 /** was this an async query? */
141 /** was this query cancelled (for bg worker) */
144 /** for async query, the callback function */
146 /** for async query, the callback user arg */
149 /** answer message, result from resolver lookup. */
151 /** resulting message length. */
153 /** validation status on security */
154 enum sec_status msg_security;
155 /** store libworker that is handling this query */
158 /** result structure, also contains original query, type, class.
159 * malloced ptr ready to hand to the client. */
160 struct ub_result* res;
164 * The error constants
169 /** socket operation. Set to -1, so that if an error from _fd() is
170 * passed (-1) it gives a socket error. */
176 /** DNS service failed */
180 /** cfg change after finalize() */
182 /** initialization failed (bad settings) */
184 /** error in pipe communication with async bg worker */
186 /** error reading from file (resolv.conf) */
188 /** error async_id does not exist or result already been delivered */
193 * Command codes for libunbound pipe.
195 * Serialization looks like this:
196 * o length (of remainder) uint32.
197 * o uint32 command code.
198 * o per command format.
203 /** New query, sent to bg worker */
205 /** Cancel query, sent to bg worker */
207 /** Query result, originates from bg worker */
212 * finalize a context.
213 * @param ctx: context to finalize. creates shared data.
214 * @return 0 if OK, or errcode.
216 int context_finalize(struct ub_ctx* ctx);
218 /** compare two ctx_query elements */
219 int context_query_cmp(const void* a, const void* b);
222 * delete context query
223 * @param q: query to delete, including message packet and prealloc result
225 void context_query_delete(struct ctx_query* q);
228 * Create new query in context, add to querynum list.
229 * @param ctx: context
230 * @param name: query name
231 * @param rrtype: type
232 * @param rrclass: class
233 * @param cb: callback for async, or NULL for sync.
234 * @param cbarg: user arg for async queries.
235 * @return new ctx_query or NULL for malloc failure.
237 struct ctx_query* context_new(struct ub_ctx* ctx, const char* name,
238 int rrtype, int rrclass, ub_callback_t cb, void* cbarg);
241 * Get a new alloc. Creates a new one or uses a cached one.
242 * @param ctx: context
243 * @param locking: if true, cfglock is locked while getting alloc.
244 * @return an alloc, or NULL on mem error.
246 struct alloc_cache* context_obtain_alloc(struct ub_ctx* ctx, int locking);
249 * Release an alloc. Puts it into the cache.
250 * @param ctx: context
251 * @param locking: if true, cfglock is locked while releasing alloc.
252 * @param alloc: alloc to relinquish.
254 void context_release_alloc(struct ub_ctx* ctx, struct alloc_cache* alloc,
258 * Serialize a context query that questions data.
259 * This serializes the query name, type, ...
260 * As well as command code 'new_query'.
261 * @param q: context query
262 * @param len: the length of the allocation is returned.
263 * @return: an alloc, or NULL on mem error.
265 uint8_t* context_serialize_new_query(struct ctx_query* q, uint32_t* len);
268 * Serialize a context_query result to hand back to user.
269 * This serializes the query name, type, ..., and result.
270 * As well as command code 'answer'.
271 * @param q: context query
272 * @param err: error code to pass to client.
273 * @param pkt: the packet to add, can be NULL.
274 * @param len: the length of the allocation is returned.
275 * @return: an alloc, or NULL on mem error.
277 uint8_t* context_serialize_answer(struct ctx_query* q, int err,
278 ldns_buffer* pkt, uint32_t* len);
281 * Serialize a query cancellation. Serializes query async id
282 * as well as command code 'cancel'
283 * @param q: context query
284 * @param len: the length of the allocation is returned.
285 * @return: an alloc, or NULL on mem error.
287 uint8_t* context_serialize_cancel(struct ctx_query* q, uint32_t* len);
290 * Serialize a 'quit' command.
291 * @param len: the length of the allocation is returned.
292 * @return: an alloc, or NULL on mem error.
294 uint8_t* context_serialize_quit(uint32_t* len);
297 * Obtain command code from serialized buffer
298 * @param p: buffer serialized.
299 * @param len: length of buffer.
300 * @return command code or QUIT on error.
302 enum ub_ctx_cmd context_serial_getcmd(uint8_t* p, uint32_t len);
305 * Lookup query from new_query buffer.
306 * @param ctx: context
307 * @param p: buffer serialized.
308 * @param len: length of buffer.
309 * @return looked up ctx_query or NULL for malloc failure.
311 struct ctx_query* context_lookup_new_query(struct ub_ctx* ctx,
312 uint8_t* p, uint32_t len);
315 * Deserialize a new_query buffer.
316 * @param ctx: context
317 * @param p: buffer serialized.
318 * @param len: length of buffer.
319 * @return new ctx_query or NULL for malloc failure.
321 struct ctx_query* context_deserialize_new_query(struct ub_ctx* ctx,
322 uint8_t* p, uint32_t len);
325 * Deserialize an answer buffer.
326 * @param ctx: context
327 * @param p: buffer serialized.
328 * @param len: length of buffer.
329 * @param err: error code to be returned to client is passed.
330 * @return ctx_query with answer added or NULL for malloc failure.
332 struct ctx_query* context_deserialize_answer(struct ub_ctx* ctx,
333 uint8_t* p, uint32_t len, int* err);
336 * Deserialize a cancel buffer.
337 * @param ctx: context
338 * @param p: buffer serialized.
339 * @param len: length of buffer.
340 * @return ctx_query to cancel or NULL for failure.
342 struct ctx_query* context_deserialize_cancel(struct ub_ctx* ctx,
343 uint8_t* p, uint32_t len);
345 #endif /* LIBUNBOUND_CONTEXT_H */