"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.17.5/lib/dns/include/dns/dnssec.h" (4 Sep 2020, 11942 Bytes) of package /linux/misc/dns/bind9/9.17.5/bind-9.17.5.tar.xz:


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