1 /* 2 * Copyright (C) 2004-2007, 2014 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_uint32_t zone; 125 LWRES_LINK(lwres_addr_t) link; 126 }; 127 128 /*% lwres_gabnrequest_t */ 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 /*% lwres_gabnresponse_t */ 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 /*% get name by address */ 154 #define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U 155 156 /*% lwres_gnbarequest_t */ 157 typedef struct { 158 /* public */ 159 lwres_uint32_t flags; 160 lwres_addr_t addr; 161 } lwres_gnbarequest_t; 162 163 /*% lwres_gnbaresponse_t */ 164 typedef struct { 165 /* public */ 166 lwres_uint32_t flags; 167 lwres_uint16_t naliases; 168 char *realname; 169 char **aliases; 170 lwres_uint16_t realnamelen; 171 lwres_uint16_t *aliaslen; 172 /*! if base != NULL, it will be freed when this structure is freed. */ 173 void *base; 174 size_t baselen; 175 } lwres_gnbaresponse_t; 176 177 /*% get rdata by name */ 178 #define LWRES_OPCODE_GETRDATABYNAME 0x00010003U 179 180 /*% lwres_grbnrequest_t */ 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 /*% lwres_grbnresponse_t */ 191 typedef struct { 192 /* public */ 193 lwres_uint32_t flags; 194 lwres_uint16_t rdclass; 195 lwres_uint16_t rdtype; 196 lwres_uint32_t ttl; 197 lwres_uint16_t nrdatas; 198 lwres_uint16_t nsigs; 199 char *realname; 200 lwres_uint16_t realnamelen; 201 unsigned char **rdatas; 202 lwres_uint16_t *rdatalen; 203 unsigned char **sigs; 204 lwres_uint16_t *siglen; 205 /*% if base != NULL, it will be freed when this structure is freed. */ 206 void *base; 207 size_t baselen; 208 } lwres_grbnresponse_t; 209 210 /*% Used by lwres_getrrsetbyname() */ 211 #define LWRDATA_VALIDATED 0x00000001 212 213 /*! 214 * resolv.conf data 215 */ 216 217 #define LWRES_CONFMAXNAMESERVERS 3 /*%< max 3 "nameserver" entries */ 218 #define LWRES_CONFMAXLWSERVERS 1 /*%< max 1 "lwserver" entry */ 219 #define LWRES_CONFMAXSEARCH 8 /*%< max 8 domains in "search" entry */ 220 #define LWRES_CONFMAXLINELEN 256 /*%< max size of a line */ 221 #define LWRES_CONFMAXSORTLIST 10 /*%< max 10 */ 222 223 /*% lwres_conf_t */ 224 typedef struct { 225 lwres_context_t *lwctx; 226 lwres_addr_t nameservers[LWRES_CONFMAXNAMESERVERS]; 227 lwres_uint8_t nsnext; /*%< index for next free slot */ 228 229 lwres_addr_t lwservers[LWRES_CONFMAXLWSERVERS]; 230 lwres_uint8_t lwnext; /*%< index for next free slot */ 231 232 char *domainname; 233 234 char *search[LWRES_CONFMAXSEARCH]; 235 lwres_uint8_t searchnxt; /*%< index for next free slot */ 236 237 struct { 238 lwres_addr_t addr; 239 /*% mask has a non-zero 'family' and 'length' if set */ 240 lwres_addr_t mask; 241 } sortlist[LWRES_CONFMAXSORTLIST]; 242 lwres_uint8_t sortlistnxt; 243 244 lwres_uint8_t resdebug; /*%< non-zero if 'options debug' set */ 245 lwres_uint8_t ndots; /*%< set to n in 'options ndots:n' */ 246 lwres_uint8_t no_tld_query; /*%< non-zero if 'options no_tld_query' */ 247 } lwres_conf_t; 248 249 #define LWRES_ADDRTYPE_V4 0x00000001U /*%< ipv4 */ 250 #define LWRES_ADDRTYPE_V6 0x00000002U /*%< ipv6 */ 251 252 #define LWRES_MAX_ALIASES 16 /*%< max # of aliases */ 253 #define LWRES_MAX_ADDRS 64 /*%< max # of addrs */ 254 255 LWRES_LANG_BEGINDECLS 256 257 /*% This is in host byte order. */ 258 LIBLWRES_EXTERNAL_DATA extern lwres_uint16_t lwres_udp_port; 259 260 LIBLWRES_EXTERNAL_DATA extern const char *lwres_resolv_conf; 261 262 lwres_result_t 263 lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req, 264 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 265 266 lwres_result_t 267 lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req, 268 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 269 270 lwres_result_t 271 lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, 272 lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp); 273 274 lwres_result_t 275 lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, 276 lwres_lwpacket_t *pkt, 277 lwres_gabnresponse_t **structp); 278 279 void 280 lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp); 281 /**< 282 * Frees any dynamically allocated memory for this structure. 283 * 284 * Requires: 285 * 286 * ctx != NULL, and be a context returned via lwres_context_create(). 287 * 288 * structp != NULL && *structp != NULL. 289 * 290 * Ensures: 291 * 292 * *structp == NULL. 293 * 294 * All memory allocated by this structure will be returned to the 295 * system via the context's free function. 296 */ 297 298 void 299 lwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnresponse_t **structp); 300 /**< 301 * Frees any dynamically allocated memory for this structure. 302 * 303 * Requires: 304 * 305 * ctx != NULL, and be a context returned via lwres_context_create(). 306 * 307 * structp != NULL && *structp != NULL. 308 * 309 * Ensures: 310 * 311 * *structp == NULL. 312 * 313 * All memory allocated by this structure will be returned to the 314 * system via the context's free function. 315 */ 316 317 318 lwres_result_t 319 lwres_gnbarequest_render(lwres_context_t *ctx, lwres_gnbarequest_t *req, 320 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 321 322 lwres_result_t 323 lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req, 324 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 325 326 lwres_result_t 327 lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, 328 lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp); 329 330 lwres_result_t 331 lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, 332 lwres_lwpacket_t *pkt, 333 lwres_gnbaresponse_t **structp); 334 335 void 336 lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp); 337 /**< 338 * Frees any dynamically allocated memory for this structure. 339 * 340 * Requires: 341 * 342 * ctx != NULL, and be a context returned via lwres_context_create(). 343 * 344 * structp != NULL && *structp != NULL. 345 * 346 * Ensures: 347 * 348 * *structp == NULL. 349 * 350 * All memory allocated by this structure will be returned to the 351 * system via the context's free function. 352 */ 353 354 void 355 lwres_gnbaresponse_free(lwres_context_t *ctx, lwres_gnbaresponse_t **structp); 356 /**< 357 * Frees any dynamically allocated memory for this structure. 358 * 359 * Requires: 360 * 361 * ctx != NULL, and be a context returned via lwres_context_create(). 362 * 363 * structp != NULL && *structp != NULL. 364 * 365 * Ensures: 366 * 367 * *structp == NULL. 368 * 369 * All memory allocated by this structure will be returned to the 370 * system via the context's free function. 371 */ 372 373 lwres_result_t 374 lwres_grbnrequest_render(lwres_context_t *ctx, lwres_grbnrequest_t *req, 375 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 376 377 lwres_result_t 378 lwres_grbnresponse_render(lwres_context_t *ctx, lwres_grbnresponse_t *req, 379 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 380 381 lwres_result_t 382 lwres_grbnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, 383 lwres_lwpacket_t *pkt, lwres_grbnrequest_t **structp); 384 385 lwres_result_t 386 lwres_grbnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, 387 lwres_lwpacket_t *pkt, 388 lwres_grbnresponse_t **structp); 389 390 void 391 lwres_grbnrequest_free(lwres_context_t *ctx, lwres_grbnrequest_t **structp); 392 /**< 393 * Frees any dynamically allocated memory for this structure. 394 * 395 * Requires: 396 * 397 * ctx != NULL, and be a context returned via lwres_context_create(). 398 * 399 * structp != NULL && *structp != NULL. 400 * 401 * Ensures: 402 * 403 * *structp == NULL. 404 * 405 * All memory allocated by this structure will be returned to the 406 * system via the context's free function. 407 */ 408 409 void 410 lwres_grbnresponse_free(lwres_context_t *ctx, lwres_grbnresponse_t **structp); 411 /**< 412 * Frees any dynamically allocated memory for this structure. 413 * 414 * Requires: 415 * 416 * ctx != NULL, and be a context returned via lwres_context_create(). 417 * 418 * structp != NULL && *structp != NULL. 419 * 420 * Ensures: 421 * 422 * *structp == NULL. 423 * 424 * All memory allocated by this structure will be returned to the 425 * system via the context's free function. 426 */ 427 428 lwres_result_t 429 lwres_nooprequest_render(lwres_context_t *ctx, lwres_nooprequest_t *req, 430 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 431 /**< 432 * Allocate space and render into wire format a noop request packet. 433 * 434 * Requires: 435 * 436 * ctx != NULL, and be a context returned via lwres_context_create(). 437 * 438 * b != NULL, and points to a lwres_buffer_t. The contents of the 439 * buffer structure will be initialized to contain the wire-format 440 * noop request packet. 441 * 442 * Caller needs to fill in parts of "pkt" before calling: 443 * serial, maxrecv, result. 444 * 445 * Returns: 446 * 447 * Returns 0 on success, non-zero on failure. 448 * 449 * On successful return, *b will contain data about the wire-format 450 * packet. It can be transmitted in any way, including lwres_sendblock(). 451 */ 452 453 lwres_result_t 454 lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req, 455 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 456 457 lwres_result_t 458 lwres_nooprequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, 459 lwres_lwpacket_t *pkt, lwres_nooprequest_t **structp); 460 /**< 461 * Parse a noop request. Note that to get here, the lwpacket must have 462 * already been parsed and removed by the caller, otherwise it would be 463 * pretty hard for it to know this is the right function to call. 464 * 465 * The function verifies bits of the header, but does not modify it. 466 */ 467 468 lwres_result_t 469 lwres_noopresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, 470 lwres_lwpacket_t *pkt, 471 lwres_noopresponse_t **structp); 472 473 void 474 lwres_nooprequest_free(lwres_context_t *ctx, lwres_nooprequest_t **structp); 475 476 void 477 lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp); 478 479 /**< 480 * Frees any dynamically allocated memory for this structure. 481 * 482 * Requires: 483 * 484 * ctx != NULL, and be a context returned via lwres_context_create(). 485 * 486 * structp != NULL && *structp != NULL. 487 * 488 * Ensures: 489 * 490 * *structp == NULL. 491 * 492 * All memory allocated by this structure will be returned to the 493 * system via the context's free function. 494 */ 495 496 lwres_result_t 497 lwres_conf_parse(lwres_context_t *ctx, const char *filename); 498 /**< 499 * parses a resolv.conf-format file and stores the results in the structure 500 * pointed to by *ctx. 501 * 502 * Requires: 503 * ctx != NULL 504 * filename != NULL && strlen(filename) > 0 505 * 506 * Returns: 507 * LWRES_R_SUCCESS on a successful parse. 508 * Anything else on error, although the structure may be partially filled 509 * in. 510 */ 511 512 lwres_result_t 513 lwres_conf_print(lwres_context_t *ctx, FILE *fp); 514 /**< 515 * Prints a resolv.conf-format of confdata output to fp. 516 * 517 * Requires: 518 * ctx != NULL 519 */ 520 521 void 522 lwres_conf_init(lwres_context_t *ctx); 523 /**< 524 * sets all internal fields to a default state. Used to initialize a new 525 * lwres_conf_t structure (not reset a used on). 526 * 527 * Requires: 528 * ctx != NULL 529 */ 530 531 void 532 lwres_conf_clear(lwres_context_t *ctx); 533 /**< 534 * frees all internally allocated memory in confdata. Uses the memory 535 * routines supplied by ctx. 536 * 537 * Requires: 538 * ctx != NULL 539 */ 540 541 lwres_conf_t * 542 lwres_conf_get(lwres_context_t *ctx); 543 /**< 544 * Be extremely cautions in modifying the contents of this structure; it 545 * needs an API to return the various bits of data, walk lists, etc. 546 * 547 * Requires: 548 * ctx != NULL 549 */ 550 551 /* 552 * Helper functions 553 */ 554 555 lwres_result_t 556 lwres_data_parse(lwres_buffer_t *b, unsigned char **p, lwres_uint16_t *len); 557 558 lwres_result_t 559 lwres_string_parse(lwres_buffer_t *b, char **c, lwres_uint16_t *len); 560 561 lwres_result_t 562 lwres_addr_parse(lwres_buffer_t *b, lwres_addr_t *addr); 563 564 lwres_result_t 565 lwres_getaddrsbyname(lwres_context_t *ctx, const char *name, 566 lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp); 567 568 lwres_result_t 569 lwres_getnamebyaddr(lwres_context_t *ctx, lwres_uint32_t addrtype, 570 lwres_uint16_t addrlen, const unsigned char *addr, 571 lwres_gnbaresponse_t **structp); 572 573 lwres_result_t 574 lwres_getrdatabyname(lwres_context_t *ctx, const char *name, 575 lwres_uint16_t rdclass, lwres_uint16_t rdtype, 576 lwres_uint32_t flags, lwres_grbnresponse_t **structp); 577 578 LWRES_LANG_ENDDECLS 579 580 #endif /* LWRES_LWRES_H */ 581