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

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 370 lines · 99 code · 45 blank · 226 comment · 0 complexity · 96c67a3618035c510ef323b59e1f031e MD5 · raw file

  1. /*
  2. * Portions Copyright (C) 2005-2007, 2009-2012 Internet Systems Consortium, Inc. ("ISC")
  3. * Portions Copyright (C) 1999-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. * Copyright (C) 2002 Stichting NLnet, Netherlands, stichting@nlnet.nl.
  19. *
  20. * Permission to use, copy, modify, and distribute this software for any
  21. * purpose with or without fee is hereby granted, provided that the
  22. * above copyright notice and this permission notice appear in all
  23. * copies.
  24. *
  25. * THE SOFTWARE IS PROVIDED "AS IS" AND STICHTING NLNET
  26. * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
  27. * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
  28. * STICHTING NLNET BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
  29. * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
  30. * OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  31. * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE
  32. * USE OR PERFORMANCE OF THIS SOFTWARE.
  33. *
  34. * The development of Dynamically Loadable Zones (DLZ) for Bind 9 was
  35. * conceived and contributed by Rob Butler.
  36. *
  37. * Permission to use, copy, modify, and distribute this software for any
  38. * purpose with or without fee is hereby granted, provided that the
  39. * above copyright notice and this permission notice appear in all
  40. * copies.
  41. *
  42. * THE SOFTWARE IS PROVIDED "AS IS" AND ROB BUTLER
  43. * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
  44. * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
  45. * ROB BUTLER BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
  46. * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
  47. * OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  48. * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE
  49. * USE OR PERFORMANCE OF THIS SOFTWARE.
  50. */
  51. /* $Id$ */
  52. /*! \file dns/sdlz.h */
  53. #ifndef SDLZ_H
  54. #define SDLZ_H 1
  55. #include <dns/dlz.h>
  56. ISC_LANG_BEGINDECLS
  57. #define DNS_SDLZFLAG_THREADSAFE 0x00000001U
  58. #define DNS_SDLZFLAG_RELATIVEOWNER 0x00000002U
  59. #define DNS_SDLZFLAG_RELATIVERDATA 0x00000004U
  60. /* A simple DLZ database. */
  61. typedef struct dns_sdlz_db dns_sdlz_db_t;
  62. /* A simple DLZ database lookup in progress. */
  63. typedef struct dns_sdlzlookup dns_sdlzlookup_t;
  64. /* A simple DLZ database traversal in progress. */
  65. typedef struct dns_sdlzallnodes dns_sdlzallnodes_t;
  66. typedef isc_result_t (*dns_sdlzallnodesfunc_t)(const char *zone,
  67. void *driverarg,
  68. void *dbdata,
  69. dns_sdlzallnodes_t *allnodes);
  70. /*%<
  71. * Method prototype. Drivers implementing the SDLZ interface may
  72. * supply an all nodes method. This method is called when the DNS
  73. * server is performing a zone transfer query, after the allow zone
  74. * transfer method has been called. This method is only called if the
  75. * allow zone transfer method returned ISC_R_SUCCESS. This method and
  76. * the allow zone transfer method are both required for zone transfers
  77. * to be supported. If the driver generates data dynamically (instead
  78. * of searching in a database for it) it should not implement this
  79. * function as a zone transfer would be meaningless. A SDLZ driver
  80. * does not have to implement an all nodes method.
  81. */
  82. typedef isc_result_t (*dns_sdlzallowzonexfr_t)(void *driverarg,
  83. void *dbdata, const char *name,
  84. const char *client);
  85. /*%<
  86. * Method prototype. Drivers implementing the SDLZ interface may
  87. * supply an allow zone transfer method. This method is called when
  88. * the DNS server is performing a zone transfer query, before the all
  89. * nodes method can be called. This method and the all node method
  90. * are both required for zone transfers to be supported. If the
  91. * driver generates data dynamically (instead of searching in a
  92. * database for it) it should not implement this function as a zone
  93. * transfer would be meaningless. A SDLZ driver does not have to
  94. * implement an allow zone transfer method.
  95. *
  96. * This method should return ISC_R_SUCCESS if the zone is supported by
  97. * the database and a zone transfer is allowed for the specified
  98. * client. If the zone is supported by the database, but zone
  99. * transfers are not allowed for the specified client this method
  100. * should return ISC_R_NOPERM.. Lastly the method should return
  101. * ISC_R_NOTFOUND if the zone is not supported by the database. If an
  102. * error occurs it should return a result code indicating the type of
  103. * error.
  104. */
  105. typedef isc_result_t (*dns_sdlzauthorityfunc_t)(const char *zone,
  106. void *driverarg, void *dbdata,
  107. dns_sdlzlookup_t *lookup);
  108. /*%<
  109. * Method prototype. Drivers implementing the SDLZ interface may
  110. * supply an authority method. This method is called when the DNS
  111. * server is performing a query, after both the find zone and lookup
  112. * methods have been called. This method is required if the lookup
  113. * function does not supply authority information for the dns
  114. * record. A SDLZ driver does not have to implement an authority
  115. * method.
  116. */
  117. typedef isc_result_t (*dns_sdlzcreate_t)(const char *dlzname,
  118. unsigned int argc, char *argv[],
  119. void *driverarg, void **dbdata);
  120. /*%<
  121. * Method prototype. Drivers implementing the SDLZ interface may
  122. * supply a create method. This method is called when the DNS server
  123. * is starting up and creating drivers for use later. A SDLZ driver
  124. * does not have to implement a create method.
  125. */
  126. typedef void (*dns_sdlzdestroy_t)(void *driverarg, void *dbdata);
  127. /*%<
  128. * Method prototype. Drivers implementing the SDLZ interface may
  129. * supply a destroy method. This method is called when the DNS server
  130. * is shutting down and no longer needs the driver. A SDLZ driver does
  131. * not have to implement a destroy method.
  132. */
  133. typedef isc_result_t
  134. (*dns_sdlzfindzone_t)(void *driverarg, void *dbdata, const char *name);
  135. /*%<
  136. * Method prototype. Drivers implementing the SDLZ interface MUST
  137. * supply a find zone method. This method is called when the DNS
  138. * server is performing a query to to determine if 'name' is a
  139. * supported dns zone. The find zone method will be called with the
  140. * longest possible name first, and continue to be called with
  141. * successively shorter domain names, until any of the following
  142. * occur:
  143. *
  144. * \li 1) the function returns (ISC_R_SUCCESS) indicating a zone name
  145. * match.
  146. *
  147. * \li 2) a problem occurs, and the functions returns anything other than
  148. * (ISC_R_NOTFOUND)
  149. *
  150. * \li 3) we run out of domain name labels. I.E. we have tried the
  151. * shortest domain name
  152. *
  153. * \li 4) the number of labels in the domain name is less than min_labels
  154. * for dns_dlzfindzone
  155. *
  156. * The driver's find zone method should return ISC_R_SUCCESS if the
  157. * zone is supported by the database. Otherwise it should return
  158. * ISC_R_NOTFOUND, if the zone is not supported. If an error occurs
  159. * it should return a result code indicating the type of error.
  160. */
  161. typedef isc_result_t
  162. (*dns_sdlzlookupfunc_t)(const char *zone, const char *name, void *driverarg,
  163. void *dbdata, dns_sdlzlookup_t *lookup);
  164. /*%<
  165. * Method prototype. Drivers implementing the SDLZ interface MUST
  166. * supply a lookup method. This method is called when the DNS server
  167. * is performing a query, after the find zone and before any other
  168. * methods have been called. This function returns record DNS record
  169. * information using the dns_sdlz_putrr and dns_sdlz_putsoa functions.
  170. * If this function supplies authority information for the DNS record
  171. * the authority method is not required. If it does not, the
  172. * authority function is required. A SDLZ driver must implement a
  173. * lookup method.
  174. */
  175. typedef isc_result_t (*dns_sdlznewversion_t)(const char *zone,
  176. void *driverarg, void *dbdata,
  177. void **versionp);
  178. /*%<
  179. * Method prototype. Drivers implementing the SDLZ interface may
  180. * supply a newversion method. This method is called to start a
  181. * write transaction on a zone and should only be implemented by
  182. * writeable backends.
  183. * When implemented, the driver should create a new transaction, and
  184. * fill *versionp with a pointer to the transaction state. The
  185. * closeversion function will be called to close the transaction.
  186. */
  187. typedef void (*dns_sdlzcloseversion_t)(const char *zone, isc_boolean_t commit,
  188. void *driverarg, void *dbdata,
  189. void **versionp);
  190. /*%<
  191. * Method prototype. Drivers implementing the SDLZ interface must
  192. * supply a closeversion method if they supply a newversion method.
  193. * When implemented, the driver should close the given transaction,
  194. * committing changes if 'commit' is ISC_TRUE. If 'commit' is not true
  195. * then all changes should be discarded and the database rolled back.
  196. * If the call is successful then *versionp should be set to NULL
  197. */
  198. typedef isc_result_t (*dns_sdlzconfigure_t)(dns_view_t *view, void *driverarg,
  199. void *dbdata);
  200. /*%<
  201. * Method prototype. Drivers implementing the SDLZ interface may
  202. * supply a configure method. When supplied, it will be called
  203. * immediately after the create method to give the driver a chance
  204. * to configure writeable zones
  205. */
  206. typedef isc_boolean_t (*dns_sdlzssumatch_t)(const char *signer,
  207. const char *name,
  208. const char *tcpaddr,
  209. const char *type,
  210. const char *key,
  211. isc_uint32_t keydatalen,
  212. unsigned char *keydata,
  213. void *driverarg,
  214. void *dbdata);
  215. /*%<
  216. * Method prototype. Drivers implementing the SDLZ interface may
  217. * supply a ssumatch method. If supplied, then ssumatch will be
  218. * called to authorize any zone updates. The driver should return
  219. * ISC_TRUE to allow the update, and ISC_FALSE to deny it. For a DLZ
  220. * controlled zone, this is the only access control on updates.
  221. */
  222. typedef isc_result_t (*dns_sdlzmodrdataset_t)(const char *name,
  223. const char *rdatastr,
  224. void *driverarg, void *dbdata,
  225. void *version);
  226. /*%<
  227. * Method prototype. Drivers implementing the SDLZ interface may
  228. * supply addrdataset and subtractrdataset methods. If supplied, then these
  229. * will be called when rdatasets are added/subtracted during
  230. * updates. The version parameter comes from a call to the sdlz
  231. * newversion() method from the driver. The rdataset parameter is a
  232. * linearise string representation of the rdataset change. The format
  233. * is the same as used by dig when displaying records. The fields are
  234. * tab delimited.
  235. */
  236. typedef isc_result_t (*dns_sdlzdelrdataset_t)(const char *name,
  237. const char *type,
  238. void *driverarg, void *dbdata,
  239. void *version);
  240. /*%<
  241. * Method prototype. Drivers implementing the SDLZ interface may
  242. * supply a delrdataset method. If supplied, then this
  243. * function will be called when rdatasets are deleted during
  244. * updates. The call should remove all rdatasets of the given type for
  245. * the specified name.
  246. */
  247. typedef struct dns_sdlzmethods {
  248. dns_sdlzcreate_t create;
  249. dns_sdlzdestroy_t destroy;
  250. dns_sdlzfindzone_t findzone;
  251. dns_sdlzlookupfunc_t lookup;
  252. dns_sdlzauthorityfunc_t authority;
  253. dns_sdlzallnodesfunc_t allnodes;
  254. dns_sdlzallowzonexfr_t allowzonexfr;
  255. dns_sdlznewversion_t newversion;
  256. dns_sdlzcloseversion_t closeversion;
  257. dns_sdlzconfigure_t configure;
  258. dns_sdlzssumatch_t ssumatch;
  259. dns_sdlzmodrdataset_t addrdataset;
  260. dns_sdlzmodrdataset_t subtractrdataset;
  261. dns_sdlzdelrdataset_t delrdataset;
  262. } dns_sdlzmethods_t;
  263. isc_result_t
  264. dns_sdlzregister(const char *drivername, const dns_sdlzmethods_t *methods,
  265. void *driverarg, unsigned int flags, isc_mem_t *mctx,
  266. dns_sdlzimplementation_t **sdlzimp);
  267. /*%<
  268. * Register a dynamically loadable zones (dlz) driver for the database
  269. * type 'drivername', implemented by the functions in '*methods'.
  270. *
  271. * sdlzimp must point to a NULL dns_sdlzimplementation_t pointer.
  272. * That is, sdlzimp != NULL && *sdlzimp == NULL. It will be assigned
  273. * a value that will later be used to identify the driver when
  274. * deregistering it.
  275. */
  276. void
  277. dns_sdlzunregister(dns_sdlzimplementation_t **sdlzimp);
  278. /*%<
  279. * Removes the sdlz driver from the list of registered sdlz drivers.
  280. * There must be no active sdlz drivers of this type when this
  281. * function is called.
  282. */
  283. typedef isc_result_t dns_sdlz_putnamedrr_t(dns_sdlzallnodes_t *allnodes,
  284. const char *name,
  285. const char *type,
  286. dns_ttl_t ttl,
  287. const char *data);
  288. dns_sdlz_putnamedrr_t dns_sdlz_putnamedrr;
  289. /*%<
  290. * Add a single resource record to the allnodes structure to be later
  291. * parsed into a zone transfer response.
  292. */
  293. typedef isc_result_t dns_sdlz_putrr_t(dns_sdlzlookup_t *lookup,
  294. const char *type,
  295. dns_ttl_t ttl,
  296. const char *data);
  297. dns_sdlz_putrr_t dns_sdlz_putrr;
  298. /*%<
  299. * Add a single resource record to the lookup structure to be later
  300. * parsed into a query response.
  301. */
  302. typedef isc_result_t dns_sdlz_putsoa_t(dns_sdlzlookup_t *lookup,
  303. const char *mname,
  304. const char *rname,
  305. isc_uint32_t serial);
  306. dns_sdlz_putsoa_t dns_sdlz_putsoa;
  307. /*%<
  308. * This function may optionally be called from the 'authority'
  309. * callback to simplify construction of the SOA record for 'zone'. It
  310. * will provide a SOA listing 'mname' as as the master server and
  311. * 'rname' as the responsible person mailbox. It is the
  312. * responsibility of the driver to increment the serial number between
  313. * responses if necessary. All other SOA fields will have reasonable
  314. * default values.
  315. */
  316. typedef isc_result_t dns_sdlz_setdb_t(dns_dlzdb_t *dlzdatabase,
  317. dns_rdataclass_t rdclass,
  318. dns_name_t *name,
  319. dns_db_t **dbp);
  320. dns_sdlz_setdb_t dns_sdlz_setdb;
  321. /*%<
  322. * Create the database pointers for a writeable SDLZ zone
  323. */
  324. ISC_LANG_ENDDECLS
  325. #endif /* SDLZ_H */