contrib/bind-9.5.2/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 */
  97 typedef struct {
  98         /* public */
  99         lwres_uint16_t                  datalength;
 100         unsigned char                  *data;
 101 } lwres_nooprequest_t;
 102
 103 /*% lwres_noopresponse_t */
 104 typedef 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 */
 114 typedef struct lwres_addr lwres_addr_t;
 115
 116 /*% LWRES_LIST */
 117 typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
 118
 119 /*% lwres_addr */
 120 struct 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 */
 128 typedef 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 */
 137 typedef 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 */
 156 typedef struct {
 157         /* public */
 158         lwres_uint32_t                  flags;
 159         lwres_addr_t                    addr;
 160 } lwres_gnbarequest_t;
 161
 162 /*% lwres_gnbaresponse_t */
 163 typedef 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 */
 180 typedef 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 */
 190 typedef 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 */
 223 typedef 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
 254 LWRES_LANG_BEGINDECLS
 255
 256 /*% This is in host byte order. */
 257 LIBLWRES_EXTERNAL_DATA extern lwres_uint16_t lwres_udp_port;
 258
 259 LIBLWRES_EXTERNAL_DATA extern const char *lwres_resolv_conf;
 260
 261 lwres_result_t
 262 lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req,
 263                          lwres_lwpacket_t *pkt, lwres_buffer_t *b);
 264
 265 lwres_result_t
 266 lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req,
 267                           lwres_lwpacket_t *pkt, lwres_buffer_t *b);
 268
 269 lwres_result_t
 270 lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
 271                         lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp);
 272
 273 lwres_result_t
 274 lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
 275                          lwres_lwpacket_t *pkt,
 276                          lwres_gabnresponse_t **structp);
 277
 278 void
 279 lwres_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
 297 void
 298 lwres_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
 317 lwres_result_t
 318 lwres_gnbarequest_render(lwres_context_t *ctx, lwres_gnbarequest_t *req,
 319                          lwres_lwpacket_t *pkt, lwres_buffer_t *b);
 320
 321 lwres_result_t
 322 lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req,
 323                           lwres_lwpacket_t *pkt, lwres_buffer_t *b);
 324
 325 lwres_result_t
 326 lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
 327                         lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp);
 328
 329 lwres_result_t
 330 lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
 331                          lwres_lwpacket_t *pkt,
 332                          lwres_gnbaresponse_t **structp);
 333
 334 void
 335 lwres_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
 353 void
 354 lwres_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
 372 lwres_result_t
 373 lwres_grbnrequest_render(lwres_context_t *ctx, lwres_grbnrequest_t *req,
 374                          lwres_lwpacket_t *pkt, lwres_buffer_t *b);
 375
 376 lwres_result_t
 377 lwres_grbnresponse_render(lwres_context_t *ctx, lwres_grbnresponse_t *req,
 378                           lwres_lwpacket_t *pkt, lwres_buffer_t *b);
 379
 380 lwres_result_t
 381 lwres_grbnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
 382                         lwres_lwpacket_t *pkt, lwres_grbnrequest_t **structp);
 383
 384 lwres_result_t
 385 lwres_grbnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
 386                          lwres_lwpacket_t *pkt,
 387                          lwres_grbnresponse_t **structp);
 388
 389 void
 390 lwres_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
 408 void
 409 lwres_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
 427 lwres_result_t
 428 lwres_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
 452 lwres_result_t
 453 lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req,
 454                           lwres_lwpacket_t *pkt, lwres_buffer_t *b);
 455
 456 lwres_result_t
 457 lwres_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
 467 lwres_result_t
 468 lwres_noopresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
 469                          lwres_lwpacket_t *pkt,
 470                          lwres_noopresponse_t **structp);
 471
 472 void
 473 lwres_nooprequest_free(lwres_context_t *ctx, lwres_nooprequest_t **structp);
 474
 475 void
 476 lwres_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
 495 lwres_result_t
 496 lwres_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
 511 lwres_result_t
 512 lwres_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
 520 void
 521 lwres_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
 530 void
 531 lwres_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
 540 lwres_conf_t *
 541 lwres_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
 554 lwres_result_t
 555 lwres_data_parse(lwres_buffer_t *b, unsigned char **p, lwres_uint16_t *len);
 556
 557 lwres_result_t
 558 lwres_string_parse(lwres_buffer_t *b, char **c, lwres_uint16_t *len);
 559
 560 lwres_result_t
 561 lwres_addr_parse(lwres_buffer_t *b, lwres_addr_t *addr);
 562
 563 lwres_result_t
 564 lwres_getaddrsbyname(lwres_context_t *ctx, const char *name,
 565                      lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp);
 566
 567 lwres_result_t
 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);
 571
 572 lwres_result_t
 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);
 576
 577 LWRES_LANG_ENDDECLS
 578
 579 #endif /* LWRES_LWRES_H */