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

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 338 lines · 92 code · 27 blank · 219 comment · 0 complexity · b97896ad8b93f603e10c19f768b3378d MD5 · raw file

  1. /*
  2. * Copyright (C) 2004-2007, 2009-2012 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$ */
  18. #ifndef DNS_DNSSEC_H
  19. #define DNS_DNSSEC_H 1
  20. /*! \file dns/dnssec.h */
  21. #include <isc/lang.h>
  22. #include <isc/stdtime.h>
  23. #include <dns/diff.h>
  24. #include <dns/types.h>
  25. #include <dst/dst.h>
  26. ISC_LANG_BEGINDECLS
  27. /*%< Maximum number of keys supported in a zone. */
  28. #define DNS_MAXZONEKEYS 32
  29. /*
  30. * Indicates how the signer found this key: in the key repository, at the
  31. * zone apex, or specified by the user.
  32. */
  33. typedef enum {
  34. dns_keysource_unknown,
  35. dns_keysource_repository,
  36. dns_keysource_zoneapex,
  37. dns_keysource_user
  38. } dns_keysource_t;
  39. /*
  40. * A DNSSEC key and hints about its intended use gleaned from metadata
  41. */
  42. struct dns_dnsseckey {
  43. dst_key_t *key;
  44. isc_boolean_t hint_publish; /*% metadata says to publish */
  45. isc_boolean_t force_publish; /*% publish regardless of metadata */
  46. isc_boolean_t hint_sign; /*% metadata says to sign with this key */
  47. isc_boolean_t force_sign; /*% sign with key regardless of metadata */
  48. isc_boolean_t hint_remove; /*% metadata says *don't* publish */
  49. isc_boolean_t is_active; /*% key is already active */
  50. isc_boolean_t first_sign; /*% key is newly becoming active */
  51. unsigned int prepublish; /*% how long until active? */
  52. dns_keysource_t source; /*% how the key was found */
  53. isc_boolean_t ksk; /*% this is a key-signing key */
  54. isc_boolean_t legacy; /*% this is old-style key with no
  55. metadata (possibly generated by
  56. an older version of BIND9) and
  57. should be ignored when searching
  58. for keys to import into the zone */
  59. unsigned int index; /*% position in list */
  60. ISC_LINK(dns_dnsseckey_t) link;
  61. };
  62. isc_result_t
  63. dns_dnssec_keyfromrdata(dns_name_t *name, dns_rdata_t *rdata, isc_mem_t *mctx,
  64. dst_key_t **key);
  65. /*%<
  66. * Creates a DST key from a DNS record. Basically a wrapper around
  67. * dst_key_fromdns().
  68. *
  69. * Requires:
  70. *\li 'name' is not NULL
  71. *\li 'rdata' is not NULL
  72. *\li 'mctx' is not NULL
  73. *\li 'key' is not NULL
  74. *\li '*key' is NULL
  75. *
  76. * Returns:
  77. *\li #ISC_R_SUCCESS
  78. *\li #ISC_R_NOMEMORY
  79. *\li DST_R_INVALIDPUBLICKEY
  80. *\li various errors from dns_name_totext
  81. */
  82. isc_result_t
  83. dns_dnssec_sign(dns_name_t *name, dns_rdataset_t *set, dst_key_t *key,
  84. isc_stdtime_t *inception, isc_stdtime_t *expire,
  85. isc_mem_t *mctx, isc_buffer_t *buffer, dns_rdata_t *sigrdata);
  86. /*%<
  87. * Generates a SIG record covering this rdataset. This has no effect
  88. * on existing SIG records.
  89. *
  90. * Requires:
  91. *\li 'name' (the owner name of the record) is a valid name
  92. *\li 'set' is a valid rdataset
  93. *\li 'key' is a valid key
  94. *\li 'inception' is not NULL
  95. *\li 'expire' is not NULL
  96. *\li 'mctx' is not NULL
  97. *\li 'buffer' is not NULL
  98. *\li 'sigrdata' is not NULL
  99. *
  100. * Returns:
  101. *\li #ISC_R_SUCCESS
  102. *\li #ISC_R_NOMEMORY
  103. *\li #ISC_R_NOSPACE
  104. *\li #DNS_R_INVALIDTIME - the expiration is before the inception
  105. *\li #DNS_R_KEYUNAUTHORIZED - the key cannot sign this data (either
  106. * it is not a zone key or its flags prevent
  107. * authentication)
  108. *\li DST_R_*
  109. */
  110. isc_result_t
  111. dns_dnssec_verify(dns_name_t *name, dns_rdataset_t *set, dst_key_t *key,
  112. isc_boolean_t ignoretime, isc_mem_t *mctx,
  113. dns_rdata_t *sigrdata);
  114. isc_result_t
  115. dns_dnssec_verify2(dns_name_t *name, dns_rdataset_t *set, dst_key_t *key,
  116. isc_boolean_t ignoretime, isc_mem_t *mctx,
  117. dns_rdata_t *sigrdata, dns_name_t *wild);
  118. /*%<
  119. * Verifies the SIG record covering this rdataset signed by a specific
  120. * key. This does not determine if the key's owner is authorized to
  121. * sign this record, as this requires a resolver or database.
  122. * If 'ignoretime' is ISC_TRUE, temporal validity will not be checked.
  123. *
  124. * Requires:
  125. *\li 'name' (the owner name of the record) is a valid name
  126. *\li 'set' is a valid rdataset
  127. *\li 'key' is a valid key
  128. *\li 'mctx' is not NULL
  129. *\li 'sigrdata' is a valid rdata containing a SIG record
  130. *\li 'wild' if non-NULL then is a valid and has a buffer.
  131. *
  132. * Returns:
  133. *\li #ISC_R_SUCCESS
  134. *\li #ISC_R_NOMEMORY
  135. *\li #DNS_R_FROMWILDCARD - the signature is valid and is from
  136. * a wildcard expansion. dns_dnssec_verify2() only.
  137. * 'wild' contains the name of the wildcard if non-NULL.
  138. *\li #DNS_R_SIGINVALID - the signature fails to verify
  139. *\li #DNS_R_SIGEXPIRED - the signature has expired
  140. *\li #DNS_R_SIGFUTURE - the signature's validity period has not begun
  141. *\li #DNS_R_KEYUNAUTHORIZED - the key cannot sign this data (either
  142. * it is not a zone key or its flags prevent
  143. * authentication)
  144. *\li DST_R_*
  145. */
  146. /*@{*/
  147. isc_result_t
  148. dns_dnssec_findzonekeys(dns_db_t *db, dns_dbversion_t *ver, dns_dbnode_t *node,
  149. dns_name_t *name, isc_mem_t *mctx,
  150. unsigned int maxkeys, dst_key_t **keys,
  151. unsigned int *nkeys);
  152. isc_result_t
  153. dns_dnssec_findzonekeys2(dns_db_t *db, dns_dbversion_t *ver,
  154. dns_dbnode_t *node, dns_name_t *name,
  155. const char *directory, isc_mem_t *mctx,
  156. unsigned int maxkeys, dst_key_t **keys,
  157. unsigned int *nkeys);
  158. /*%<
  159. * Finds a set of zone keys.
  160. * XXX temporary - this should be handled in dns_zone_t.
  161. */
  162. /*@}*/
  163. isc_result_t
  164. dns_dnssec_signmessage(dns_message_t *msg, dst_key_t *key);
  165. /*%<
  166. * Signs a message with a SIG(0) record. This is implicitly called by
  167. * dns_message_renderend() if msg->sig0key is not NULL.
  168. *
  169. * Requires:
  170. *\li 'msg' is a valid message
  171. *\li 'key' is a valid key that can be used for signing
  172. *
  173. * Returns:
  174. *\li #ISC_R_SUCCESS
  175. *\li #ISC_R_NOMEMORY
  176. *\li DST_R_*
  177. */
  178. isc_result_t
  179. dns_dnssec_verifymessage(isc_buffer_t *source, dns_message_t *msg,
  180. dst_key_t *key);
  181. /*%<
  182. * Verifies a message signed by a SIG(0) record. This is not
  183. * called implicitly by dns_message_parse(). If dns_message_signer()
  184. * is called before dns_dnssec_verifymessage(), it will return
  185. * #DNS_R_NOTVERIFIEDYET. dns_dnssec_verifymessage() will set
  186. * the verified_sig0 flag in msg if the verify succeeds, and
  187. * the sig0status field otherwise.
  188. *
  189. * Requires:
  190. *\li 'source' is a valid buffer containing the unparsed message
  191. *\li 'msg' is a valid message
  192. *\li 'key' is a valid key
  193. *
  194. * Returns:
  195. *\li #ISC_R_SUCCESS
  196. *\li #ISC_R_NOMEMORY
  197. *\li #ISC_R_NOTFOUND - no SIG(0) was found
  198. *\li #DNS_R_SIGINVALID - the SIG record is not well-formed or
  199. * was not generated by the key.
  200. *\li DST_R_*
  201. */
  202. isc_boolean_t
  203. dns_dnssec_selfsigns(dns_rdata_t *rdata, dns_name_t *name,
  204. dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset,
  205. isc_boolean_t ignoretime, isc_mem_t *mctx);
  206. isc_boolean_t
  207. dns_dnssec_signs(dns_rdata_t *rdata, dns_name_t *name,
  208. dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset,
  209. isc_boolean_t ignoretime, isc_mem_t *mctx);
  210. /*%<
  211. * Verify that 'rdataset' is validly signed in 'sigrdataset' by
  212. * the key in 'rdata'.
  213. *
  214. * dns_dnssec_selfsigns() requires that rdataset be a DNSKEY or KEY
  215. * rrset. dns_dnssec_signs() works on any rrset.
  216. */
  217. isc_result_t
  218. dns_dnsseckey_create(isc_mem_t *mctx, dst_key_t **dstkey,
  219. dns_dnsseckey_t **dkp);
  220. /*%<
  221. * Create and initialize a dns_dnsseckey_t structure.
  222. *
  223. * Requires:
  224. *\li 'dkp' is not NULL and '*dkp' is NULL.
  225. *
  226. * Returns:
  227. *\li #ISC_R_SUCCESS
  228. *\li #ISC_R_NOMEMORY
  229. */
  230. void
  231. dns_dnsseckey_destroy(isc_mem_t *mctx, dns_dnsseckey_t **dkp);
  232. /*%<
  233. * Reclaim a dns_dnsseckey_t structure.
  234. *
  235. * Requires:
  236. *\li 'dkp' is not NULL and '*dkp' is not NULL.
  237. *
  238. * Ensures:
  239. *\li '*dkp' is NULL.
  240. */
  241. isc_result_t
  242. dns_dnssec_findmatchingkeys(dns_name_t *origin, const char *directory,
  243. isc_mem_t *mctx, dns_dnsseckeylist_t *keylist);
  244. /*%<
  245. * Search 'directory' for K* key files matching the name in 'origin'.
  246. * Append all such keys, along with use hints gleaned from their
  247. * metadata, onto 'keylist'.
  248. *
  249. * Requires:
  250. *\li 'keylist' is not NULL
  251. *
  252. * Returns:
  253. *\li #ISC_R_SUCCESS
  254. *\li #ISC_R_NOTFOUND
  255. *\li #ISC_R_NOMEMORY
  256. *\li any error returned by dns_name_totext(), isc_dir_open(), or
  257. * dst_key_fromnamedfile()
  258. *
  259. * Ensures:
  260. *\li On error, keylist is unchanged
  261. */
  262. isc_result_t
  263. dns_dnssec_keylistfromrdataset(dns_name_t *origin,
  264. const char *directory, isc_mem_t *mctx,
  265. dns_rdataset_t *keyset, dns_rdataset_t *keysigs,
  266. dns_rdataset_t *soasigs, isc_boolean_t savekeys,
  267. isc_boolean_t public,
  268. dns_dnsseckeylist_t *keylist);
  269. /*%<
  270. * Append the contents of a DNSKEY rdataset 'keyset' to 'keylist'.
  271. * Omit duplicates. If 'public' is ISC_FALSE, search 'directory' for
  272. * matching key files, and load the private keys that go with
  273. * the public ones. If 'savekeys' is ISC_TRUE, mark the keys so
  274. * they will not be deleted or inactivated regardless of metadata.
  275. *
  276. * 'keysigs' and 'soasigs', if not NULL and associated, contain the
  277. * RRSIGS for the DNSKEY and SOA records respectively and are used to mark
  278. * whether a key is already active in the zone.
  279. */
  280. isc_result_t
  281. dns_dnssec_updatekeys(dns_dnsseckeylist_t *keys, dns_dnsseckeylist_t *newkeys,
  282. dns_dnsseckeylist_t *removed, dns_name_t *origin,
  283. dns_ttl_t ttl, dns_diff_t *diff, isc_boolean_t allzsk,
  284. isc_mem_t *mctx, void (*report)(const char *, ...));
  285. /*%<
  286. * Update the list of keys in 'keys' with new key information in 'newkeys'.
  287. *
  288. * For each key in 'newkeys', see if it has a match in 'keys'.
  289. * - If not, and if the metadata says the key should be published:
  290. * add it to 'keys', and place a dns_difftuple into 'diff' so
  291. * the key can be added to the DNSKEY set. If the metadata says it
  292. * should be active, set the first_sign flag.
  293. * - If so, and if the metadata says it should be removed:
  294. * remove it from 'keys', and place a dns_difftuple into 'diff' so
  295. * the key can be removed from the DNSKEY set. if 'removed' is non-NULL,
  296. * copy the key into that list; otherwise destroy it.
  297. * - Otherwise, make sure keys has current metadata.
  298. *
  299. * If 'allzsk' is true, we are allowing KSK-flagged keys to be used as
  300. * ZSKs.
  301. *
  302. * 'ttl' is the TTL of the DNSKEY RRset; if it is longer than the
  303. * time until a new key will be activated, then we have to delay the
  304. * key's activation.
  305. *
  306. * 'report' points to a function for reporting status.
  307. *
  308. * On completion, any remaining keys in 'newkeys' are freed.
  309. */
  310. ISC_LANG_ENDDECLS
  311. #endif /* DNS_DNSSEC_H */