"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.11.23/lib/dns/include/dns/dnssec.h" (7 Sep 2020, 12114 Bytes) of package /linux/misc/dns/bind9/9.11.23/bind-9.11.23.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "dnssec.h" see the Fossies "Dox" file reference documentation.

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