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

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 252 lines · 58 code · 23 blank · 171 comment · 0 complexity · 0918f922ebe043e08a6b0c57deee8f88 MD5 · raw file

  1. /*
  2. * Copyright (C) 2004-2007, 2009-2011 Internet Systems Consortium, Inc. ("ISC")
  3. * 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. /* $Id: tkey.h,v 1.32 2011/01/08 23:47:01 tbox Exp $ */
  18. #ifndef DNS_TKEY_H
  19. #define DNS_TKEY_H 1
  20. /*! \file dns/tkey.h */
  21. #include <isc/lang.h>
  22. #include <dns/types.h>
  23. #include <dst/dst.h>
  24. #include <dst/gssapi.h>
  25. ISC_LANG_BEGINDECLS
  26. /* Key agreement modes */
  27. #define DNS_TKEYMODE_SERVERASSIGNED 1
  28. #define DNS_TKEYMODE_DIFFIEHELLMAN 2
  29. #define DNS_TKEYMODE_GSSAPI 3
  30. #define DNS_TKEYMODE_RESOLVERASSIGNED 4
  31. #define DNS_TKEYMODE_DELETE 5
  32. struct dns_tkeyctx {
  33. dst_key_t *dhkey;
  34. dns_name_t *domain;
  35. gss_cred_id_t gsscred;
  36. isc_mem_t *mctx;
  37. isc_entropy_t *ectx;
  38. char *gssapi_keytab;
  39. };
  40. isc_result_t
  41. dns_tkeyctx_create(isc_mem_t *mctx, isc_entropy_t *ectx,
  42. dns_tkeyctx_t **tctxp);
  43. /*%<
  44. * Create an empty TKEY context.
  45. *
  46. * Requires:
  47. *\li 'mctx' is not NULL
  48. *\li 'tctx' is not NULL
  49. *\li '*tctx' is NULL
  50. *
  51. * Returns
  52. *\li #ISC_R_SUCCESS
  53. *\li #ISC_R_NOMEMORY
  54. *\li return codes from dns_name_fromtext()
  55. */
  56. void
  57. dns_tkeyctx_destroy(dns_tkeyctx_t **tctxp);
  58. /*%<
  59. * Frees all data associated with the TKEY context
  60. *
  61. * Requires:
  62. *\li 'tctx' is not NULL
  63. *\li '*tctx' is not NULL
  64. */
  65. isc_result_t
  66. dns_tkey_processquery(dns_message_t *msg, dns_tkeyctx_t *tctx,
  67. dns_tsig_keyring_t *ring);
  68. /*%<
  69. * Processes a query containing a TKEY record, adding or deleting TSIG
  70. * keys if necessary, and modifies the message to contain the response.
  71. *
  72. * Requires:
  73. *\li 'msg' is a valid message
  74. *\li 'tctx' is a valid TKEY context
  75. *\li 'ring' is a valid TSIG keyring
  76. *
  77. * Returns
  78. *\li #ISC_R_SUCCESS msg was updated (the TKEY operation succeeded,
  79. * or msg now includes a TKEY with an error set)
  80. * DNS_R_FORMERR the packet was malformed (missing a TKEY
  81. * or KEY).
  82. *\li other An error occurred while processing the message
  83. */
  84. isc_result_t
  85. dns_tkey_builddhquery(dns_message_t *msg, dst_key_t *key, dns_name_t *name,
  86. dns_name_t *algorithm, isc_buffer_t *nonce,
  87. isc_uint32_t lifetime);
  88. /*%<
  89. * Builds a query containing a TKEY that will generate a shared
  90. * secret using a Diffie-Hellman key exchange. The shared key
  91. * will be of the specified algorithm (only DNS_TSIG_HMACMD5_NAME
  92. * is supported), and will be named either 'name',
  93. * 'name' + server chosen domain, or random data + server chosen domain
  94. * if 'name' == dns_rootname. If nonce is not NULL, it supplies
  95. * random data used in the shared secret computation. The key is
  96. * requested to have the specified lifetime (in seconds)
  97. *
  98. *
  99. * Requires:
  100. *\li 'msg' is a valid message
  101. *\li 'key' is a valid Diffie Hellman dst key
  102. *\li 'name' is a valid name
  103. *\li 'algorithm' is a valid name
  104. *
  105. * Returns:
  106. *\li #ISC_R_SUCCESS msg was successfully updated to include the
  107. * query to be sent
  108. *\li other an error occurred while building the message
  109. */
  110. isc_result_t
  111. dns_tkey_buildgssquery(dns_message_t *msg, dns_name_t *name, dns_name_t *gname,
  112. isc_buffer_t *intoken, isc_uint32_t lifetime,
  113. gss_ctx_id_t *context, isc_boolean_t win2k,
  114. isc_mem_t *mctx, char **err_message);
  115. /*%<
  116. * Builds a query containing a TKEY that will generate a GSSAPI context.
  117. * The key is requested to have the specified lifetime (in seconds).
  118. *
  119. * Requires:
  120. *\li 'msg' is a valid message
  121. *\li 'name' is a valid name
  122. *\li 'gname' is a valid name
  123. *\li 'context' is a pointer to a valid gss_ctx_id_t
  124. * (which may have the value GSS_C_NO_CONTEXT)
  125. *\li 'win2k' when true says to turn on some hacks to work
  126. * with the non-standard GSS-TSIG of Windows 2000
  127. *
  128. * Returns:
  129. *\li ISC_R_SUCCESS msg was successfully updated to include the
  130. * query to be sent
  131. *\li other an error occurred while building the message
  132. *\li *err_message optional error message
  133. */
  134. isc_result_t
  135. dns_tkey_builddeletequery(dns_message_t *msg, dns_tsigkey_t *key);
  136. /*%<
  137. * Builds a query containing a TKEY record that will delete the
  138. * specified shared secret from the server.
  139. *
  140. * Requires:
  141. *\li 'msg' is a valid message
  142. *\li 'key' is a valid TSIG key
  143. *
  144. * Returns:
  145. *\li #ISC_R_SUCCESS msg was successfully updated to include the
  146. * query to be sent
  147. *\li other an error occurred while building the message
  148. */
  149. isc_result_t
  150. dns_tkey_processdhresponse(dns_message_t *qmsg, dns_message_t *rmsg,
  151. dst_key_t *key, isc_buffer_t *nonce,
  152. dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring);
  153. /*%<
  154. * Processes a response to a query containing a TKEY that was
  155. * designed to generate a shared secret using a Diffie-Hellman key
  156. * exchange. If the query was successful, a new shared key
  157. * is created and added to the list of shared keys.
  158. *
  159. * Requires:
  160. *\li 'qmsg' is a valid message (the query)
  161. *\li 'rmsg' is a valid message (the response)
  162. *\li 'key' is a valid Diffie Hellman dst key
  163. *\li 'outkey' is either NULL or a pointer to NULL
  164. *\li 'ring' is a valid keyring or NULL
  165. *
  166. * Returns:
  167. *\li #ISC_R_SUCCESS the shared key was successfully added
  168. *\li #ISC_R_NOTFOUND an error occurred while looking for a
  169. * component of the query or response
  170. */
  171. isc_result_t
  172. dns_tkey_processgssresponse(dns_message_t *qmsg, dns_message_t *rmsg,
  173. dns_name_t *gname, gss_ctx_id_t *context,
  174. isc_buffer_t *outtoken, dns_tsigkey_t **outkey,
  175. dns_tsig_keyring_t *ring, char **err_message);
  176. /*%<
  177. * XXX
  178. */
  179. isc_result_t
  180. dns_tkey_processdeleteresponse(dns_message_t *qmsg, dns_message_t *rmsg,
  181. dns_tsig_keyring_t *ring);
  182. /*%<
  183. * Processes a response to a query containing a TKEY that was
  184. * designed to delete a shared secret. If the query was successful,
  185. * the shared key is deleted from the list of shared keys.
  186. *
  187. * Requires:
  188. *\li 'qmsg' is a valid message (the query)
  189. *\li 'rmsg' is a valid message (the response)
  190. *\li 'ring' is not NULL
  191. *
  192. * Returns:
  193. *\li #ISC_R_SUCCESS the shared key was successfully deleted
  194. *\li #ISC_R_NOTFOUND an error occurred while looking for a
  195. * component of the query or response
  196. */
  197. isc_result_t
  198. dns_tkey_gssnegotiate(dns_message_t *qmsg, dns_message_t *rmsg,
  199. dns_name_t *server, gss_ctx_id_t *context,
  200. dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring,
  201. isc_boolean_t win2k, char **err_message);
  202. /*
  203. * Client side negotiation of GSS-TSIG. Process the response
  204. * to a TKEY, and establish a TSIG key if negotiation was successful.
  205. * Build a response to the input TKEY message. Can take multiple
  206. * calls to successfully establish the context.
  207. *
  208. * Requires:
  209. * 'qmsg' is a valid message, the original TKEY request;
  210. * it will be filled with the new message to send
  211. * 'rmsg' is a valid message, the incoming TKEY message
  212. * 'server' is the server name
  213. * 'context' is the input context handle
  214. * 'outkey' receives the established key, if non-NULL;
  215. * if non-NULL must point to NULL
  216. * 'ring' is the keyring in which to establish the key,
  217. * or NULL
  218. * 'win2k' when true says to turn on some hacks to work
  219. * with the non-standard GSS-TSIG of Windows 2000
  220. *
  221. * Returns:
  222. * ISC_R_SUCCESS context was successfully established
  223. * ISC_R_NOTFOUND couldn't find a needed part of the query
  224. * or response
  225. * DNS_R_CONTINUE additional context negotiation is required;
  226. * send the new qmsg to the server
  227. */
  228. ISC_LANG_ENDDECLS
  229. #endif /* DNS_TKEY_H */