external/bsd/bind/dist/lib/lwres/include/lwres/lwres.h

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