contrib/bind-9.2.4rc7/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.2.1 2004/03/09 06:12:37 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
  30 /*
  31  * Design notes:
  32  *
  33  * Each opcode has two structures and three functions which operate on each
  34  * structure.  For example, using the "no operation/ping" opcode as an
  35  * example:
  36  *
  37  *      lwres_nooprequest_t:
  38  *
  39  *              lwres_nooprequest_render() takes a lwres_nooprequest_t and
  40  *              and renders it into wire format, storing the allocated
  41  *              buffer information in a passed-in buffer.  When this buffer
  42  *              is no longer needed, it must be freed by
  43  *              lwres_context_freemem().  All other memory used by the
  44  *              caller must be freed manually, including the
  45  *              lwres_nooprequest_t passed in.
  46  *
  47  *              lwres_nooprequest_parse() takes a wire format message and
  48  *              breaks it out into a lwres_nooprequest_t.  The structure
  49  *              must be freed via lwres_nooprequest_free() when it is no longer
  50  *              needed.
  51  *
  52  *              lwres_nooprequest_free() releases into the lwres_context_t
  53  *              any space allocated during parsing.
  54  *
  55  *      lwres_noopresponse_t:
  56  *
  57  *              The functions used are similar to the three used for
  58  *              requests, just with different names.
  59  *
  60  * Typically, the client will use request_render, response_parse, and
  61  * response_free, while the daemon will use request_parse, response_render,
  62  * and request_free.
  63  *
  64  * The basic flow of a typical client is:
  65  *
  66  *      fill in a request_t, and call the render function.
  67  *
  68  *      Transmit the buffer returned to the daemon.
  69  *
  70  *      Wait for a response.
  71  *
  72  *      When a response is received, parse it into a response_t.
  73  *
  74  *      free the request buffer using lwres_context_freemem().
  75  *
  76  *      free the response structure and its associated buffer using
  77  *      response_free().
  78  */
  79
  80 #define LWRES_UDP_PORT          921
  81 #define LWRES_RECVLENGTH        16384
  82 #define LWRES_ADDR_MAXLEN       16      /* changing this breaks ABI */
  83 #define LWRES_RESOLV_CONF       "/etc/resolv.conf"
  84
  85 /*
  86  * Flags.
  87  *
  88  *      These flags are only relevant to rrset queries.
  89  *
  90  *      TRUSTNOTREQUIRED:  DNSSEC is not required (input)
  91  *      SECUREDATA: The data was crypto-verified with DNSSEC (output)
  92  *
  93  */
  94 #define LWRES_FLAG_TRUSTNOTREQUIRED     0x00000001U
  95 #define LWRES_FLAG_SECUREDATA           0x00000002U
  96
  97 /*
  98  * no-op
  99  */
 100 #define LWRES_OPCODE_NOOP               0x00000000U
 101
 102 typedef struct {
 103         /* public */
 104         lwres_uint16_t                  datalength;
 105         unsigned char                  *data;
 106 } lwres_nooprequest_t;
 107
 108 typedef struct {
 109         /* public */
 110         lwres_uint16_t                  datalength;
 111         unsigned char                  *data;
 112 } lwres_noopresponse_t;
 113
 114 /*
 115  * get addresses by name
 116  */
 117 #define LWRES_OPCODE_GETADDRSBYNAME     0x00010001U
 118
 119 typedef struct lwres_addr lwres_addr_t;
 120 typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
 121
 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 typedef struct {
 130         /* public */
 131         lwres_uint32_t                  flags;
 132         lwres_uint32_t                  addrtypes;
 133         lwres_uint16_t                  namelen;
 134         char                           *name;
 135 } lwres_gabnrequest_t;
 136
 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 /*
 153  * get name by address
 154  */
 155 #define LWRES_OPCODE_GETNAMEBYADDR      0x00010002U
 156 typedef struct {
 157         /* public */
 158         lwres_uint32_t                  flags;
 159         lwres_addr_t                    addr;
 160 } lwres_gnbarequest_t;
 161
 162 typedef struct {
 163         /* public */
 164         lwres_uint32_t                  flags;
 165         lwres_uint16_t                  naliases;
 166         char                           *realname;
 167         char                          **aliases;
 168         lwres_uint16_t                  realnamelen;
 169         lwres_uint16_t                 *aliaslen;
 170         /* if base != NULL, it will be freed when this structure is freed. */
 171         void                           *base;
 172         size_t                          baselen;
 173 } lwres_gnbaresponse_t;
 174
 175 /*
 176  * get rdata by name
 177  */
 178 #define LWRES_OPCODE_GETRDATABYNAME     0x00010003U
 179
 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 typedef struct {
 190         /* public */
 191         lwres_uint32_t                  flags;
 192         lwres_uint16_t                  rdclass;
 193         lwres_uint16_t                  rdtype;
 194         lwres_uint32_t                  ttl;
 195         lwres_uint16_t                  nrdatas;
 196         lwres_uint16_t                  nsigs;
 197         char                           *realname;
 198         lwres_uint16_t                  realnamelen;
 199         unsigned char                 **rdatas;
 200         lwres_uint16_t                 *rdatalen;
 201         unsigned char                 **sigs;
 202         lwres_uint16_t                 *siglen;
 203         /* if base != NULL, it will be freed when this structure is freed. */
 204         void                           *base;
 205         size_t                          baselen;
 206 } lwres_grbnresponse_t;
 207
 208 #define LWRDATA_VALIDATED       0x00000001
 209
 210 /*
 211  * resolv.conf data
 212  */
 213
 214 #define LWRES_CONFMAXNAMESERVERS 3      /* max 3 "nameserver" entries */
 215 #define LWRES_CONFMAXLWSERVERS 1        /* max 1 "lwserver" entry */
 216 #define LWRES_CONFMAXSEARCH 8           /* max 8 domains in "search" entry */
 217 #define LWRES_CONFMAXLINELEN 256        /* max size of a line */
 218 #define LWRES_CONFMAXSORTLIST 10
 219 typedef struct {
 220         lwres_context_t *lwctx;
 221         lwres_addr_t    nameservers[LWRES_CONFMAXNAMESERVERS];
 222         lwres_uint8_t   nsnext;         /* index for next free slot */
 223
 224         lwres_addr_t    lwservers[LWRES_CONFMAXLWSERVERS];
 225         lwres_uint8_t   lwnext;         /* index for next free slot */
 226
 227         char           *domainname;
 228
 229         char           *search[LWRES_CONFMAXSEARCH];
 230         lwres_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         lwres_uint8_t   sortlistnxt;
 238
 239         lwres_uint8_t   resdebug;      /* non-zero if 'options debug' set */
 240         lwres_uint8_t   ndots;         /* set to n in 'options ndots:n' */
 241         lwres_uint8_t   no_tld_query;  /* non-zero if 'options no_tld_query' */
 242 } lwres_conf_t;
 243
 244 #define LWRES_ADDRTYPE_V4               0x00000001U     /* ipv4 */
 245 #define LWRES_ADDRTYPE_V6               0x00000002U     /* ipv6 */
 246
 247 #define LWRES_MAX_ALIASES               16              /* max # of aliases */
 248 #define LWRES_MAX_ADDRS                 64              /* max # of addrs */
 249
 250 LWRES_LANG_BEGINDECLS
 251
 252 /*
 253  * This is in host byte order.
 254  */
 255 extern lwres_uint16_t lwres_udp_port;
 256
 257 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_contextcreate().
 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_contextcreate().
 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_contextcreate().
 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_contextcreate().
 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_contextcreate().
 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_contextcreate().
 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_contextcreate().
 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_contextcreate().
 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  * returns a pointer to the current config structure.
 542  * Be extremely cautions in modifying the contents of this structure; it
 543  * needs an API to return the various bits of data, walk lists, etc.
 544  *
 545  * Requires:
 546  *      ctx != NULL
 547  */
 548
 549 /*
 550  * Helper functions
 551  */
 552
 553 lwres_result_t
 554 lwres_data_parse(lwres_buffer_t *b, unsigned char **p, lwres_uint16_t *len);
 555
 556 lwres_result_t
 557 lwres_string_parse(lwres_buffer_t *b, char **c, lwres_uint16_t *len);
 558
 559 lwres_result_t
 560 lwres_addr_parse(lwres_buffer_t *b, lwres_addr_t *addr);
 561
 562 lwres_result_t
 563 lwres_getaddrsbyname(lwres_context_t *ctx, const char *name,
 564                      lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp);
 565
 566 lwres_result_t
 567 lwres_getnamebyaddr(lwres_context_t *ctx, lwres_uint32_t addrtype,
 568                     lwres_uint16_t addrlen, const unsigned char *addr,
 569                     lwres_gnbaresponse_t **structp);
 570
 571 lwres_result_t
 572 lwres_getrdatabyname(lwres_context_t *ctx, const char *name,
 573                      lwres_uint16_t rdclass, lwres_uint16_t rdtype,
 574                      lwres_uint32_t flags, lwres_grbnresponse_t **structp);
 575
 576 LWRES_LANG_ENDDECLS
 577
 578 #endif /* LWRES_LWRES_H */