/contrib/bind9/lib/lwres/include/lwres/lwres.h

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 579 lines · 217 code · 77 blank · 285 comment · 0 complexity · 4d05338868533a9b8599f415425277a4 MD5 · raw file

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