lwres.h revision 135446
1269639Sgjb/* 2259994Sgjb * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") 3259994Sgjb * Copyright (C) 2000, 2001 Internet Software Consortium. 4259994Sgjb * 5259994Sgjb * Permission to use, copy, modify, and distribute this software for any 6283161Sgjb * purpose with or without fee is hereby granted, provided that the above 7283161Sgjb * copyright notice and this permission notice appear in all copies. 8283161Sgjb * 9283161Sgjb * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10283161Sgjb * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11283161Sgjb * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12283161Sgjb * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13284517Sgjb * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14283161Sgjb * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15283161Sgjb * PERFORMANCE OF THIS SOFTWARE. 16283161Sgjb */ 17283161Sgjb 18283880Sgjb/* $Id: lwres.h,v 1.49.12.3 2004/03/08 09:05:11 marka Exp $ */ 19269639Sgjb 20283161Sgjb#ifndef LWRES_LWRES_H 21283161Sgjb#define LWRES_LWRES_H 1 22283161Sgjb 23283161Sgjb#include <stdio.h> 24283161Sgjb 25283161Sgjb#include <lwres/context.h> 26283161Sgjb#include <lwres/lang.h> 27283161Sgjb#include <lwres/list.h> 28283161Sgjb#include <lwres/lwpacket.h> 29283161Sgjb#include <lwres/platform.h> 30283161Sgjb 31283161Sgjb/* 32283161Sgjb * Design notes: 33283161Sgjb * 34288469Sgjb * Each opcode has two structures and three functions which operate on each 35288469Sgjb * structure. For example, using the "no operation/ping" opcode as an 36283161Sgjb * example: 37283161Sgjb * 38283161Sgjb * lwres_nooprequest_t: 39283161Sgjb * 40283161Sgjb * lwres_nooprequest_render() takes a lwres_nooprequest_t and 41283161Sgjb * and renders it into wire format, storing the allocated 42283161Sgjb * buffer information in a passed-in buffer. When this buffer 43283161Sgjb * is no longer needed, it must be freed by 44283161Sgjb * lwres_context_freemem(). All other memory used by the 45282500Sgjb * caller must be freed manually, including the 46282500Sgjb * 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 103typedef struct { 104 /* public */ 105 lwres_uint16_t datalength; 106 unsigned char *data; 107} lwres_nooprequest_t; 108 109typedef 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 120typedef struct lwres_addr lwres_addr_t; 121typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; 122 123struct 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 130typedef 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 138typedef 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 157typedef struct { 158 /* public */ 159 lwres_uint32_t flags; 160 lwres_addr_t addr; 161} lwres_gnbarequest_t; 162 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/* 177 * get rdata by name 178 */ 179#define LWRES_OPCODE_GETRDATABYNAME 0x00010003U 180 181typedef 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 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#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 220typedef 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 251LWRES_LANG_BEGINDECLS 252 253/* 254 * This is in host byte order. 255 */ 256LIBLWRES_EXTERNAL_DATA extern lwres_uint16_t lwres_udp_port; 257 258LIBLWRES_EXTERNAL_DATA extern const char *lwres_resolv_conf; 259 260lwres_result_t 261lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req, 262 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 263 264lwres_result_t 265lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req, 266 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 267 268lwres_result_t 269lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, 270 lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp); 271 272lwres_result_t 273lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, 274 lwres_lwpacket_t *pkt, 275 lwres_gabnresponse_t **structp); 276 277void 278lwres_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 296void 297lwres_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 316lwres_result_t 317lwres_gnbarequest_render(lwres_context_t *ctx, lwres_gnbarequest_t *req, 318 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 319 320lwres_result_t 321lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req, 322 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 323 324lwres_result_t 325lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, 326 lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp); 327 328lwres_result_t 329lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, 330 lwres_lwpacket_t *pkt, 331 lwres_gnbaresponse_t **structp); 332 333void 334lwres_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 352void 353lwres_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 371lwres_result_t 372lwres_grbnrequest_render(lwres_context_t *ctx, lwres_grbnrequest_t *req, 373 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 374 375lwres_result_t 376lwres_grbnresponse_render(lwres_context_t *ctx, lwres_grbnresponse_t *req, 377 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 378 379lwres_result_t 380lwres_grbnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, 381 lwres_lwpacket_t *pkt, lwres_grbnrequest_t **structp); 382 383lwres_result_t 384lwres_grbnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, 385 lwres_lwpacket_t *pkt, 386 lwres_grbnresponse_t **structp); 387 388void 389lwres_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 407void 408lwres_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 426lwres_result_t 427lwres_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 451lwres_result_t 452lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req, 453 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 454 455lwres_result_t 456lwres_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 466lwres_result_t 467lwres_noopresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, 468 lwres_lwpacket_t *pkt, 469 lwres_noopresponse_t **structp); 470 471void 472lwres_nooprequest_free(lwres_context_t *ctx, lwres_nooprequest_t **structp); 473 474void 475lwres_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 494lwres_result_t 495lwres_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 510lwres_result_t 511lwres_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 519void 520lwres_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 529void 530lwres_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 539lwres_conf_t * 540lwres_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 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