2 * Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 2000, 2001 Internet Software Consortium.
5 * Permission to use, copy, modify, and/or distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
18 /* $Id: lwres.h,v 1.57 2007/06/19 23:47:23 tbox Exp $ */
21 #define LWRES_LWRES_H 1
25 #include <lwres/context.h>
26 #include <lwres/lang.h>
27 #include <lwres/list.h>
28 #include <lwres/lwpacket.h>
29 #include <lwres/platform.h>
31 /*! \file lwres/lwres.h */
36 * Each opcode has two structures and three functions which operate on each
37 * structure. For example, using the "no operation/ping" opcode as an
40 * <ul><li>lwres_nooprequest_t:
42 * lwres_nooprequest_render() takes a lwres_nooprequest_t and
43 * and renders it into wire format, storing the allocated
44 * buffer information in a passed-in buffer. When this buffer
45 * is no longer needed, it must be freed by
46 * lwres_context_freemem(). All other memory used by the
47 * caller must be freed manually, including the
48 * lwres_nooprequest_t passed in.<br /><br />
50 * lwres_nooprequest_parse() takes a wire format message and
51 * breaks it out into a lwres_nooprequest_t. The structure
52 * must be freed via lwres_nooprequest_free() when it is no longer
55 * lwres_nooprequest_free() releases into the lwres_context_t
56 * any space allocated during parsing.</li>
58 * <li>lwres_noopresponse_t:
60 * The functions used are similar to the three used for
61 * requests, just with different names.</li></ul>
63 * Typically, the client will use request_render, response_parse, and
64 * response_free, while the daemon will use request_parse, response_render,
67 * The basic flow of a typical client is:
69 * \li fill in a request_t, and call the render function.
71 * \li Transmit the buffer returned to the daemon.
73 * \li Wait for a response.
75 * \li When a response is received, parse it into a response_t.
77 * \li free the request buffer using lwres_context_freemem().
79 * \li free the response structure and its associated buffer using
83 #define LWRES_UDP_PORT 921 /*%< UDP Port Number */
84 #define LWRES_RECVLENGTH 16384 /*%< Maximum Packet Length */
85 #define LWRES_ADDR_MAXLEN 16 /*%< changing this breaks ABI */
86 #define LWRES_RESOLV_CONF "/etc/resolv.conf" /*%< Location of resolv.conf */
88 /*% DNSSEC is not required (input). Only relevant to rrset queries. */
89 #define LWRES_FLAG_TRUSTNOTREQUIRED 0x00000001U
90 /*% The data was crypto-verified with DNSSEC (output). */
91 #define LWRES_FLAG_SECUREDATA 0x00000002U
94 #define LWRES_OPCODE_NOOP 0x00000000U
96 /*% lwres_nooprequest_t */
99 lwres_uint16_t datalength;
101 } lwres_nooprequest_t;
103 /*% lwres_noopresponse_t */
106 lwres_uint16_t datalength;
108 } lwres_noopresponse_t;
110 /*% get addresses by name */
111 #define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
114 typedef struct lwres_addr lwres_addr_t;
117 typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
121 lwres_uint32_t family;
122 lwres_uint16_t length;
123 unsigned char address[LWRES_ADDR_MAXLEN];
124 LWRES_LINK(lwres_addr_t) link;
127 /*% lwres_gabnrequest_t */
130 lwres_uint32_t flags;
131 lwres_uint32_t addrtypes;
132 lwres_uint16_t namelen;
134 } lwres_gabnrequest_t;
136 /*% lwres_gabnresponse_t */
139 lwres_uint32_t flags;
140 lwres_uint16_t naliases;
141 lwres_uint16_t naddrs;
144 lwres_uint16_t realnamelen;
145 lwres_uint16_t *aliaslen;
146 lwres_addrlist_t addrs;
147 /*! if base != NULL, it will be freed when this structure is freed. */
150 } lwres_gabnresponse_t;
152 /*% get name by address */
153 #define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U
155 /*% lwres_gnbarequest_t */
158 lwres_uint32_t flags;
160 } lwres_gnbarequest_t;
162 /*% lwres_gnbaresponse_t */
165 lwres_uint32_t flags;
166 lwres_uint16_t naliases;
169 lwres_uint16_t realnamelen;
170 lwres_uint16_t *aliaslen;
171 /*! if base != NULL, it will be freed when this structure is freed. */
174 } lwres_gnbaresponse_t;
176 /*% get rdata by name */
177 #define LWRES_OPCODE_GETRDATABYNAME 0x00010003U
179 /*% lwres_grbnrequest_t */
182 lwres_uint32_t flags;
183 lwres_uint16_t rdclass;
184 lwres_uint16_t rdtype;
185 lwres_uint16_t namelen;
187 } lwres_grbnrequest_t;
189 /*% lwres_grbnresponse_t */
192 lwres_uint32_t flags;
193 lwres_uint16_t rdclass;
194 lwres_uint16_t rdtype;
196 lwres_uint16_t nrdatas;
197 lwres_uint16_t nsigs;
199 lwres_uint16_t realnamelen;
200 unsigned char **rdatas;
201 lwres_uint16_t *rdatalen;
202 unsigned char **sigs;
203 lwres_uint16_t *siglen;
204 /*% if base != NULL, it will be freed when this structure is freed. */
207 } lwres_grbnresponse_t;
209 /*% Used by lwres_getrrsetbyname() */
210 #define LWRDATA_VALIDATED 0x00000001
216 #define LWRES_CONFMAXNAMESERVERS 3 /*%< max 3 "nameserver" entries */
217 #define LWRES_CONFMAXLWSERVERS 1 /*%< max 1 "lwserver" entry */
218 #define LWRES_CONFMAXSEARCH 8 /*%< max 8 domains in "search" entry */
219 #define LWRES_CONFMAXLINELEN 256 /*%< max size of a line */
220 #define LWRES_CONFMAXSORTLIST 10 /*%< max 10 */
224 lwres_context_t *lwctx;
225 lwres_addr_t nameservers[LWRES_CONFMAXNAMESERVERS];
226 lwres_uint8_t nsnext; /*%< index for next free slot */
228 lwres_addr_t lwservers[LWRES_CONFMAXLWSERVERS];
229 lwres_uint8_t lwnext; /*%< index for next free slot */
233 char *search[LWRES_CONFMAXSEARCH];
234 lwres_uint8_t searchnxt; /*%< index for next free slot */
238 /*% mask has a non-zero 'family' and 'length' if set */
240 } sortlist[LWRES_CONFMAXSORTLIST];
241 lwres_uint8_t sortlistnxt;
243 lwres_uint8_t resdebug; /*%< non-zero if 'options debug' set */
244 lwres_uint8_t ndots; /*%< set to n in 'options ndots:n' */
245 lwres_uint8_t no_tld_query; /*%< non-zero if 'options no_tld_query' */
248 #define LWRES_ADDRTYPE_V4 0x00000001U /*%< ipv4 */
249 #define LWRES_ADDRTYPE_V6 0x00000002U /*%< ipv6 */
251 #define LWRES_MAX_ALIASES 16 /*%< max # of aliases */
252 #define LWRES_MAX_ADDRS 64 /*%< max # of addrs */
254 LWRES_LANG_BEGINDECLS
256 /*% This is in host byte order. */
257 LIBLWRES_EXTERNAL_DATA extern lwres_uint16_t lwres_udp_port;
259 LIBLWRES_EXTERNAL_DATA extern const char *lwres_resolv_conf;
262 lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req,
263 lwres_lwpacket_t *pkt, lwres_buffer_t *b);
266 lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req,
267 lwres_lwpacket_t *pkt, lwres_buffer_t *b);
270 lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
271 lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp);
274 lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
275 lwres_lwpacket_t *pkt,
276 lwres_gabnresponse_t **structp);
279 lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp);
281 * Frees any dynamically allocated memory for this structure.
285 * ctx != NULL, and be a context returned via lwres_context_create().
287 * structp != NULL && *structp != NULL.
293 * All memory allocated by this structure will be returned to the
294 * system via the context's free function.
298 lwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnresponse_t **structp);
300 * Frees any dynamically allocated memory for this structure.
304 * ctx != NULL, and be a context returned via lwres_context_create().
306 * structp != NULL && *structp != NULL.
312 * All memory allocated by this structure will be returned to the
313 * system via the context's free function.
318 lwres_gnbarequest_render(lwres_context_t *ctx, lwres_gnbarequest_t *req,
319 lwres_lwpacket_t *pkt, lwres_buffer_t *b);
322 lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req,
323 lwres_lwpacket_t *pkt, lwres_buffer_t *b);
326 lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
327 lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp);
330 lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
331 lwres_lwpacket_t *pkt,
332 lwres_gnbaresponse_t **structp);
335 lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp);
337 * Frees any dynamically allocated memory for this structure.
341 * ctx != NULL, and be a context returned via lwres_context_create().
343 * structp != NULL && *structp != NULL.
349 * All memory allocated by this structure will be returned to the
350 * system via the context's free function.
354 lwres_gnbaresponse_free(lwres_context_t *ctx, lwres_gnbaresponse_t **structp);
356 * Frees any dynamically allocated memory for this structure.
360 * ctx != NULL, and be a context returned via lwres_context_create().
362 * structp != NULL && *structp != NULL.
368 * All memory allocated by this structure will be returned to the
369 * system via the context's free function.
373 lwres_grbnrequest_render(lwres_context_t *ctx, lwres_grbnrequest_t *req,
374 lwres_lwpacket_t *pkt, lwres_buffer_t *b);
377 lwres_grbnresponse_render(lwres_context_t *ctx, lwres_grbnresponse_t *req,
378 lwres_lwpacket_t *pkt, lwres_buffer_t *b);
381 lwres_grbnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
382 lwres_lwpacket_t *pkt, lwres_grbnrequest_t **structp);
385 lwres_grbnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
386 lwres_lwpacket_t *pkt,
387 lwres_grbnresponse_t **structp);
390 lwres_grbnrequest_free(lwres_context_t *ctx, lwres_grbnrequest_t **structp);
392 * Frees any dynamically allocated memory for this structure.
396 * ctx != NULL, and be a context returned via lwres_context_create().
398 * structp != NULL && *structp != NULL.
404 * All memory allocated by this structure will be returned to the
405 * system via the context's free function.
409 lwres_grbnresponse_free(lwres_context_t *ctx, lwres_grbnresponse_t **structp);
411 * Frees any dynamically allocated memory for this structure.
415 * ctx != NULL, and be a context returned via lwres_context_create().
417 * structp != NULL && *structp != NULL.
423 * All memory allocated by this structure will be returned to the
424 * system via the context's free function.
428 lwres_nooprequest_render(lwres_context_t *ctx, lwres_nooprequest_t *req,
429 lwres_lwpacket_t *pkt, lwres_buffer_t *b);
431 * Allocate space and render into wire format a noop request packet.
435 * ctx != NULL, and be a context returned via lwres_context_create().
437 * b != NULL, and points to a lwres_buffer_t. The contents of the
438 * buffer structure will be initialized to contain the wire-format
439 * noop request packet.
441 * Caller needs to fill in parts of "pkt" before calling:
442 * serial, maxrecv, result.
446 * Returns 0 on success, non-zero on failure.
448 * On successful return, *b will contain data about the wire-format
449 * packet. It can be transmitted in any way, including lwres_sendblock().
453 lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req,
454 lwres_lwpacket_t *pkt, lwres_buffer_t *b);
457 lwres_nooprequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
458 lwres_lwpacket_t *pkt, lwres_nooprequest_t **structp);
460 * Parse a noop request. Note that to get here, the lwpacket must have
461 * already been parsed and removed by the caller, otherwise it would be
462 * pretty hard for it to know this is the right function to call.
464 * The function verifies bits of the header, but does not modify it.
468 lwres_noopresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
469 lwres_lwpacket_t *pkt,
470 lwres_noopresponse_t **structp);
473 lwres_nooprequest_free(lwres_context_t *ctx, lwres_nooprequest_t **structp);
476 lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp);
479 * Frees any dynamically allocated memory for this structure.
483 * ctx != NULL, and be a context returned via lwres_context_create().
485 * structp != NULL && *structp != NULL.
491 * All memory allocated by this structure will be returned to the
492 * system via the context's free function.
496 lwres_conf_parse(lwres_context_t *ctx, const char *filename);
498 * parses a resolv.conf-format file and stores the results in the structure
499 * pointed to by *ctx.
503 * filename != NULL && strlen(filename) > 0
506 * LWRES_R_SUCCESS on a successful parse.
507 * Anything else on error, although the structure may be partially filled
512 lwres_conf_print(lwres_context_t *ctx, FILE *fp);
514 * Prints a resolv.conf-format of confdata output to fp.
521 lwres_conf_init(lwres_context_t *ctx);
523 * sets all internal fields to a default state. Used to initialize a new
524 * lwres_conf_t structure (not reset a used on).
531 lwres_conf_clear(lwres_context_t *ctx);
533 * frees all internally allocated memory in confdata. Uses the memory
534 * routines supplied by ctx.
541 lwres_conf_get(lwres_context_t *ctx);
543 * Be extremely cautions in modifying the contents of this structure; it
544 * needs an API to return the various bits of data, walk lists, etc.
555 lwres_data_parse(lwres_buffer_t *b, unsigned char **p, lwres_uint16_t *len);
558 lwres_string_parse(lwres_buffer_t *b, char **c, lwres_uint16_t *len);
561 lwres_addr_parse(lwres_buffer_t *b, lwres_addr_t *addr);
564 lwres_getaddrsbyname(lwres_context_t *ctx, const char *name,
565 lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp);
568 lwres_getnamebyaddr(lwres_context_t *ctx, lwres_uint32_t addrtype,
569 lwres_uint16_t addrlen, const unsigned char *addr,
570 lwres_gnbaresponse_t **structp);
573 lwres_getrdatabyname(lwres_context_t *ctx, const char *name,
574 lwres_uint16_t rdclass, lwres_uint16_t rdtype,
575 lwres_uint32_t flags, lwres_grbnresponse_t **structp);
579 #endif /* LWRES_LWRES_H */