contrib/bind-9.3/lib/lwres/include/lwres/lwres.h

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000, 2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and 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.49.12.3 2004/03/08 09:05:11 marka 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 /*
  32  * Design notes:
  33  *
  34  * Each opcode has two structures and three functions which operate on each
  35  * structure.  For example, using the "no operation/ping" opcode as an
  36  * example:
  37  *
  38  *      lwres_nooprequest_t:
  39  *
  40  *              lwres_nooprequest_render() takes a lwres_nooprequest_t and
  41  *              and renders it into wire format, storing the allocated
  42  *              buffer information in a passed-in buffer.  When this buffer
  43  *              is no longer needed, it must be freed by
  44  *              lwres_context_freemem().  All other memory used by the
  45  *              caller must be freed manually, including the
  46  *              lwres_nooprequest_t passed in.
  47  *
  48  *              lwres_nooprequest_parse() takes a wire format message and
  49  *              breaks it out into a lwres_nooprequest_t.  The structure
  50  *              must be freed via lwres_nooprequest_free() when it is no longer
  51  *              needed.
  52  *
  53  *              lwres_nooprequest_free() releases into the lwres_context_t
  54  *              any space allocated during parsing.
  55  *
  56  *      lwres_noopresponse_t:
  57  *
  58  *              The functions used are similar to the three used for
  59  *              requests, just with different names.
  60  *
  61  * Typically, the client will use request_render, response_parse, and
  62  * response_free, while the daemon will use request_parse, response_render,
  63  * and request_free.
  64  *
  65  * The basic flow of a typical client is:
  66  *
  67  *      fill in a request_t, and call the render function.
  68  *
  69  *      Transmit the buffer returned to the daemon.
  70  *
  71  *      Wait for a response.
  72  *
  73  *      When a response is received, parse it into a response_t.
  74  *
  75  *      free the request buffer using lwres_context_freemem().
  76  *
  77  *      free the response structure and its associated buffer using
  78  *      response_free().
  79  */
  80
  81 #define LWRES_UDP_PORT          921
  82 #define LWRES_RECVLENGTH        16384
  83 #define LWRES_ADDR_MAXLEN       16      /* changing this breaks ABI */
  84 #define LWRES_RESOLV_CONF       "/etc/resolv.conf"
  85
  86 /*
  87  * Flags.
  88  *
  89  *      These flags are only relevant to rrset queries.
  90  *
  91  *      TRUSTNOTREQUIRED:  DNSSEC is not required (input)
  92  *      SECUREDATA: The data was crypto-verified with DNSSEC (output)
  93  *
  94  */
  95 #define LWRES_FLAG_TRUSTNOTREQUIRED     0x00000001U
  96 #define LWRES_FLAG_SECUREDATA           0x00000002U
  97
  98 /*
  99  * no-op
 100  */
 101 #define LWRES_OPCODE_NOOP               0x00000000U
 102
 103 typedef struct {
 104         /* public */
 105         lwres_uint16_t                  datalength;
 106         unsigned char                  *data;
 107 } lwres_nooprequest_t;
 108
 109 typedef struct {
 110         /* public */
 111         lwres_uint16_t                  datalength;
 112         unsigned char                  *data;
 113 } lwres_noopresponse_t;
 114
 115 /*
 116  * get addresses by name
 117  */
 118 #define LWRES_OPCODE_GETADDRSBYNAME     0x00010001U
 119
 120 typedef struct lwres_addr lwres_addr_t;
 121 typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
 122
 123 struct lwres_addr {
 124         lwres_uint32_t                  family;
 125         lwres_uint16_t                  length;
 126         unsigned char                   address[LWRES_ADDR_MAXLEN];
 127         LWRES_LINK(lwres_addr_t)        link;
 128 };
 129
 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 typedef struct {
 139         /* public */
 140         lwres_uint32_t                  flags;
 141         lwres_uint16_t                  naliases;
 142         lwres_uint16_t                  naddrs;
 143         char                           *realname;
 144         char                          **aliases;
 145         lwres_uint16_t                  realnamelen;
 146         lwres_uint16_t                 *aliaslen;
 147         lwres_addrlist_t                addrs;
 148         /* if base != NULL, it will be freed when this structure is freed. */
 149         void                           *base;
 150         size_t                          baselen;
 151 } lwres_gabnresponse_t;
 152
 153 /*
 154  * get name by address
 155  */
 156 #define LWRES_OPCODE_GETNAMEBYADDR      0x00010002U
 157 typedef struct {
 158         /* public */
 159         lwres_uint32_t                  flags;
 160         lwres_addr_t                    addr;
 161 } lwres_gnbarequest_t;
 162
 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 /*
 177  * get rdata by name
 178  */
 179 #define LWRES_OPCODE_GETRDATABYNAME     0x00010003U
 180
 181 typedef struct {
 182         /* public */
 183         lwres_uint32_t                  flags;
 184         lwres_uint16_t                  rdclass;
 185         lwres_uint16_t                  rdtype;
 186         lwres_uint16_t                  namelen;
 187         char                           *name;
 188 } lwres_grbnrequest_t;
 189
 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 #define LWRDATA_VALIDATED       0x00000001
 210
 211 /*
 212  * resolv.conf data
 213  */
 214
 215 #define LWRES_CONFMAXNAMESERVERS 3      /* max 3 "nameserver" entries */
 216 #define LWRES_CONFMAXLWSERVERS 1        /* max 1 "lwserver" entry */
 217 #define LWRES_CONFMAXSEARCH 8           /* max 8 domains in "search" entry */
 218 #define LWRES_CONFMAXLINELEN 256        /* max size of a line */
 219 #define LWRES_CONFMAXSORTLIST 10
 220 typedef struct {
 221         lwres_context_t *lwctx;
 222         lwres_addr_t    nameservers[LWRES_CONFMAXNAMESERVERS];
 223         lwres_uint8_t   nsnext;         /* index for next free slot */
 224
 225         lwres_addr_t    lwservers[LWRES_CONFMAXLWSERVERS];
 226         lwres_uint8_t   lwnext;         /* index for next free slot */
 227
 228         char           *domainname;
 229
 230         char           *search[LWRES_CONFMAXSEARCH];
 231         lwres_uint8_t   searchnxt;      /* index for next free slot */
 232
 233         struct {
 234                 lwres_addr_t addr;
 235                 /* mask has a non-zero 'family' and 'length' if set */
 236                 lwres_addr_t mask;
 237         } sortlist[LWRES_CONFMAXSORTLIST];
 238         lwres_uint8_t   sortlistnxt;
 239
 240         lwres_uint8_t   resdebug;      /* non-zero if 'options debug' set */
 241         lwres_uint8_t   ndots;         /* set to n in 'options ndots:n' */
 242         lwres_uint8_t   no_tld_query;  /* non-zero if 'options no_tld_query' */
 243 } lwres_conf_t;
 244
 245 #define LWRES_ADDRTYPE_V4               0x00000001U     /* ipv4 */
 246 #define LWRES_ADDRTYPE_V6               0x00000002U     /* ipv6 */
 247
 248 #define LWRES_MAX_ALIASES               16              /* max # of aliases */
 249 #define LWRES_MAX_ADDRS                 64              /* max # of addrs */
 250
 251 LWRES_LANG_BEGINDECLS
 252
 253 /*
 254  * This is in host byte order.
 255  */
 256 LIBLWRES_EXTERNAL_DATA extern lwres_uint16_t lwres_udp_port;
 257
 258 LIBLWRES_EXTERNAL_DATA extern const char *lwres_resolv_conf;
 259
 260 lwres_result_t
 261 lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req,
 262                          lwres_lwpacket_t *pkt, lwres_buffer_t *b);
 263
 264 lwres_result_t
 265 lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req,
 266                           lwres_lwpacket_t *pkt, lwres_buffer_t *b);
 267
 268 lwres_result_t
 269 lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
 270                         lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp);
 271
 272 lwres_result_t
 273 lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
 274                          lwres_lwpacket_t *pkt,
 275                          lwres_gabnresponse_t **structp);
 276
 277 void
 278 lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp);
 279 /*
 280  * Frees any dynamically allocated memory for this structure.
 281  *
 282  * Requires:
 283  *
 284  *      ctx != NULL, and be a context returned via lwres_contextcreate().
 285  *
 286  *      structp != NULL && *structp != NULL.
 287  *
 288  * Ensures:
 289  *
 290  *      *structp == NULL.
 291  *
 292  *      All memory allocated by this structure will be returned to the
 293  *      system via the context's free function.
 294  */
 295
 296 void
 297 lwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnresponse_t **structp);
 298 /*
 299  * Frees any dynamically allocated memory for this structure.
 300  *
 301  * Requires:
 302  *
 303  *      ctx != NULL, and be a context returned via lwres_contextcreate().
 304  *
 305  *      structp != NULL && *structp != NULL.
 306  *
 307  * Ensures:
 308  *
 309  *      *structp == NULL.
 310  *
 311  *      All memory allocated by this structure will be returned to the
 312  *      system via the context's free function.
 313  */
 314
 315
 316 lwres_result_t
 317 lwres_gnbarequest_render(lwres_context_t *ctx, lwres_gnbarequest_t *req,
 318                          lwres_lwpacket_t *pkt, lwres_buffer_t *b);
 319
 320 lwres_result_t
 321 lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req,
 322                           lwres_lwpacket_t *pkt, lwres_buffer_t *b);
 323
 324 lwres_result_t
 325 lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
 326                         lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp);
 327
 328 lwres_result_t
 329 lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
 330                          lwres_lwpacket_t *pkt,
 331                          lwres_gnbaresponse_t **structp);
 332
 333 void
 334 lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp);
 335 /*
 336  * Frees any dynamically allocated memory for this structure.
 337  *
 338  * Requires:
 339  *
 340  *      ctx != NULL, and be a context returned via lwres_contextcreate().
 341  *
 342  *      structp != NULL && *structp != NULL.
 343  *
 344  * Ensures:
 345  *
 346  *      *structp == NULL.
 347  *
 348  *      All memory allocated by this structure will be returned to the
 349  *      system via the context's free function.
 350  */
 351
 352 void
 353 lwres_gnbaresponse_free(lwres_context_t *ctx, lwres_gnbaresponse_t **structp);
 354 /*
 355  * Frees any dynamically allocated memory for this structure.
 356  *
 357  * Requires:
 358  *
 359  *      ctx != NULL, and be a context returned via lwres_contextcreate().
 360  *
 361  *      structp != NULL && *structp != NULL.
 362  *
 363  * Ensures:
 364  *
 365  *      *structp == NULL.
 366  *
 367  *      All memory allocated by this structure will be returned to the
 368  *      system via the context's free function.
 369  */
 370
 371 lwres_result_t
 372 lwres_grbnrequest_render(lwres_context_t *ctx, lwres_grbnrequest_t *req,
 373                          lwres_lwpacket_t *pkt, lwres_buffer_t *b);
 374
 375 lwres_result_t
 376 lwres_grbnresponse_render(lwres_context_t *ctx, lwres_grbnresponse_t *req,
 377                           lwres_lwpacket_t *pkt, lwres_buffer_t *b);
 378
 379 lwres_result_t
 380 lwres_grbnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
 381                         lwres_lwpacket_t *pkt, lwres_grbnrequest_t **structp);
 382
 383 lwres_result_t
 384 lwres_grbnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
 385                          lwres_lwpacket_t *pkt,
 386                          lwres_grbnresponse_t **structp);
 387
 388 void
 389 lwres_grbnrequest_free(lwres_context_t *ctx, lwres_grbnrequest_t **structp);
 390 /*
 391  * Frees any dynamically allocated memory for this structure.
 392  *
 393  * Requires:
 394  *
 395  *      ctx != NULL, and be a context returned via lwres_contextcreate().
 396  *
 397  *      structp != NULL && *structp != NULL.
 398  *
 399  * Ensures:
 400  *
 401  *      *structp == NULL.
 402  *
 403  *      All memory allocated by this structure will be returned to the
 404  *      system via the context's free function.
 405  */
 406
 407 void
 408 lwres_grbnresponse_free(lwres_context_t *ctx, lwres_grbnresponse_t **structp);
 409 /*
 410  * Frees any dynamically allocated memory for this structure.
 411  *
 412  * Requires:
 413  *
 414  *      ctx != NULL, and be a context returned via lwres_contextcreate().
 415  *
 416  *      structp != NULL && *structp != NULL.
 417  *
 418  * Ensures:
 419  *
 420  *      *structp == NULL.
 421  *
 422  *      All memory allocated by this structure will be returned to the
 423  *      system via the context's free function.
 424  */
 425
 426 lwres_result_t
 427 lwres_nooprequest_render(lwres_context_t *ctx, lwres_nooprequest_t *req,
 428                          lwres_lwpacket_t *pkt, lwres_buffer_t *b);
 429 /*
 430  * Allocate space and render into wire format a noop request packet.
 431  *
 432  * Requires:
 433  *
 434  *      ctx != NULL, and be a context returned via lwres_contextcreate().
 435  *
 436  *      b != NULL, and points to a lwres_buffer_t.  The contents of the
 437  *      buffer structure will be initialized to contain the wire-format
 438  *      noop request packet.
 439  *
 440  *      Caller needs to fill in parts of "pkt" before calling:
 441  *              serial, maxrecv, result.
 442  *
 443  * Returns:
 444  *
 445  *      Returns 0 on success, non-zero on failure.
 446  *
 447  *      On successful return, *b will contain data about the wire-format
 448  *      packet.  It can be transmitted in any way, including lwres_sendblock().
 449  */
 450
 451 lwres_result_t
 452 lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req,
 453                           lwres_lwpacket_t *pkt, lwres_buffer_t *b);
 454
 455 lwres_result_t
 456 lwres_nooprequest_parse(lwres_context_t *ctx, lwres_buffer_t *b,
 457                         lwres_lwpacket_t *pkt, lwres_nooprequest_t **structp);
 458 /*
 459  * Parse a noop request.  Note that to get here, the lwpacket must have
 460  * already been parsed and removed by the caller, otherwise it would be
 461  * pretty hard for it to know this is the right function to call.
 462  *
 463  * The function verifies bits of the header, but does not modify it.
 464  */
 465
 466 lwres_result_t
 467 lwres_noopresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b,
 468                          lwres_lwpacket_t *pkt,
 469                          lwres_noopresponse_t **structp);
 470
 471 void
 472 lwres_nooprequest_free(lwres_context_t *ctx, lwres_nooprequest_t **structp);
 473
 474 void
 475 lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp);
 476
 477 /*
 478  * Frees any dynamically allocated memory for this structure.
 479  *
 480  * Requires:
 481  *
 482  *      ctx != NULL, and be a context returned via lwres_contextcreate().
 483  *
 484  *      structp != NULL && *structp != NULL.
 485  *
 486  * Ensures:
 487  *
 488  *      *structp == NULL.
 489  *
 490  *      All memory allocated by this structure will be returned to the
 491  *      system via the context's free function.
 492  */
 493
 494 lwres_result_t
 495 lwres_conf_parse(lwres_context_t *ctx, const char *filename);
 496 /*
 497  * parses a resolv.conf-format file and stores the results in the structure
 498  * pointed to by *ctx.
 499  *
 500  * Requires:
 501  *      ctx != NULL
 502  *      filename != NULL && strlen(filename) > 0
 503  *
 504  * Returns:
 505  *      LWRES_R_SUCCESS on a successful parse.
 506  *      Anything else on error, although the structure may be partially filled
 507  *      in.
 508  */
 509
 510 lwres_result_t
 511 lwres_conf_print(lwres_context_t *ctx, FILE *fp);
 512 /*
 513  * Prints a resolv.conf-format of confdata output to fp.
 514  *
 515  * Requires:
 516  *      ctx != NULL
 517  */
 518
 519 void
 520 lwres_conf_init(lwres_context_t *ctx);
 521 /*
 522  * sets all internal fields to a default state. Used to initialize a new
 523  * lwres_conf_t structure (not reset a used on).
 524  *
 525  * Requires:
 526  *      ctx != NULL
 527  */
 528
 529 void
 530 lwres_conf_clear(lwres_context_t *ctx);
 531 /*
 532  * frees all internally allocated memory in confdata. Uses the memory
 533  * routines supplied by ctx.
 534  *
 535  * Requires:
 536  *      ctx != NULL
 537  */
 538
 539 lwres_conf_t *
 540 lwres_conf_get(lwres_context_t *ctx);
 541 /*
 542  * returns a pointer to the current config structure.
 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 */