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

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 294 lines · 97 code · 31 blank · 166 comment · 1 complexity · 0070c8ebe05bb13617120b4e880f8c40 MD5 · raw file

  1. /*
  2. * Copyright (C) 2004-2007, 2009-2011 Internet Systems Consortium, Inc. ("ISC")
  3. * Copyright (C) 1999-2002 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: tsig.h,v 1.59 2011/01/11 23:47:13 tbox Exp $ */
  18. #ifndef DNS_TSIG_H
  19. #define DNS_TSIG_H 1
  20. /*! \file dns/tsig.h */
  21. #include <isc/lang.h>
  22. #include <isc/refcount.h>
  23. #include <isc/rwlock.h>
  24. #include <isc/stdio.h>
  25. #include <isc/stdtime.h>
  26. #include <dns/types.h>
  27. #include <dns/name.h>
  28. #include <dst/dst.h>
  29. /*
  30. * Algorithms.
  31. */
  32. LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacmd5_name;
  33. #define DNS_TSIG_HMACMD5_NAME dns_tsig_hmacmd5_name
  34. LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_gssapi_name;
  35. #define DNS_TSIG_GSSAPI_NAME dns_tsig_gssapi_name
  36. LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_gssapims_name;
  37. #define DNS_TSIG_GSSAPIMS_NAME dns_tsig_gssapims_name
  38. LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha1_name;
  39. #define DNS_TSIG_HMACSHA1_NAME dns_tsig_hmacsha1_name
  40. LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha224_name;
  41. #define DNS_TSIG_HMACSHA224_NAME dns_tsig_hmacsha224_name
  42. LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha256_name;
  43. #define DNS_TSIG_HMACSHA256_NAME dns_tsig_hmacsha256_name
  44. LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha384_name;
  45. #define DNS_TSIG_HMACSHA384_NAME dns_tsig_hmacsha384_name
  46. LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha512_name;
  47. #define DNS_TSIG_HMACSHA512_NAME dns_tsig_hmacsha512_name
  48. /*%
  49. * Default fudge value.
  50. */
  51. #define DNS_TSIG_FUDGE 300
  52. struct dns_tsig_keyring {
  53. dns_rbt_t *keys;
  54. unsigned int writecount;
  55. isc_rwlock_t lock;
  56. isc_mem_t *mctx;
  57. /*
  58. * LRU list of generated key along with a count of the keys on the
  59. * list and a maximum size.
  60. */
  61. unsigned int generated;
  62. unsigned int maxgenerated;
  63. ISC_LIST(dns_tsigkey_t) lru;
  64. unsigned int references;
  65. };
  66. struct dns_tsigkey {
  67. /* Unlocked */
  68. unsigned int magic; /*%< Magic number. */
  69. isc_mem_t *mctx;
  70. dst_key_t *key; /*%< Key */
  71. dns_name_t name; /*%< Key name */
  72. dns_name_t *algorithm; /*%< Algorithm name */
  73. dns_name_t *creator; /*%< name that created secret */
  74. isc_boolean_t generated; /*%< was this generated? */
  75. isc_stdtime_t inception; /*%< start of validity period */
  76. isc_stdtime_t expire; /*%< end of validity period */
  77. dns_tsig_keyring_t *ring; /*%< the enclosing keyring */
  78. isc_refcount_t refs; /*%< reference counter */
  79. ISC_LINK(dns_tsigkey_t) link;
  80. };
  81. #define dns_tsigkey_identity(tsigkey) \
  82. ((tsigkey) == NULL ? NULL : \
  83. (tsigkey)->generated ? ((tsigkey)->creator) : \
  84. (&((tsigkey)->name)))
  85. ISC_LANG_BEGINDECLS
  86. isc_result_t
  87. dns_tsigkey_create(dns_name_t *name, dns_name_t *algorithm,
  88. unsigned char *secret, int length, isc_boolean_t generated,
  89. dns_name_t *creator, isc_stdtime_t inception,
  90. isc_stdtime_t expire, isc_mem_t *mctx,
  91. dns_tsig_keyring_t *ring, dns_tsigkey_t **key);
  92. isc_result_t
  93. dns_tsigkey_createfromkey(dns_name_t *name, dns_name_t *algorithm,
  94. dst_key_t *dstkey, isc_boolean_t generated,
  95. dns_name_t *creator, isc_stdtime_t inception,
  96. isc_stdtime_t expire, isc_mem_t *mctx,
  97. dns_tsig_keyring_t *ring, dns_tsigkey_t **key);
  98. /*%<
  99. * Creates a tsig key structure and saves it in the keyring. If key is
  100. * not NULL, *key will contain a copy of the key. The keys validity
  101. * period is specified by (inception, expire), and will not expire if
  102. * inception == expire. If the key was generated, the creating identity,
  103. * if there is one, should be in the creator parameter. Specifying an
  104. * unimplemented algorithm will cause failure only if dstkey != NULL; this
  105. * allows a transient key with an invalid algorithm to exist long enough
  106. * to generate a BADKEY response.
  107. *
  108. * If dns_tsigkey_createfromkey is successful a new reference to 'dstkey'
  109. * will have been made.
  110. *
  111. * Requires:
  112. *\li 'name' is a valid dns_name_t
  113. *\li 'algorithm' is a valid dns_name_t
  114. *\li 'secret' is a valid pointer
  115. *\li 'length' is an integer >= 0
  116. *\li 'dstkey' is a valid dst key or NULL
  117. *\li 'creator' points to a valid dns_name_t or is NULL
  118. *\li 'mctx' is a valid memory context
  119. *\li 'ring' is a valid TSIG keyring or NULL
  120. *\li 'key' or '*key' must be NULL
  121. *
  122. * Returns:
  123. *\li #ISC_R_SUCCESS
  124. *\li #ISC_R_EXISTS - a key with this name already exists
  125. *\li #ISC_R_NOTIMPLEMENTED - algorithm is not implemented
  126. *\li #ISC_R_NOMEMORY
  127. */
  128. void
  129. dns_tsigkey_attach(dns_tsigkey_t *source, dns_tsigkey_t **targetp);
  130. /*%<
  131. * Attach '*targetp' to 'source'.
  132. *
  133. * Requires:
  134. *\li 'key' is a valid TSIG key
  135. *
  136. * Ensures:
  137. *\li *targetp is attached to source.
  138. */
  139. void
  140. dns_tsigkey_detach(dns_tsigkey_t **keyp);
  141. /*%<
  142. * Detaches from the tsig key structure pointed to by '*key'.
  143. *
  144. * Requires:
  145. *\li 'keyp' is not NULL and '*keyp' is a valid TSIG key
  146. *
  147. * Ensures:
  148. *\li 'keyp' points to NULL
  149. */
  150. void
  151. dns_tsigkey_setdeleted(dns_tsigkey_t *key);
  152. /*%<
  153. * Prevents this key from being used again. It will be deleted when
  154. * no references exist.
  155. *
  156. * Requires:
  157. *\li 'key' is a valid TSIG key on a keyring
  158. */
  159. isc_result_t
  160. dns_tsig_sign(dns_message_t *msg);
  161. /*%<
  162. * Generates a TSIG record for this message
  163. *
  164. * Requires:
  165. *\li 'msg' is a valid message
  166. *\li 'msg->tsigkey' is a valid TSIG key
  167. *\li 'msg->tsig' is NULL
  168. *
  169. * Returns:
  170. *\li #ISC_R_SUCCESS
  171. *\li #ISC_R_NOMEMORY
  172. *\li #ISC_R_NOSPACE
  173. *\li #DNS_R_EXPECTEDTSIG
  174. * - this is a response & msg->querytsig is NULL
  175. */
  176. isc_result_t
  177. dns_tsig_verify(isc_buffer_t *source, dns_message_t *msg,
  178. dns_tsig_keyring_t *ring1, dns_tsig_keyring_t *ring2);
  179. /*%<
  180. * Verifies the TSIG record in this message
  181. *
  182. * Requires:
  183. *\li 'source' is a valid buffer containing the unparsed message
  184. *\li 'msg' is a valid message
  185. *\li 'msg->tsigkey' is a valid TSIG key if this is a response
  186. *\li 'msg->tsig' is NULL
  187. *\li 'msg->querytsig' is not NULL if this is a response
  188. *\li 'ring1' and 'ring2' are each either a valid keyring or NULL
  189. *
  190. * Returns:
  191. *\li #ISC_R_SUCCESS
  192. *\li #ISC_R_NOMEMORY
  193. *\li #DNS_R_EXPECTEDTSIG - A TSIG was expected but not seen
  194. *\li #DNS_R_UNEXPECTEDTSIG - A TSIG was seen but not expected
  195. *\li #DNS_R_TSIGERRORSET - the TSIG verified but ->error was set
  196. * and this is a query
  197. *\li #DNS_R_CLOCKSKEW - the TSIG failed to verify because of
  198. * the time was out of the allowed range.
  199. *\li #DNS_R_TSIGVERIFYFAILURE - the TSIG failed to verify
  200. *\li #DNS_R_EXPECTEDRESPONSE - the message was set over TCP and
  201. * should have been a response,
  202. * but was not.
  203. */
  204. isc_result_t
  205. dns_tsigkey_find(dns_tsigkey_t **tsigkey, dns_name_t *name,
  206. dns_name_t *algorithm, dns_tsig_keyring_t *ring);
  207. /*%<
  208. * Returns the TSIG key corresponding to this name and (possibly)
  209. * algorithm. Also increments the key's reference counter.
  210. *
  211. * Requires:
  212. *\li 'tsigkey' is not NULL
  213. *\li '*tsigkey' is NULL
  214. *\li 'name' is a valid dns_name_t
  215. *\li 'algorithm' is a valid dns_name_t or NULL
  216. *\li 'ring' is a valid keyring
  217. *
  218. * Returns:
  219. *\li #ISC_R_SUCCESS
  220. *\li #ISC_R_NOTFOUND
  221. */
  222. isc_result_t
  223. dns_tsigkeyring_create(isc_mem_t *mctx, dns_tsig_keyring_t **ringp);
  224. /*%<
  225. * Create an empty TSIG key ring.
  226. *
  227. * Requires:
  228. *\li 'mctx' is not NULL
  229. *\li 'ringp' is not NULL, and '*ringp' is NULL
  230. *
  231. * Returns:
  232. *\li #ISC_R_SUCCESS
  233. *\li #ISC_R_NOMEMORY
  234. */
  235. isc_result_t
  236. dns_tsigkeyring_add(dns_tsig_keyring_t *ring, dns_name_t *name,
  237. dns_tsigkey_t *tkey);
  238. /*%<
  239. * Place a TSIG key onto a key ring.
  240. *
  241. * Requires:
  242. *\li 'ring', 'name' and 'tkey' are not NULL
  243. *
  244. * Returns:
  245. *\li #ISC_R_SUCCESS
  246. *\li Any other value indicates failure.
  247. */
  248. void
  249. dns_tsigkeyring_attach(dns_tsig_keyring_t *source, dns_tsig_keyring_t **target);
  250. void
  251. dns_tsigkeyring_detach(dns_tsig_keyring_t **ringp);
  252. isc_result_t
  253. dns_tsigkeyring_dumpanddetach(dns_tsig_keyring_t **ringp, FILE *fp);
  254. /*%<
  255. * Destroy a TSIG key ring.
  256. *
  257. * Requires:
  258. *\li 'ringp' is not NULL
  259. */
  260. void
  261. dns_keyring_restore(dns_tsig_keyring_t *ring, FILE *fp);
  262. ISC_LANG_ENDDECLS
  263. #endif /* DNS_TSIG_H */