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

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