/contrib/bind9/lib/lwres/include/lwres/lwres.h

  1/*
  2 * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
  3 * Copyright (C) 2000, 2001  Internet Software Consortium.
  4 *
  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.
  8 *
  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.
 16 */
 17
 18/* $Id: lwres.h,v 1.57 2007/06/19 23:47:23 tbox Exp $ */
 19
 20#ifndef LWRES_LWRES_H
 21#define LWRES_LWRES_H 1
 22
 23#include <stdio.h>
 24
 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>
 30
 31/*! \file lwres/lwres.h */
 32
 33/*!
 34 * Design notes:
 35 *
 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
 38 * example:
 39 *
 40 *	<ul><li>lwres_nooprequest_t:
 41 *
 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 />
 49 *
 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
 53 *		needed.<br /><br />
 54 *
 55 *		lwres_nooprequest_free() releases into the lwres_context_t
 56 *		any space allocated during parsing.</li>
 57 *
 58 *	<li>lwres_noopresponse_t:
 59 *
 60 *		The functions used are similar to the three used for
 61 *		requests, just with different names.</li></ul>
 62 *
 63 * Typically, the client will use request_render, response_parse, and
 64 * response_free, while the daemon will use request_parse, response_render,
 65 * and request_free.
 66 *
 67 * The basic flow of a typical client is:
 68 *
 69 *	\li fill in a request_t, and call the render function.
 70 *
 71 *	\li Transmit the buffer returned to the daemon.
 72 *
 73 *	\li Wait for a response.
 74 *
 75 *	\li When a response is received, parse it into a response_t.
 76 *
 77 *	\li free the request buffer using lwres_context_freemem().
 78 *
 79 *	\li free the response structure and its associated buffer using
 80 *	response_free().
 81 */
 82
 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 */
 87
 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
 92
 93/*% no-op */
 94#define LWRES_OPCODE_NOOP		0x00000000U
 95
 96/*% lwres_nooprequest_t */
 97typedef struct {
 98	/* public */
 99	lwres_uint16_t			datalength;
100	unsigned char		       *data;
101} lwres_nooprequest_t;
102
103/*% lwres_noopresponse_t */
104typedef struct {
105	/* public */
106	lwres_uint16_t			datalength;
107	unsigned char		       *data;
108} lwres_noopresponse_t;
109
110/*% get addresses by name */
111#define LWRES_OPCODE_GETADDRSBYNAME	0x00010001U
112
113/*% lwres_addr_t */
114typedef struct lwres_addr lwres_addr_t;
115
116/*% LWRES_LIST */
117typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
118
119/*% lwres_addr */
120struct lwres_addr {
121	lwres_uint32_t			family;
122	lwres_uint16_t			length;
123	unsigned char			address[LWRES_ADDR_MAXLEN];
124	LWRES_LINK(lwres_addr_t)	link;
125};
126
127/*% lwres_gabnrequest_t */
128typedef struct {
129	/* public */
130	lwres_uint32_t			flags;
131	lwres_uint32_t			addrtypes;
132	lwres_uint16_t			namelen;
133	char			       *name;
134} lwres_gabnrequest_t;
135
136/*% lwres_gabnresponse_t */
137typedef struct {
138	/* public */
139	lwres_uint32_t			flags;
140	lwres_uint16_t			naliases;
141	lwres_uint16_t			naddrs;
142	char			       *realname;
143	char			      **aliases;
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. */
148	void			       *base;
149	size_t				baselen;
150} lwres_gabnresponse_t;
151
152/*% get name by address */
153#define LWRES_OPCODE_GETNAMEBYADDR	0x00010002U
154
155/*% lwres_gnbarequest_t */
156typedef struct {
157	/* public */
158	lwres_uint32_t			flags;
159	lwres_addr_t			addr;
160} lwres_gnbarequest_t;
161
162/*% lwres_gnbaresponse_t */
163typedef struct {
164	/* public */
165	lwres_uint32_t			flags;
166	lwres_uint16_t			naliases;
167	char			       *realname;
168	char			      **aliases;
169	lwres_uint16_t			realnamelen;
170	lwres_uint16_t		       *aliaslen;
171	/*! if base != NULL, it will be freed when this structure is freed. */
172	void			       *base;
173	size_t				baselen;
174} lwres_gnbaresponse_t;
175
176/*% get rdata by name */
177#define LWRES_OPCODE_GETRDATABYNAME	0x00010003U
178
179/*% lwres_grbnrequest_t */
180typedef struct {
181	/* public */
182	lwres_uint32_t			flags;
183	lwres_uint16_t			rdclass;
184	lwres_uint16_t			rdtype;
185	lwres_uint16_t			namelen;
186	char			       *name;
187} lwres_grbnrequest_t;
188
189/*% lwres_grbnresponse_t */
190typedef struct {
191	/* public */
192	lwres_uint32_t			flags;
193	lwres_uint16_t			rdclass;
194	lwres_uint16_t			rdtype;
195	lwres_uint32_t			ttl;
196	lwres_uint16_t			nrdatas;
197	lwres_uint16_t			nsigs;
198	char			       *realname;
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. */
205	void			       *base;
206	size_t				baselen;
207} lwres_grbnresponse_t;
208
209/*% Used by lwres_getrrsetbyname() */
210#define LWRDATA_VALIDATED	0x00000001
211
212/*!
213 * resolv.conf data
214 */
215
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 */
221
222/*% lwres_conf_t */
223typedef struct {
224	lwres_context_t *lwctx;
225	lwres_addr_t    nameservers[LWRES_CONFMAXNAMESERVERS];
226	lwres_uint8_t	nsnext;		/*%< index for next free slot */
227
228	lwres_addr_t	lwservers[LWRES_CONFMAXLWSERVERS];
229	lwres_uint8_t	lwnext;		/*%< index for next free slot */
230
231	char	       *domainname;
232
233	char 	       *search[LWRES_CONFMAXSEARCH];
234	lwres_uint8_t	searchnxt;	/*%< index for next free slot */
235
236	struct {
237		lwres_addr_t addr;
238		/*% mask has a non-zero 'family' and 'length' if set */
239		lwres_addr_t mask;
240	} sortlist[LWRES_CONFMAXSORTLIST];
241	lwres_uint8_t	sortlistnxt;
242
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' */
246} lwres_conf_t;
247
248#define LWRES_ADDRTYPE_V4		0x00000001U	/*%< ipv4 */
249#define LWRES_ADDRTYPE_V6		0x00000002U	/*%< ipv6 */
250
251#define LWRES_MAX_ALIASES		16		/*%< max # of aliases */
252#define LWRES_MAX_ADDRS			64		/*%< max # of addrs */
253
254LWRES_LANG_BEGINDECLS
255
256/*% This is in host byte order. */
257LIBLWRES_EXTERNAL_DATA extern lwres_uint16_t lwres_udp_port;
258
259LIBLWRES_EXTERNAL_DATA extern const char *lwres_resolv_conf;
260
261lwres_result_t
262lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req,
263			 lwres_lwpacket_t *pkt, lwres_buffer_t *b);
264
265lwres_result_t
266lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req,
267			  lwres_lwpacket_t *pkt, lwres_buffer_t *b);
268
269lwres_result_t
270lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
271			lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp);
272
273lwres_result_t
274lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
275			 lwres_lwpacket_t *pkt,
276			 lwres_gabnresponse_t **structp);
277
278void
279lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp);
280/**<
281 * Frees any dynamically allocated memory for this structure.
282 *
283 * Requires:
284 *
285 *	ctx != NULL, and be a context returned via lwres_context_create().
286 *
287 *	structp != NULL && *structp != NULL.
288 *
289 * Ensures:
290 *
291 *	*structp == NULL.
292 *
293 *	All memory allocated by this structure will be returned to the
294 *	system via the context's free function.
295 */
296
297void
298lwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnresponse_t **structp);
299/**<
300 * Frees any dynamically allocated memory for this structure.
301 *
302 * Requires:
303 *
304 *	ctx != NULL, and be a context returned via lwres_context_create().
305 *
306 *	structp != NULL && *structp != NULL.
307 *
308 * Ensures:
309 *
310 *	*structp == NULL.
311 *
312 *	All memory allocated by this structure will be returned to the
313 *	system via the context's free function.
314 */
315
316
317lwres_result_t
318lwres_gnbarequest_render(lwres_context_t *ctx, lwres_gnbarequest_t *req,
319			 lwres_lwpacket_t *pkt, lwres_buffer_t *b);
320
321lwres_result_t
322lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req,
323			  lwres_lwpacket_t *pkt, lwres_buffer_t *b);
324
325lwres_result_t
326lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
327			lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp);
328
329lwres_result_t
330lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
331			 lwres_lwpacket_t *pkt,
332			 lwres_gnbaresponse_t **structp);
333
334void
335lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp);
336/**<
337 * Frees any dynamically allocated memory for this structure.
338 *
339 * Requires:
340 *
341 *	ctx != NULL, and be a context returned via lwres_context_create().
342 *
343 *	structp != NULL && *structp != NULL.
344 *
345 * Ensures:
346 *
347 *	*structp == NULL.
348 *
349 *	All memory allocated by this structure will be returned to the
350 *	system via the context's free function.
351 */
352
353void
354lwres_gnbaresponse_free(lwres_context_t *ctx, lwres_gnbaresponse_t **structp);
355/**<
356 * Frees any dynamically allocated memory for this structure.
357 *
358 * Requires:
359 *
360 *	ctx != NULL, and be a context returned via lwres_context_create().
361 *
362 *	structp != NULL && *structp != NULL.
363 *
364 * Ensures:
365 *
366 *	*structp == NULL.
367 *
368 *	All memory allocated by this structure will be returned to the
369 *	system via the context's free function.
370 */
371
372lwres_result_t
373lwres_grbnrequest_render(lwres_context_t *ctx, lwres_grbnrequest_t *req,
374			 lwres_lwpacket_t *pkt, lwres_buffer_t *b);
375
376lwres_result_t
377lwres_grbnresponse_render(lwres_context_t *ctx, lwres_grbnresponse_t *req,
378			  lwres_lwpacket_t *pkt, lwres_buffer_t *b);
379
380lwres_result_t
381lwres_grbnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
382			lwres_lwpacket_t *pkt, lwres_grbnrequest_t **structp);
383
384lwres_result_t
385lwres_grbnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
386			 lwres_lwpacket_t *pkt,
387			 lwres_grbnresponse_t **structp);
388
389void
390lwres_grbnrequest_free(lwres_context_t *ctx, lwres_grbnrequest_t **structp);
391/**<
392 * Frees any dynamically allocated memory for this structure.
393 *
394 * Requires:
395 *
396 *	ctx != NULL, and be a context returned via lwres_context_create().
397 *
398 *	structp != NULL && *structp != NULL.
399 *
400 * Ensures:
401 *
402 *	*structp == NULL.
403 *
404 *	All memory allocated by this structure will be returned to the
405 *	system via the context's free function.
406 */
407
408void
409lwres_grbnresponse_free(lwres_context_t *ctx, lwres_grbnresponse_t **structp);
410/**<
411 * Frees any dynamically allocated memory for this structure.
412 *
413 * Requires:
414 *
415 *	ctx != NULL, and be a context returned via lwres_context_create().
416 *
417 *	structp != NULL && *structp != NULL.
418 *
419 * Ensures:
420 *
421 *	*structp == NULL.
422 *
423 *	All memory allocated by this structure will be returned to the
424 *	system via the context's free function.
425 */
426
427lwres_result_t
428lwres_nooprequest_render(lwres_context_t *ctx, lwres_nooprequest_t *req,
429			 lwres_lwpacket_t *pkt, lwres_buffer_t *b);
430/**<
431 * Allocate space and render into wire format a noop request packet.
432 *
433 * Requires:
434 *
435 *	ctx != NULL, and be a context returned via lwres_context_create().
436 *
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.
440 *
441 *	Caller needs to fill in parts of "pkt" before calling:
442 *		serial, maxrecv, result.
443 *
444 * Returns:
445 *
446 *	Returns 0 on success, non-zero on failure.
447 *
448 *	On successful return, *b will contain data about the wire-format
449 *	packet.  It can be transmitted in any way, including lwres_sendblock().
450 */
451
452lwres_result_t
453lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req,
454			  lwres_lwpacket_t *pkt, lwres_buffer_t *b);
455
456lwres_result_t
457lwres_nooprequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
458			lwres_lwpacket_t *pkt, lwres_nooprequest_t **structp);
459/**<
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.
463 *
464 * The function verifies bits of the header, but does not modify it.
465 */
466
467lwres_result_t
468lwres_noopresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
469			 lwres_lwpacket_t *pkt,
470			 lwres_noopresponse_t **structp);
471
472void
473lwres_nooprequest_free(lwres_context_t *ctx, lwres_nooprequest_t **structp);
474
475void
476lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp);
477
478/**<
479 * Frees any dynamically allocated memory for this structure.
480 *
481 * Requires:
482 *
483 *	ctx != NULL, and be a context returned via lwres_context_create().
484 *
485 *	structp != NULL && *structp != NULL.
486 *
487 * Ensures:
488 *
489 *	*structp == NULL.
490 *
491 *	All memory allocated by this structure will be returned to the
492 *	system via the context's free function.
493 */
494
495lwres_result_t
496lwres_conf_parse(lwres_context_t *ctx, const char *filename);
497/**<
498 * parses a resolv.conf-format file and stores the results in the structure
499 * pointed to by *ctx.
500 *
501 * Requires:
502 *	ctx != NULL
503 *	filename != NULL && strlen(filename) > 0
504 *
505 * Returns:
506 *	LWRES_R_SUCCESS on a successful parse.
507 *	Anything else on error, although the structure may be partially filled
508 *	in.
509 */
510
511lwres_result_t
512lwres_conf_print(lwres_context_t *ctx, FILE *fp);
513/**<
514 * Prints a resolv.conf-format of confdata output to fp.
515 *
516 * Requires:
517 *	ctx != NULL
518 */
519
520void
521lwres_conf_init(lwres_context_t *ctx);
522/**<
523 * sets all internal fields to a default state. Used to initialize a new
524 * lwres_conf_t structure (not reset a used on).
525 *
526 * Requires:
527 *	ctx != NULL
528 */
529
530void
531lwres_conf_clear(lwres_context_t *ctx);
532/**<
533 * frees all internally allocated memory in confdata. Uses the memory
534 * routines supplied by ctx.
535 *
536 * Requires:
537 *	ctx != NULL
538 */
539
540lwres_conf_t *
541lwres_conf_get(lwres_context_t *ctx);
542/**<
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.
545 *
546 * Requires:
547 *	ctx != NULL
548 */
549
550/*
551 * Helper functions
552 */
553
554lwres_result_t
555lwres_data_parse(lwres_buffer_t *b, unsigned char **p, lwres_uint16_t *len);
556
557lwres_result_t
558lwres_string_parse(lwres_buffer_t *b, char **c, lwres_uint16_t *len);
559
560lwres_result_t
561lwres_addr_parse(lwres_buffer_t *b, lwres_addr_t *addr);
562
563lwres_result_t
564lwres_getaddrsbyname(lwres_context_t *ctx, const char *name,
565		     lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp);
566
567lwres_result_t
568lwres_getnamebyaddr(lwres_context_t *ctx, lwres_uint32_t addrtype,
569		    lwres_uint16_t addrlen, const unsigned char *addr,
570		    lwres_gnbaresponse_t **structp);
571
572lwres_result_t
573lwres_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);
576
577LWRES_LANG_ENDDECLS
578
579#endif /* LWRES_LWRES_H */