"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.11.23/lib/lwres/include/lwres/lwres.h" (7 Sep 2020, 15402 Bytes) of package /linux/misc/dns/bind9/9.11.23/bind-9.11.23.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "lwres.h" see the Fossies "Dox" file reference documentation.

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