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