lib/dns/include/dns/dnssec.h

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