1 /* $NetBSD: lwres.h,v 1.8 2014/12/10 04:38:02 christos Exp $ */ 2 3 /* 4 * Copyright (C) 2004-2007, 2014 Internet Systems Consortium, Inc. ("ISC") 5 * Copyright (C) 2000, 2001 Internet Software Consortium. 6 * 7 * Permission to use, copy, modify, and/or distribute this software for any 8 * purpose with or without fee is hereby granted, provided that the above 9 * copyright notice and this permission notice appear in all copies. 10 * 11 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 12 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 13 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 14 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 15 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 16 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 17 * PERFORMANCE OF THIS SOFTWARE. 18 */ 19 20 /* Id: lwres.h,v 1.57 2007/06/19 23:47:23 tbox Exp */ 21 22 #ifndef LWRES_LWRES_H 23 #define LWRES_LWRES_H 1 24 25 #include <stdio.h> 26 27 #include <lwres/context.h> 28 #include <lwres/lang.h> 29 #include <lwres/list.h> 30 #include <lwres/lwpacket.h> 31 #include <lwres/platform.h> 32 33 /*! \file lwres/lwres.h */ 34 35 /*! 36 * Design notes: 37 * 38 * Each opcode has two structures and three functions which operate on each 39 * structure. For example, using the "no operation/ping" opcode as an 40 * example: 41 * 42 * <ul><li>lwres_nooprequest_t: 43 * 44 * lwres_nooprequest_render() takes a lwres_nooprequest_t and 45 * and renders it into wire format, storing the allocated 46 * buffer information in a passed-in buffer. When this buffer 47 * is no longer needed, it must be freed by 48 * lwres_context_freemem(). All other memory used by the 49 * caller must be freed manually, including the 50 * lwres_nooprequest_t passed in.<br /><br /> 51 * 52 * lwres_nooprequest_parse() takes a wire format message and 53 * breaks it out into a lwres_nooprequest_t. The structure 54 * must be freed via lwres_nooprequest_free() when it is no longer 55 * needed.<br /><br /> 56 * 57 * lwres_nooprequest_free() releases into the lwres_context_t 58 * any space allocated during parsing.</li> 59 * 60 * <li>lwres_noopresponse_t: 61 * 62 * The functions used are similar to the three used for 63 * requests, just with different names.</li></ul> 64 * 65 * Typically, the client will use request_render, response_parse, and 66 * response_free, while the daemon will use request_parse, response_render, 67 * and request_free. 68 * 69 * The basic flow of a typical client is: 70 * 71 * \li fill in a request_t, and call the render function. 72 * 73 * \li Transmit the buffer returned to the daemon. 74 * 75 * \li Wait for a response. 76 * 77 * \li When a response is received, parse it into a response_t. 78 * 79 * \li free the request buffer using lwres_context_freemem(). 80 * 81 * \li free the response structure and its associated buffer using 82 * response_free(). 83 */ 84 85 #define LWRES_UDP_PORT 921 /*%< UDP Port Number */ 86 #define LWRES_RECVLENGTH 16384 /*%< Maximum Packet Length */ 87 #define LWRES_ADDR_MAXLEN 16 /*%< changing this breaks ABI */ 88 #define LWRES_RESOLV_CONF "/etc/resolv.conf" /*%< Location of resolv.conf */ 89 90 /*% DNSSEC is not required (input). Only relevant to rrset queries. */ 91 #define LWRES_FLAG_TRUSTNOTREQUIRED 0x00000001U 92 /*% The data was crypto-verified with DNSSEC (output). */ 93 #define LWRES_FLAG_SECUREDATA 0x00000002U 94 95 /*% no-op */ 96 #define LWRES_OPCODE_NOOP 0x00000000U 97 98 /*% lwres_nooprequest_t */ 99 typedef struct { 100 /* public */ 101 lwres_uint16_t datalength; 102 unsigned char *data; 103 } lwres_nooprequest_t; 104 105 /*% lwres_noopresponse_t */ 106 typedef struct { 107 /* public */ 108 lwres_uint16_t datalength; 109 unsigned char *data; 110 } lwres_noopresponse_t; 111 112 /*% get addresses by name */ 113 #define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U 114 115 /*% lwres_addr_t */ 116 typedef struct lwres_addr lwres_addr_t; 117 118 /*% LWRES_LIST */ 119 typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; 120 121 /*% lwres_addr */ 122 struct lwres_addr { 123 lwres_uint32_t family; 124 lwres_uint16_t length; 125 unsigned char address[LWRES_ADDR_MAXLEN]; 126 lwres_uint32_t zone; 127 LWRES_LINK(lwres_addr_t) link; 128 }; 129 130 /*% lwres_gabnrequest_t */ 131 typedef struct { 132 /* public */ 133 lwres_uint32_t flags; 134 lwres_uint32_t addrtypes; 135 lwres_uint16_t namelen; 136 char *name; 137 } lwres_gabnrequest_t; 138 139 /*% lwres_gabnresponse_t */ 140 typedef struct { 141 /* public */ 142 lwres_uint32_t flags; 143 lwres_uint16_t naliases; 144 lwres_uint16_t naddrs; 145 char *realname; 146 char **aliases; 147 lwres_uint16_t realnamelen; 148 lwres_uint16_t *aliaslen; 149 lwres_addrlist_t addrs; 150 /*! if base != NULL, it will be freed when this structure is freed. */ 151 void *base; 152 size_t baselen; 153 } lwres_gabnresponse_t; 154 155 /*% get name by address */ 156 #define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U 157 158 /*% lwres_gnbarequest_t */ 159 typedef struct { 160 /* public */ 161 lwres_uint32_t flags; 162 lwres_addr_t addr; 163 } lwres_gnbarequest_t; 164 165 /*% lwres_gnbaresponse_t */ 166 typedef struct { 167 /* public */ 168 lwres_uint32_t flags; 169 lwres_uint16_t naliases; 170 char *realname; 171 char **aliases; 172 lwres_uint16_t realnamelen; 173 lwres_uint16_t *aliaslen; 174 /*! if base != NULL, it will be freed when this structure is freed. */ 175 void *base; 176 size_t baselen; 177 } lwres_gnbaresponse_t; 178 179 /*% get rdata by name */ 180 #define LWRES_OPCODE_GETRDATABYNAME 0x00010003U 181 182 /*% lwres_grbnrequest_t */ 183 typedef struct { 184 /* public */ 185 lwres_uint32_t flags; 186 lwres_uint16_t rdclass; 187 lwres_uint16_t rdtype; 188 lwres_uint16_t namelen; 189 char *name; 190 } lwres_grbnrequest_t; 191 192 /*% lwres_grbnresponse_t */ 193 typedef struct { 194 /* public */ 195 lwres_uint32_t flags; 196 lwres_uint16_t rdclass; 197 lwres_uint16_t rdtype; 198 lwres_uint32_t ttl; 199 lwres_uint16_t nrdatas; 200 lwres_uint16_t nsigs; 201 char *realname; 202 lwres_uint16_t realnamelen; 203 unsigned char **rdatas; 204 lwres_uint16_t *rdatalen; 205 unsigned char **sigs; 206 lwres_uint16_t *siglen; 207 /*% if base != NULL, it will be freed when this structure is freed. */ 208 void *base; 209 size_t baselen; 210 } lwres_grbnresponse_t; 211 212 /*% Used by lwres_getrrsetbyname() */ 213 #define LWRDATA_VALIDATED 0x00000001 214 215 /*! 216 * resolv.conf data 217 */ 218 219 #define LWRES_CONFMAXNAMESERVERS 3 /*%< max 3 nameserver entries */ 220 #define LWRES_CONFMAXLWSERVERS 1 /*%< max 1 lwserver entry */ 221 #define LWRES_CONFMAXSEARCH 8 /*%< max 8 domains in search entry */ 222 #define LWRES_CONFMAXLINELEN 256 /*%< max size of a line */ 223 #define LWRES_CONFMAXSORTLIST 10 /*%< max 10 */ 224 225 /*% lwres_conf_t */ 226 typedef struct { 227 lwres_context_t *lwctx; 228 lwres_addr_t nameservers[LWRES_CONFMAXNAMESERVERS]; 229 lwres_uint8_t nsnext; /*%< index for next free slot */ 230 231 lwres_addr_t lwservers[LWRES_CONFMAXLWSERVERS]; 232 lwres_uint8_t lwnext; /*%< index for next free slot */ 233 234 char *domainname; 235 236 char *search[LWRES_CONFMAXSEARCH]; 237 lwres_uint8_t searchnxt; /*%< index for next free slot */ 238 239 struct { 240 lwres_addr_t addr; 241 /*% mask has a non-zero 'family' and 'length' if set */ 242 lwres_addr_t mask; 243 } sortlist[LWRES_CONFMAXSORTLIST]; 244 lwres_uint8_t sortlistnxt; 245 246 lwres_uint8_t resdebug; /*%< non-zero if 'options debug' set */ 247 lwres_uint8_t ndots; /*%< set to n in 'options ndots:n' */ 248 lwres_uint8_t no_tld_query; /*%< non-zero if 'options no_tld_query' */ 249 } lwres_conf_t; 250 251 #define LWRES_ADDRTYPE_V4 0x00000001U /*%< ipv4 */ 252 #define LWRES_ADDRTYPE_V6 0x00000002U /*%< ipv6 */ 253 254 #define LWRES_MAX_ALIASES 16 /*%< max # of aliases */ 255 #define LWRES_MAX_ADDRS 64 /*%< max # of addrs */ 256 257 LWRES_LANG_BEGINDECLS 258 259 /*% This is in host byte order. */ 260 LIBLWRES_EXTERNAL_DATA extern lwres_uint16_t lwres_udp_port; 261 262 LIBLWRES_EXTERNAL_DATA extern const char *lwres_resolv_conf; 263 264 lwres_result_t 265 lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req, 266 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 267 268 lwres_result_t 269 lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req, 270 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 271 272 lwres_result_t 273 lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, 274 lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp); 275 276 lwres_result_t 277 lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, 278 lwres_lwpacket_t *pkt, 279 lwres_gabnresponse_t **structp); 280 281 void 282 lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp); 283 /**< 284 * Frees any dynamically allocated memory for this structure. 285 * 286 * Requires: 287 * 288 * ctx != NULL, and be a context returned via lwres_context_create(). 289 * 290 * structp != NULL && *structp != NULL. 291 * 292 * Ensures: 293 * 294 * *structp == NULL. 295 * 296 * All memory allocated by this structure will be returned to the 297 * system via the context's free function. 298 */ 299 300 void 301 lwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnresponse_t **structp); 302 /**< 303 * Frees any dynamically allocated memory for this structure. 304 * 305 * Requires: 306 * 307 * ctx != NULL, and be a context returned via lwres_context_create(). 308 * 309 * structp != NULL && *structp != NULL. 310 * 311 * Ensures: 312 * 313 * *structp == NULL. 314 * 315 * All memory allocated by this structure will be returned to the 316 * system via the context's free function. 317 */ 318 319 320 lwres_result_t 321 lwres_gnbarequest_render(lwres_context_t *ctx, lwres_gnbarequest_t *req, 322 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 323 324 lwres_result_t 325 lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req, 326 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 327 328 lwres_result_t 329 lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, 330 lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp); 331 332 lwres_result_t 333 lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, 334 lwres_lwpacket_t *pkt, 335 lwres_gnbaresponse_t **structp); 336 337 void 338 lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp); 339 /**< 340 * Frees any dynamically allocated memory for this structure. 341 * 342 * Requires: 343 * 344 * ctx != NULL, and be a context returned via lwres_context_create(). 345 * 346 * structp != NULL && *structp != NULL. 347 * 348 * Ensures: 349 * 350 * *structp == NULL. 351 * 352 * All memory allocated by this structure will be returned to the 353 * system via the context's free function. 354 */ 355 356 void 357 lwres_gnbaresponse_free(lwres_context_t *ctx, lwres_gnbaresponse_t **structp); 358 /**< 359 * Frees any dynamically allocated memory for this structure. 360 * 361 * Requires: 362 * 363 * ctx != NULL, and be a context returned via lwres_context_create(). 364 * 365 * structp != NULL && *structp != NULL. 366 * 367 * Ensures: 368 * 369 * *structp == NULL. 370 * 371 * All memory allocated by this structure will be returned to the 372 * system via the context's free function. 373 */ 374 375 lwres_result_t 376 lwres_grbnrequest_render(lwres_context_t *ctx, lwres_grbnrequest_t *req, 377 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 378 379 lwres_result_t 380 lwres_grbnresponse_render(lwres_context_t *ctx, lwres_grbnresponse_t *req, 381 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 382 383 lwres_result_t 384 lwres_grbnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, 385 lwres_lwpacket_t *pkt, lwres_grbnrequest_t **structp); 386 387 lwres_result_t 388 lwres_grbnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, 389 lwres_lwpacket_t *pkt, 390 lwres_grbnresponse_t **structp); 391 392 void 393 lwres_grbnrequest_free(lwres_context_t *ctx, lwres_grbnrequest_t **structp); 394 /**< 395 * Frees any dynamically allocated memory for this structure. 396 * 397 * Requires: 398 * 399 * ctx != NULL, and be a context returned via lwres_context_create(). 400 * 401 * structp != NULL && *structp != NULL. 402 * 403 * Ensures: 404 * 405 * *structp == NULL. 406 * 407 * All memory allocated by this structure will be returned to the 408 * system via the context's free function. 409 */ 410 411 void 412 lwres_grbnresponse_free(lwres_context_t *ctx, lwres_grbnresponse_t **structp); 413 /**< 414 * Frees any dynamically allocated memory for this structure. 415 * 416 * Requires: 417 * 418 * ctx != NULL, and be a context returned via lwres_context_create(). 419 * 420 * structp != NULL && *structp != NULL. 421 * 422 * Ensures: 423 * 424 * *structp == NULL. 425 * 426 * All memory allocated by this structure will be returned to the 427 * system via the context's free function. 428 */ 429 430 lwres_result_t 431 lwres_nooprequest_render(lwres_context_t *ctx, lwres_nooprequest_t *req, 432 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 433 /**< 434 * Allocate space and render into wire format a noop request packet. 435 * 436 * Requires: 437 * 438 * ctx != NULL, and be a context returned via lwres_context_create(). 439 * 440 * b != NULL, and points to a lwres_buffer_t. The contents of the 441 * buffer structure will be initialized to contain the wire-format 442 * noop request packet. 443 * 444 * Caller needs to fill in parts of "pkt" before calling: 445 * serial, maxrecv, result. 446 * 447 * Returns: 448 * 449 * Returns 0 on success, non-zero on failure. 450 * 451 * On successful return, *b will contain data about the wire-format 452 * packet. It can be transmitted in any way, including lwres_sendblock(). 453 */ 454 455 lwres_result_t 456 lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req, 457 lwres_lwpacket_t *pkt, lwres_buffer_t *b); 458 459 lwres_result_t 460 lwres_nooprequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, 461 lwres_lwpacket_t *pkt, lwres_nooprequest_t **structp); 462 /**< 463 * Parse a noop request. Note that to get here, the lwpacket must have 464 * already been parsed and removed by the caller, otherwise it would be 465 * pretty hard for it to know this is the right function to call. 466 * 467 * The function verifies bits of the header, but does not modify it. 468 */ 469 470 lwres_result_t 471 lwres_noopresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, 472 lwres_lwpacket_t *pkt, 473 lwres_noopresponse_t **structp); 474 475 void 476 lwres_nooprequest_free(lwres_context_t *ctx, lwres_nooprequest_t **structp); 477 478 void 479 lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp); 480 481 /**< 482 * Frees any dynamically allocated memory for this structure. 483 * 484 * Requires: 485 * 486 * ctx != NULL, and be a context returned via lwres_context_create(). 487 * 488 * structp != NULL && *structp != NULL. 489 * 490 * Ensures: 491 * 492 * *structp == NULL. 493 * 494 * All memory allocated by this structure will be returned to the 495 * system via the context's free function. 496 */ 497 498 lwres_result_t 499 lwres_conf_parse(lwres_context_t *ctx, const char *filename); 500 /**< 501 * parses a resolv.conf-format file and stores the results in the structure 502 * pointed to by *ctx. 503 * 504 * Requires: 505 * ctx != NULL 506 * filename != NULL && strlen(filename) > 0 507 * 508 * Returns: 509 * LWRES_R_SUCCESS on a successful parse. 510 * Anything else on error, although the structure may be partially filled 511 * in. 512 */ 513 514 lwres_result_t 515 lwres_conf_print(lwres_context_t *ctx, FILE *fp); 516 /**< 517 * Prints a resolv.conf-format of confdata output to fp. 518 * 519 * Requires: 520 * ctx != NULL 521 */ 522 523 void 524 lwres_conf_init(lwres_context_t *ctx); 525 /**< 526 * sets all internal fields to a default state. Used to initialize a new 527 * lwres_conf_t structure (not reset a used on). 528 * 529 * Requires: 530 * ctx != NULL 531 */ 532 533 void 534 lwres_conf_clear(lwres_context_t *ctx); 535 /**< 536 * frees all internally allocated memory in confdata. Uses the memory 537 * routines supplied by ctx. 538 * 539 * Requires: 540 * ctx != NULL 541 */ 542 543 lwres_conf_t * 544 lwres_conf_get(lwres_context_t *ctx); 545 /**< 546 * Be extremely cautions in modifying the contents of this structure; it 547 * needs an API to return the various bits of data, walk lists, etc. 548 * 549 * Requires: 550 * ctx != NULL 551 */ 552 553 /* 554 * Helper functions 555 */ 556 557 lwres_result_t 558 lwres_data_parse(lwres_buffer_t *b, unsigned char **p, lwres_uint16_t *len); 559 560 lwres_result_t 561 lwres_string_parse(lwres_buffer_t *b, char **c, lwres_uint16_t *len); 562 563 lwres_result_t 564 lwres_addr_parse(lwres_buffer_t *b, lwres_addr_t *addr); 565 566 lwres_result_t 567 lwres_getaddrsbyname(lwres_context_t *ctx, const char *name, 568 lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp); 569 570 lwres_result_t 571 lwres_getnamebyaddr(lwres_context_t *ctx, lwres_uint32_t addrtype, 572 lwres_uint16_t addrlen, const unsigned char *addr, 573 lwres_gnbaresponse_t **structp); 574 575 lwres_result_t 576 lwres_getrdatabyname(lwres_context_t *ctx, const char *name, 577 lwres_uint16_t rdclass, lwres_uint16_t rdtype, 578 lwres_uint32_t flags, lwres_grbnresponse_t **structp); 579 580 LWRES_LANG_ENDDECLS 581 582 #endif /* LWRES_LWRES_H */ 583