Edit File: lwres.h
/* * Copyright (C) Internet Systems Consortium, Inc. ("ISC") * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. * * See the COPYRIGHT file distributed with this work for additional * information regarding copyright ownership. */ /* $Id: lwres.h,v 1.57 2007/06/19 23:47:23 tbox Exp $ */ #ifndef LWRES_LWRES_H #define LWRES_LWRES_H 1 #include <stdio.h> #include <lwres/context.h> #include <lwres/lang.h> #include <lwres/list.h> #include <lwres/lwpacket.h> #include <lwres/platform.h> /*! \file lwres/lwres.h */ /*! * Design notes: * * Each opcode has two structures and three functions which operate on each * structure. For example, using the "no operation/ping" opcode as an * example: * * <ul><li>lwres_nooprequest_t: * * lwres_nooprequest_render() takes a lwres_nooprequest_t and * and renders it into wire format, storing the allocated * buffer information in a passed-in buffer. When this buffer * is no longer needed, it must be freed by * lwres_context_freemem(). All other memory used by the * caller must be freed manually, including the * lwres_nooprequest_t passed in.<br /><br /> * * lwres_nooprequest_parse() takes a wire format message and * breaks it out into a lwres_nooprequest_t. The structure * must be freed via lwres_nooprequest_free() when it is no longer * needed.<br /><br /> * * lwres_nooprequest_free() releases into the lwres_context_t * any space allocated during parsing.</li> * * <li>lwres_noopresponse_t: * * The functions used are similar to the three used for * requests, just with different names.</li></ul> * * Typically, the client will use request_render, response_parse, and * response_free, while the daemon will use request_parse, response_render, * and request_free. * * The basic flow of a typical client is: * * \li fill in a request_t, and call the render function. * * \li Transmit the buffer returned to the daemon. * * \li Wait for a response. * * \li When a response is received, parse it into a response_t. * * \li free the request buffer using lwres_context_freemem(). * * \li free the response structure and its associated buffer using * response_free(). */ #define LWRES_UDP_PORT 921 /*%< UDP Port Number */ #define LWRES_RECVLENGTH 16384 /*%< Maximum Packet Length */ #define LWRES_ADDR_MAXLEN 16 /*%< changing this breaks ABI */ #define LWRES_RESOLV_CONF "/etc/resolv.conf" /*%< Location of resolv.conf */ /*% DNSSEC is not required (input). Only relevant to rrset queries. */ #define LWRES_FLAG_TRUSTNOTREQUIRED 0x00000001U /*% The data was crypto-verified with DNSSEC (output). */ #define LWRES_FLAG_SECUREDATA 0x00000002U /*% no-op */ #define LWRES_OPCODE_NOOP 0x00000000U /*% lwres_nooprequest_t */ typedef struct { /* public */ lwres_uint16_t datalength; unsigned char *data; } lwres_nooprequest_t; /*% lwres_noopresponse_t */ typedef struct { /* public */ lwres_uint16_t datalength; unsigned char *data; } lwres_noopresponse_t; /*% get addresses by name */ #define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U /*% lwres_addr_t */ typedef struct lwres_addr lwres_addr_t; /*% LWRES_LIST */ typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; /*% lwres_addr */ struct lwres_addr { lwres_uint32_t family; lwres_uint16_t length; unsigned char address[LWRES_ADDR_MAXLEN]; lwres_uint32_t zone; LWRES_LINK(lwres_addr_t) link; }; /*% lwres_gabnrequest_t */ typedef struct { /* public */ lwres_uint32_t flags; lwres_uint32_t addrtypes; lwres_uint16_t namelen; char *name; } lwres_gabnrequest_t; /*% lwres_gabnresponse_t */ typedef struct { /* public */ lwres_uint32_t flags; lwres_uint16_t naliases; lwres_uint16_t naddrs; char *realname; char **aliases; lwres_uint16_t realnamelen; lwres_uint16_t *aliaslen; lwres_addrlist_t addrs; /*! if base != NULL, it will be freed when this structure is freed. */ void *base; size_t baselen; } lwres_gabnresponse_t; /*% get name by address */ #define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U /*% lwres_gnbarequest_t */ typedef struct { /* public */ lwres_uint32_t flags; lwres_addr_t addr; } lwres_gnbarequest_t; /*% lwres_gnbaresponse_t */ typedef struct { /* public */ lwres_uint32_t flags; lwres_uint16_t naliases; char *realname; char **aliases; lwres_uint16_t realnamelen; lwres_uint16_t *aliaslen; /*! if base != NULL, it will be freed when this structure is freed. */ void *base; size_t baselen; } lwres_gnbaresponse_t; /*% get rdata by name */ #define LWRES_OPCODE_GETRDATABYNAME 0x00010003U /*% lwres_grbnrequest_t */ typedef struct { /* public */ lwres_uint32_t flags; lwres_uint16_t rdclass; lwres_uint16_t rdtype; lwres_uint16_t namelen; char *name; } lwres_grbnrequest_t; /*% lwres_grbnresponse_t */ typedef struct { /* public */ lwres_uint32_t flags; lwres_uint16_t rdclass; lwres_uint16_t rdtype; lwres_uint32_t ttl; lwres_uint16_t nrdatas; lwres_uint16_t nsigs; char *realname; lwres_uint16_t realnamelen; unsigned char **rdatas; lwres_uint16_t *rdatalen; unsigned char **sigs; lwres_uint16_t *siglen; /*% if base != NULL, it will be freed when this structure is freed. */ void *base; size_t baselen; } lwres_grbnresponse_t; /*% Used by lwres_getrrsetbyname() */ #define LWRDATA_VALIDATED 0x00000001 /*! * resolv.conf data */ #define LWRES_CONFMAXNAMESERVERS 3 /*%< max 3 "nameserver" entries */ #define LWRES_CONFMAXLWSERVERS 1 /*%< max 1 "lwserver" entry */ #define LWRES_CONFMAXSEARCH 8 /*%< max 8 domains in "search" entry */ #define LWRES_CONFMAXLINELEN 256 /*%< max size of a line */ #define LWRES_CONFMAXSORTLIST 10 /*%< max 10 */ /*% lwres_conf_t */ typedef struct { lwres_context_t *lwctx; lwres_addr_t nameservers[LWRES_CONFMAXNAMESERVERS]; lwres_uint8_t nsnext; /*%< index for next free slot */ lwres_addr_t lwservers[LWRES_CONFMAXLWSERVERS]; lwres_uint8_t lwnext; /*%< index for next free slot */ char *domainname; char *search[LWRES_CONFMAXSEARCH]; lwres_uint8_t searchnxt; /*%< index for next free slot */ struct { lwres_addr_t addr; /*% mask has a non-zero 'family' and 'length' if set */ lwres_addr_t mask; } sortlist[LWRES_CONFMAXSORTLIST]; lwres_uint8_t sortlistnxt; lwres_uint8_t resdebug; /*%< non-zero if 'options debug' set */ lwres_uint8_t ndots; /*%< set to n in 'options ndots:n' */ lwres_uint8_t no_tld_query; /*%< non-zero if 'options no_tld_query' */ lwres_int32_t attempts; /*%< set to n in 'options attempts:n' */ lwres_int32_t timeout; /*%< set to n in 'options timeout:n' */ } lwres_conf_t; #define LWRES_ADDRTYPE_V4 0x00000001U /*%< ipv4 */ #define LWRES_ADDRTYPE_V6 0x00000002U /*%< ipv6 */ #define LWRES_MAX_ALIASES 16 /*%< max # of aliases */ #define LWRES_MAX_ADDRS 64 /*%< max # of addrs */ LWRES_LANG_BEGINDECLS /*% This is in host byte order. */ LIBLWRES_EXTERNAL_DATA extern lwres_uint16_t lwres_udp_port; LIBLWRES_EXTERNAL_DATA extern const char *lwres_resolv_conf; lwres_result_t lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b); lwres_result_t lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b); lwres_result_t lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp); lwres_result_t lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnresponse_t **structp); void lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp); /**< * Frees any dynamically allocated memory for this structure. * * Requires: * * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * * Ensures: * * *structp == NULL. * * All memory allocated by this structure will be returned to the * system via the context's free function. */ void lwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnresponse_t **structp); /**< * Frees any dynamically allocated memory for this structure. * * Requires: * * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * * Ensures: * * *structp == NULL. * * All memory allocated by this structure will be returned to the * system via the context's free function. */ lwres_result_t lwres_gnbarequest_render(lwres_context_t *ctx, lwres_gnbarequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b); lwres_result_t lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b); lwres_result_t lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp); lwres_result_t lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbaresponse_t **structp); void lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp); /**< * Frees any dynamically allocated memory for this structure. * * Requires: * * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * * Ensures: * * *structp == NULL. * * All memory allocated by this structure will be returned to the * system via the context's free function. */ void lwres_gnbaresponse_free(lwres_context_t *ctx, lwres_gnbaresponse_t **structp); /**< * Frees any dynamically allocated memory for this structure. * * Requires: * * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * * Ensures: * * *structp == NULL. * * All memory allocated by this structure will be returned to the * system via the context's free function. */ lwres_result_t lwres_grbnrequest_render(lwres_context_t *ctx, lwres_grbnrequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b); lwres_result_t lwres_grbnresponse_render(lwres_context_t *ctx, lwres_grbnresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b); lwres_result_t lwres_grbnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_grbnrequest_t **structp); lwres_result_t lwres_grbnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_grbnresponse_t **structp); void lwres_grbnrequest_free(lwres_context_t *ctx, lwres_grbnrequest_t **structp); /**< * Frees any dynamically allocated memory for this structure. * * Requires: * * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * * Ensures: * * *structp == NULL. * * All memory allocated by this structure will be returned to the * system via the context's free function. */ void lwres_grbnresponse_free(lwres_context_t *ctx, lwres_grbnresponse_t **structp); /**< * Frees any dynamically allocated memory for this structure. * * Requires: * * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * * Ensures: * * *structp == NULL. * * All memory allocated by this structure will be returned to the * system via the context's free function. */ lwres_result_t lwres_nooprequest_render(lwres_context_t *ctx, lwres_nooprequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b); /**< * Allocate space and render into wire format a noop request packet. * * Requires: * * ctx != NULL, and be a context returned via lwres_context_create(). * * b != NULL, and points to a lwres_buffer_t. The contents of the * buffer structure will be initialized to contain the wire-format * noop request packet. * * Caller needs to fill in parts of "pkt" before calling: * serial, maxrecv, result. * * Returns: * * Returns 0 on success, non-zero on failure. * * On successful return, *b will contain data about the wire-format * packet. It can be transmitted in any way, including lwres_sendblock(). */ lwres_result_t lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b); lwres_result_t lwres_nooprequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_nooprequest_t **structp); /**< * Parse a noop request. Note that to get here, the lwpacket must have * already been parsed and removed by the caller, otherwise it would be * pretty hard for it to know this is the right function to call. * * The function verifies bits of the header, but does not modify it. */ lwres_result_t lwres_noopresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_noopresponse_t **structp); void lwres_nooprequest_free(lwres_context_t *ctx, lwres_nooprequest_t **structp); void lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp); /**< * Frees any dynamically allocated memory for this structure. * * Requires: * * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * * Ensures: * * *structp == NULL. * * All memory allocated by this structure will be returned to the * system via the context's free function. */ lwres_result_t lwres_conf_parse(lwres_context_t *ctx, const char *filename); /**< * parses a resolv.conf-format file and stores the results in the structure * pointed to by *ctx. * * Requires: * ctx != NULL * filename != NULL && strlen(filename) > 0 * * Returns: * LWRES_R_SUCCESS on a successful parse. * Anything else on error, although the structure may be partially filled * in. */ lwres_result_t lwres_conf_print(lwres_context_t *ctx, FILE *fp); /**< * Prints a resolv.conf-format of confdata output to fp. * * Requires: * ctx != NULL */ void lwres_conf_init(lwres_context_t *ctx); /**< * sets all internal fields to a default state. Used to initialize a new * lwres_conf_t structure (not reset a used on). * * Requires: * ctx != NULL */ void lwres_conf_clear(lwres_context_t *ctx); /**< * frees all internally allocated memory in confdata. Uses the memory * routines supplied by ctx. * * Requires: * ctx != NULL */ lwres_conf_t * lwres_conf_get(lwres_context_t *ctx); /**< * Be extremely cautions in modifying the contents of this structure; it * needs an API to return the various bits of data, walk lists, etc. * * Requires: * ctx != NULL */ /* * Helper functions */ lwres_result_t lwres_data_parse(lwres_buffer_t *b, unsigned char **p, lwres_uint16_t *len); lwres_result_t lwres_string_parse(lwres_buffer_t *b, char **c, lwres_uint16_t *len); lwres_result_t lwres_addr_parse(lwres_buffer_t *b, lwres_addr_t *addr); lwres_result_t lwres_getaddrsbyname(lwres_context_t *ctx, const char *name, lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp); lwres_result_t lwres_getnamebyaddr(lwres_context_t *ctx, lwres_uint32_t addrtype, lwres_uint16_t addrlen, const unsigned char *addr, lwres_gnbaresponse_t **structp); lwres_result_t lwres_getrdatabyname(lwres_context_t *ctx, const char *name, lwres_uint16_t rdclass, lwres_uint16_t rdtype, lwres_uint32_t flags, lwres_grbnresponse_t **structp); LWRES_LANG_ENDDECLS #endif /* LWRES_LWRES_H */