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