/contrib/bind9/lib/dns/include/dns/dispatch.h

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 501 lines · 94 code · 40 blank · 367 comment · 0 complexity · aa2fb931d22dce36601e7b05cbe1dc8b MD5 · raw file

  1. /*
  2. * Copyright (C) 2004-2009, 2012 Internet Systems Consortium, Inc. ("ISC")
  3. * Copyright (C) 1999-2003 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$ */
  18. #ifndef DNS_DISPATCH_H
  19. #define DNS_DISPATCH_H 1
  20. /*****
  21. ***** Module Info
  22. *****/
  23. /*! \file dns/dispatch.h
  24. * \brief
  25. * DNS Dispatch Management
  26. * Shared UDP and single-use TCP dispatches for queries and responses.
  27. *
  28. * MP:
  29. *
  30. *\li All locking is performed internally to each dispatch.
  31. * Restrictions apply to dns_dispatch_removeresponse().
  32. *
  33. * Reliability:
  34. *
  35. * Resources:
  36. *
  37. * Security:
  38. *
  39. *\li Depends on the isc_socket_t and dns_message_t for prevention of
  40. * buffer overruns.
  41. *
  42. * Standards:
  43. *
  44. *\li None.
  45. */
  46. /***
  47. *** Imports
  48. ***/
  49. #include <isc/buffer.h>
  50. #include <isc/lang.h>
  51. #include <isc/socket.h>
  52. #include <isc/types.h>
  53. #include <dns/types.h>
  54. ISC_LANG_BEGINDECLS
  55. /*%
  56. * This event is sent to a task when a response comes in.
  57. * No part of this structure should ever be modified by the caller,
  58. * other than parts of the buffer. The holy parts of the buffer are
  59. * the base and size of the buffer. All other parts of the buffer may
  60. * be used. On event delivery the used region contains the packet.
  61. *
  62. * "id" is the received message id,
  63. *
  64. * "addr" is the host that sent it to us,
  65. *
  66. * "buffer" holds state on the received data.
  67. *
  68. * The "free" routine for this event will clean up itself as well as
  69. * any buffer space allocated from common pools.
  70. */
  71. struct dns_dispatchevent {
  72. ISC_EVENT_COMMON(dns_dispatchevent_t); /*%< standard event common */
  73. isc_result_t result; /*%< result code */
  74. isc_int32_t id; /*%< message id */
  75. isc_sockaddr_t addr; /*%< address recv'd from */
  76. struct in6_pktinfo pktinfo; /*%< reply info for v6 */
  77. isc_buffer_t buffer; /*%< data buffer */
  78. isc_uint32_t attributes; /*%< mirrored from socket.h */
  79. };
  80. /*@{*/
  81. /*%
  82. * Attributes for added dispatchers.
  83. *
  84. * Values with the mask 0xffff0000 are application defined.
  85. * Values with the mask 0x0000ffff are library defined.
  86. *
  87. * Insane values (like setting both TCP and UDP) are not caught. Don't
  88. * do that.
  89. *
  90. * _PRIVATE
  91. * The dispatcher cannot be shared.
  92. *
  93. * _TCP, _UDP
  94. * The dispatcher is a TCP or UDP socket.
  95. *
  96. * _IPV4, _IPV6
  97. * The dispatcher uses an IPv4 or IPv6 socket.
  98. *
  99. * _NOLISTEN
  100. * The dispatcher should not listen on the socket.
  101. *
  102. * _MAKEQUERY
  103. * The dispatcher can be used to issue queries to other servers, and
  104. * accept replies from them.
  105. *
  106. * _RANDOMPORT
  107. * Previously used to indicate that the port of a dispatch UDP must be
  108. * chosen randomly. This behavior now always applies and the attribute
  109. * is obsoleted.
  110. *
  111. * _EXCLUSIVE
  112. * A separate socket will be used on-demand for each transaction.
  113. */
  114. #define DNS_DISPATCHATTR_PRIVATE 0x00000001U
  115. #define DNS_DISPATCHATTR_TCP 0x00000002U
  116. #define DNS_DISPATCHATTR_UDP 0x00000004U
  117. #define DNS_DISPATCHATTR_IPV4 0x00000008U
  118. #define DNS_DISPATCHATTR_IPV6 0x00000010U
  119. #define DNS_DISPATCHATTR_NOLISTEN 0x00000020U
  120. #define DNS_DISPATCHATTR_MAKEQUERY 0x00000040U
  121. #define DNS_DISPATCHATTR_CONNECTED 0x00000080U
  122. /*#define DNS_DISPATCHATTR_RANDOMPORT 0x00000100U*/
  123. #define DNS_DISPATCHATTR_EXCLUSIVE 0x00000200U
  124. /*@}*/
  125. isc_result_t
  126. dns_dispatchmgr_create(isc_mem_t *mctx, isc_entropy_t *entropy,
  127. dns_dispatchmgr_t **mgrp);
  128. /*%<
  129. * Creates a new dispatchmgr object.
  130. *
  131. * Requires:
  132. *\li "mctx" be a valid memory context.
  133. *
  134. *\li mgrp != NULL && *mgrp == NULL
  135. *
  136. *\li "entropy" may be NULL, in which case an insecure random generator
  137. * will be used. If it is non-NULL, it must be a valid entropy
  138. * source.
  139. *
  140. * Returns:
  141. *\li ISC_R_SUCCESS -- all ok
  142. *
  143. *\li anything else -- failure
  144. */
  145. void
  146. dns_dispatchmgr_destroy(dns_dispatchmgr_t **mgrp);
  147. /*%<
  148. * Destroys the dispatchmgr when it becomes empty. This could be
  149. * immediately.
  150. *
  151. * Requires:
  152. *\li mgrp != NULL && *mgrp is a valid dispatchmgr.
  153. */
  154. void
  155. dns_dispatchmgr_setblackhole(dns_dispatchmgr_t *mgr, dns_acl_t *blackhole);
  156. /*%<
  157. * Sets the dispatcher's "blackhole list," a list of addresses that will
  158. * be ignored by all dispatchers created by the dispatchmgr.
  159. *
  160. * Requires:
  161. * \li mgrp is a valid dispatchmgr
  162. * \li blackhole is a valid acl
  163. */
  164. dns_acl_t *
  165. dns_dispatchmgr_getblackhole(dns_dispatchmgr_t *mgr);
  166. /*%<
  167. * Gets a pointer to the dispatcher's current blackhole list,
  168. * without incrementing its reference count.
  169. *
  170. * Requires:
  171. *\li mgr is a valid dispatchmgr
  172. * Returns:
  173. *\li A pointer to the current blackhole list, or NULL.
  174. */
  175. void
  176. dns_dispatchmgr_setblackportlist(dns_dispatchmgr_t *mgr,
  177. dns_portlist_t *portlist);
  178. /*%<
  179. * This function is deprecated. Use dns_dispatchmgr_setavailports() instead.
  180. *
  181. * Requires:
  182. *\li mgr is a valid dispatchmgr
  183. */
  184. dns_portlist_t *
  185. dns_dispatchmgr_getblackportlist(dns_dispatchmgr_t *mgr);
  186. /*%<
  187. * This function is deprecated and always returns NULL.
  188. *
  189. * Requires:
  190. *\li mgr is a valid dispatchmgr
  191. */
  192. isc_result_t
  193. dns_dispatchmgr_setavailports(dns_dispatchmgr_t *mgr, isc_portset_t *v4portset,
  194. isc_portset_t *v6portset);
  195. /*%<
  196. * Sets a list of UDP ports that can be used for outgoing UDP messages.
  197. *
  198. * Requires:
  199. *\li mgr is a valid dispatchmgr
  200. *\li v4portset is NULL or a valid port set
  201. *\li v6portset is NULL or a valid port set
  202. */
  203. void
  204. dns_dispatchmgr_setstats(dns_dispatchmgr_t *mgr, isc_stats_t *stats);
  205. /*%<
  206. * Sets statistics counter for the dispatchmgr. This function is expected to
  207. * be called only on zone creation (when necessary).
  208. * Once installed, it cannot be removed or replaced. Also, there is no
  209. * interface to get the installed stats from the zone; the caller must keep the
  210. * stats to reference (e.g. dump) it later.
  211. *
  212. * Requires:
  213. *\li mgr is a valid dispatchmgr with no managed dispatch.
  214. *\li stats is a valid statistics supporting resolver statistics counters
  215. * (see dns/stats.h).
  216. */
  217. isc_result_t
  218. dns_dispatch_getudp(dns_dispatchmgr_t *mgr, isc_socketmgr_t *sockmgr,
  219. isc_taskmgr_t *taskmgr, isc_sockaddr_t *localaddr,
  220. unsigned int buffersize,
  221. unsigned int maxbuffers, unsigned int maxrequests,
  222. unsigned int buckets, unsigned int increment,
  223. unsigned int attributes, unsigned int mask,
  224. dns_dispatch_t **dispp);
  225. /*%<
  226. * Attach to existing dns_dispatch_t if one is found with dns_dispatchmgr_find,
  227. * otherwise create a new UDP dispatch.
  228. *
  229. * Requires:
  230. *\li All pointer parameters be valid for their respective types.
  231. *
  232. *\li dispp != NULL && *disp == NULL
  233. *
  234. *\li 512 <= buffersize <= 64k
  235. *
  236. *\li maxbuffers > 0
  237. *
  238. *\li buckets < 2097169
  239. *
  240. *\li increment > buckets
  241. *
  242. *\li (attributes & DNS_DISPATCHATTR_TCP) == 0
  243. *
  244. * Returns:
  245. *\li ISC_R_SUCCESS -- success.
  246. *
  247. *\li Anything else -- failure.
  248. */
  249. isc_result_t
  250. dns_dispatch_createtcp(dns_dispatchmgr_t *mgr, isc_socket_t *sock,
  251. isc_taskmgr_t *taskmgr, unsigned int buffersize,
  252. unsigned int maxbuffers, unsigned int maxrequests,
  253. unsigned int buckets, unsigned int increment,
  254. unsigned int attributes, dns_dispatch_t **dispp);
  255. /*%<
  256. * Create a new dns_dispatch and attach it to the provided isc_socket_t.
  257. *
  258. * For all dispatches, "buffersize" is the maximum packet size we will
  259. * accept.
  260. *
  261. * "maxbuffers" and "maxrequests" control the number of buffers in the
  262. * overall system and the number of buffers which can be allocated to
  263. * requests.
  264. *
  265. * "buckets" is the number of buckets to use, and should be prime.
  266. *
  267. * "increment" is used in a collision avoidance function, and needs to be
  268. * a prime > buckets, and not 2.
  269. *
  270. * Requires:
  271. *
  272. *\li mgr is a valid dispatch manager.
  273. *
  274. *\li sock is a valid.
  275. *
  276. *\li task is a valid task that can be used internally to this dispatcher.
  277. *
  278. * \li 512 <= buffersize <= 64k
  279. *
  280. *\li maxbuffers > 0.
  281. *
  282. *\li maxrequests <= maxbuffers.
  283. *
  284. *\li buckets < 2097169 (the next prime after 65536 * 32)
  285. *
  286. *\li increment > buckets (and prime).
  287. *
  288. *\li attributes includes #DNS_DISPATCHATTR_TCP and does not include
  289. * #DNS_DISPATCHATTR_UDP.
  290. *
  291. * Returns:
  292. *\li ISC_R_SUCCESS -- success.
  293. *
  294. *\li Anything else -- failure.
  295. */
  296. void
  297. dns_dispatch_attach(dns_dispatch_t *disp, dns_dispatch_t **dispp);
  298. /*%<
  299. * Attach to a dispatch handle.
  300. *
  301. * Requires:
  302. *\li disp is valid.
  303. *
  304. *\li dispp != NULL && *dispp == NULL
  305. */
  306. void
  307. dns_dispatch_detach(dns_dispatch_t **dispp);
  308. /*%<
  309. * Detaches from the dispatch.
  310. *
  311. * Requires:
  312. *\li dispp != NULL and *dispp be a valid dispatch.
  313. */
  314. void
  315. dns_dispatch_starttcp(dns_dispatch_t *disp);
  316. /*%<
  317. * Start processing of a TCP dispatch once the socket connects.
  318. *
  319. * Requires:
  320. *\li 'disp' is valid.
  321. */
  322. isc_result_t
  323. dns_dispatch_addresponse2(dns_dispatch_t *disp, isc_sockaddr_t *dest,
  324. isc_task_t *task, isc_taskaction_t action, void *arg,
  325. isc_uint16_t *idp, dns_dispentry_t **resp,
  326. isc_socketmgr_t *sockmgr);
  327. isc_result_t
  328. dns_dispatch_addresponse(dns_dispatch_t *disp, isc_sockaddr_t *dest,
  329. isc_task_t *task, isc_taskaction_t action, void *arg,
  330. isc_uint16_t *idp, dns_dispentry_t **resp);
  331. /*%<
  332. * Add a response entry for this dispatch.
  333. *
  334. * "*idp" is filled in with the assigned message ID, and *resp is filled in
  335. * to contain the magic token used to request event flow stop.
  336. *
  337. * Arranges for the given task to get a callback for response packets. When
  338. * the event is delivered, it must be returned using dns_dispatch_freeevent()
  339. * or through dns_dispatch_removeresponse() for another to be delivered.
  340. *
  341. * Requires:
  342. *\li "idp" be non-NULL.
  343. *
  344. *\li "task" "action" and "arg" be set as appropriate.
  345. *
  346. *\li "dest" be non-NULL and valid.
  347. *
  348. *\li "resp" be non-NULL and *resp be NULL
  349. *
  350. *\li "sockmgr" be NULL or a valid socket manager. If 'disp' has
  351. * the DNS_DISPATCHATTR_EXCLUSIVE attribute, this must not be NULL,
  352. * which also means dns_dispatch_addresponse() cannot be used.
  353. *
  354. * Ensures:
  355. *
  356. *\li &lt;id, dest> is a unique tuple. That means incoming messages
  357. * are identifiable.
  358. *
  359. * Returns:
  360. *
  361. *\li ISC_R_SUCCESS -- all is well.
  362. *\li ISC_R_NOMEMORY -- memory could not be allocated.
  363. *\li ISC_R_NOMORE -- no more message ids can be allocated
  364. * for this destination.
  365. */
  366. void
  367. dns_dispatch_removeresponse(dns_dispentry_t **resp,
  368. dns_dispatchevent_t **sockevent);
  369. /*%<
  370. * Stops the flow of responses for the provided id and destination.
  371. * If "sockevent" is non-NULL, the dispatch event and associated buffer is
  372. * also returned to the system.
  373. *
  374. * Requires:
  375. *\li "resp" != NULL and "*resp" contain a value previously allocated
  376. * by dns_dispatch_addresponse();
  377. *
  378. *\li May only be called from within the task given as the 'task'
  379. * argument to dns_dispatch_addresponse() when allocating '*resp'.
  380. */
  381. isc_socket_t *
  382. dns_dispatch_getentrysocket(dns_dispentry_t *resp);
  383. isc_socket_t *
  384. dns_dispatch_getsocket(dns_dispatch_t *disp);
  385. /*%<
  386. * Return the socket associated with this dispatcher.
  387. *
  388. * Requires:
  389. *\li disp is valid.
  390. *
  391. * Returns:
  392. *\li The socket the dispatcher is using.
  393. */
  394. isc_result_t
  395. dns_dispatch_getlocaladdress(dns_dispatch_t *disp, isc_sockaddr_t *addrp);
  396. /*%<
  397. * Return the local address for this dispatch.
  398. * This currently only works for dispatches using UDP sockets.
  399. *
  400. * Requires:
  401. *\li disp is valid.
  402. *\li addrp to be non null.
  403. *
  404. * Returns:
  405. *\li ISC_R_SUCCESS
  406. *\li ISC_R_NOTIMPLEMENTED
  407. */
  408. void
  409. dns_dispatch_cancel(dns_dispatch_t *disp);
  410. /*%<
  411. * cancel outstanding clients
  412. *
  413. * Requires:
  414. *\li disp is valid.
  415. */
  416. unsigned int
  417. dns_dispatch_getattributes(dns_dispatch_t *disp);
  418. /*%<
  419. * Return the attributes (DNS_DISPATCHATTR_xxx) of this dispatch. Only the
  420. * non-changeable attributes are expected to be referenced by the caller.
  421. *
  422. * Requires:
  423. *\li disp is valid.
  424. */
  425. void
  426. dns_dispatch_changeattributes(dns_dispatch_t *disp,
  427. unsigned int attributes, unsigned int mask);
  428. /*%<
  429. * Set the bits described by "mask" to the corresponding values in
  430. * "attributes".
  431. *
  432. * That is:
  433. *
  434. * \code
  435. * new = (old & ~mask) | (attributes & mask)
  436. * \endcode
  437. *
  438. * This function has a side effect when #DNS_DISPATCHATTR_NOLISTEN changes.
  439. * When the flag becomes off, the dispatch will start receiving on the
  440. * corresponding socket. When the flag becomes on, receive events on the
  441. * corresponding socket will be canceled.
  442. *
  443. * Requires:
  444. *\li disp is valid.
  445. *
  446. *\li attributes are reasonable for the dispatch. That is, setting the UDP
  447. * attribute on a TCP socket isn't reasonable.
  448. */
  449. void
  450. dns_dispatch_importrecv(dns_dispatch_t *disp, isc_event_t *event);
  451. /*%<
  452. * Inform the dispatcher of a socket receive. This is used for sockets
  453. * shared between dispatchers and clients. If the dispatcher fails to copy
  454. * or send the event, nothing happens.
  455. *
  456. * Requires:
  457. *\li disp is valid, and the attribute DNS_DISPATCHATTR_NOLISTEN is set.
  458. * event != NULL
  459. */
  460. ISC_LANG_ENDDECLS
  461. #endif /* DNS_DISPATCH_H */