"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.17.5/lib/dns/include/dns/kasp.h" (4 Sep 2020, 10409 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 "kasp.h" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 9.17.4_vs_9.17.5.

    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_KASP_H
   13 #define DNS_KASP_H 1
   14 
   15 /*****
   16 ***** Module Info
   17 *****/
   18 
   19 /*! \file dns/kasp.h
   20  * \brief
   21  * DNSSEC Key and Signing Policy (KASP)
   22  *
   23  * A "kasp" is a DNSSEC policy, that determines how a zone should be
   24  * signed and maintained.
   25  */
   26 
   27 #include <isc/lang.h>
   28 #include <isc/magic.h>
   29 #include <isc/mutex.h>
   30 #include <isc/refcount.h>
   31 
   32 #include <dns/types.h>
   33 
   34 ISC_LANG_BEGINDECLS
   35 
   36 /* Stores a KASP key */
   37 struct dns_kasp_key {
   38     isc_mem_t *mctx;
   39 
   40     /* Locked by themselves. */
   41     isc_refcount_t references;
   42 
   43     /* Under owner's locking control. */
   44     ISC_LINK(struct dns_kasp_key) link;
   45 
   46     /* Configuration */
   47     uint32_t lifetime;
   48     uint8_t  algorithm;
   49     int  length;
   50     uint8_t  role;
   51 };
   52 
   53 /* Stores a DNSSEC policy */
   54 struct dns_kasp {
   55     unsigned int magic;
   56     isc_mem_t *  mctx;
   57     char *       name;
   58 
   59     /* Internals. */
   60     isc_mutex_t lock;
   61     bool        frozen;
   62 
   63     /* Locked by themselves. */
   64     isc_refcount_t references;
   65 
   66     /* Under owner's locking control. */
   67     ISC_LINK(struct dns_kasp) link;
   68 
   69     /* Configuration: signatures */
   70     uint32_t signatures_refresh;
   71     uint32_t signatures_validity;
   72     uint32_t signatures_validity_dnskey;
   73 
   74     /* Configuration: Keys */
   75     dns_kasp_keylist_t keys;
   76     dns_ttl_t      dnskey_ttl;
   77 
   78     /* Configuration: Timings */
   79     uint32_t publish_safety;
   80     uint32_t retire_safety;
   81 
   82     /* Zone settings */
   83     dns_ttl_t zone_max_ttl;
   84     uint32_t  zone_propagation_delay;
   85 
   86     /* Parent settings */
   87     dns_ttl_t parent_ds_ttl;
   88     uint32_t  parent_propagation_delay;
   89 
   90     /* TODO: The rest of the KASP configuration */
   91 };
   92 
   93 #define DNS_KASP_MAGIC       ISC_MAGIC('K', 'A', 'S', 'P')
   94 #define DNS_KASP_VALID(kasp) ISC_MAGIC_VALID(kasp, DNS_KASP_MAGIC)
   95 
   96 /* Defaults */
   97 #define DNS_KASP_SIG_REFRESH         (86400 * 5)
   98 #define DNS_KASP_SIG_VALIDITY        (86400 * 14)
   99 #define DNS_KASP_SIG_VALIDITY_DNSKEY (86400 * 14)
  100 #define DNS_KASP_KEY_TTL         (3600)
  101 #define DNS_KASP_DS_TTL          (86400)
  102 #define DNS_KASP_PUBLISH_SAFETY      (3600)
  103 #define DNS_KASP_RETIRE_SAFETY       (3600)
  104 #define DNS_KASP_ZONE_MAXTTL         (86400)
  105 #define DNS_KASP_ZONE_PROPDELAY      (300)
  106 #define DNS_KASP_PARENT_PROPDELAY    (3600)
  107 
  108 /* Key roles */
  109 #define DNS_KASP_KEY_ROLE_KSK 0x01
  110 #define DNS_KASP_KEY_ROLE_ZSK 0x02
  111 
  112 isc_result_t
  113 dns_kasp_create(isc_mem_t *mctx, const char *name, dns_kasp_t **kaspp);
  114 /*%<
  115  * Create a KASP.
  116  *
  117  * Requires:
  118  *
  119  *\li  'mctx' is a valid memory context.
  120  *
  121  *\li  'name' is a valid C string.
  122  *
  123  *\li  kaspp != NULL && *kaspp == NULL
  124  *
  125  * Returns:
  126  *
  127  *\li  #ISC_R_SUCCESS
  128  *\li  #ISC_R_NOMEMORY
  129  *
  130  *\li  Other errors are possible.
  131  */
  132 
  133 void
  134 dns_kasp_attach(dns_kasp_t *source, dns_kasp_t **targetp);
  135 /*%<
  136  * Attach '*targetp' to 'source'.
  137  *
  138  * Requires:
  139  *
  140  *\li   'source' is a valid, frozen kasp.
  141  *
  142  *\li   'targetp' points to a NULL dns_kasp_t *.
  143  *
  144  * Ensures:
  145  *
  146  *\li   *targetp is attached to source.
  147  *
  148  *\li   While *targetp is attached, the kasp will not shut down.
  149  */
  150 
  151 void
  152 dns_kasp_detach(dns_kasp_t **kaspp);
  153 /*%<
  154  * Detach KASP.
  155  *
  156  * Requires:
  157  *
  158  *\li   'kaspp' points to a valid dns_kasp_t *
  159  *
  160  * Ensures:
  161  *
  162  *\li   *kaspp is NULL.
  163  */
  164 
  165 void
  166 dns_kasp_freeze(dns_kasp_t *kasp);
  167 /*%<
  168  * Freeze kasp.  No changes can be made to kasp configuration while frozen.
  169  *
  170  * Requires:
  171  *
  172  *\li   'kasp' is a valid, unfrozen kasp.
  173  *
  174  * Ensures:
  175  *
  176  *\li   'kasp' is frozen.
  177  */
  178 
  179 void
  180 dns_kasp_thaw(dns_kasp_t *kasp);
  181 /*%<
  182  * Thaw kasp.
  183  *
  184  * Requires:
  185  *
  186  *\li   'kasp' is a valid, frozen kasp.
  187  *
  188  * Ensures:
  189  *
  190  *\li   'kasp' is no longer frozen.
  191  */
  192 
  193 const char *
  194 dns_kasp_getname(dns_kasp_t *kasp);
  195 /*%<
  196  * Get kasp name.
  197  *
  198  * Requires:
  199  *
  200  *\li   'kasp' is a valid kasp.
  201  *
  202  * Returns:
  203  *
  204  *\li   name of 'kasp'.
  205  */
  206 
  207 uint32_t
  208 dns_kasp_signdelay(dns_kasp_t *kasp);
  209 /*%<
  210  * Get the delay that is needed to ensure that all existing RRsets have been
  211  * re-signed with a successor key.  This is the signature validity minus the
  212  * signature refresh time (that indicates how far before signature expiry an
  213  * RRSIG should be refreshed).
  214  *
  215  * Requires:
  216  *
  217  *\li   'kasp' is a valid, frozen kasp.
  218  *
  219  * Returns:
  220  *
  221  *\li   signature refresh interval.
  222  */
  223 
  224 uint32_t
  225 dns_kasp_sigrefresh(dns_kasp_t *kasp);
  226 /*%<
  227  * Get signature refresh interval.
  228  *
  229  * Requires:
  230  *
  231  *\li   'kasp' is a valid, frozen kasp.
  232  *
  233  * Returns:
  234  *
  235  *\li   signature refresh interval.
  236  */
  237 
  238 void
  239 dns_kasp_setsigrefresh(dns_kasp_t *kasp, uint32_t value);
  240 /*%<
  241  * Set signature refresh interval.
  242  *
  243  * Requires:
  244  *
  245  *\li   'kasp' is a valid, thawed kasp.
  246  */
  247 
  248 uint32_t
  249 dns_kasp_sigvalidity(dns_kasp_t *kasp);
  250 uint32_t
  251 dns_kasp_sigvalidity_dnskey(dns_kasp_t *kasp);
  252 /*%<
  253  * Get signature validity.
  254  *
  255  * Requires:
  256  *
  257  *\li   'kasp' is a valid, frozen kasp.
  258  *
  259  * Returns:
  260  *
  261  *\li   signature validity.
  262  */
  263 
  264 void
  265 dns_kasp_setsigvalidity(dns_kasp_t *kasp, uint32_t value);
  266 void
  267 dns_kasp_setsigvalidity_dnskey(dns_kasp_t *kasp, uint32_t value);
  268 /*%<
  269  * Set signature validity.
  270  *
  271  * Requires:
  272  *
  273  *\li   'kasp' is a valid, thawed kasp.
  274  */
  275 
  276 dns_ttl_t
  277 dns_kasp_dnskeyttl(dns_kasp_t *kasp);
  278 /*%<
  279  * Get DNSKEY TTL.
  280  *
  281  * Requires:
  282  *
  283  *\li   'kasp' is a valid, frozen kasp.
  284  *
  285  * Returns:
  286  *
  287  *\li   DNSKEY TTL.
  288  */
  289 
  290 void
  291 dns_kasp_setdnskeyttl(dns_kasp_t *kasp, dns_ttl_t ttl);
  292 /*%<
  293  * Set DNSKEY TTL.
  294  *
  295  * Requires:
  296  *
  297  *\li   'kasp' is a valid, thawed kasp.
  298  */
  299 
  300 uint32_t
  301 dns_kasp_publishsafety(dns_kasp_t *kasp);
  302 /*%<
  303  * Get publish safety interval.
  304  *
  305  * Requires:
  306  *
  307  *\li   'kasp' is a valid, frozen kasp.
  308  *
  309  * Returns:
  310  *
  311  *\li   Publish safety interval.
  312  */
  313 
  314 void
  315 dns_kasp_setpublishsafety(dns_kasp_t *kasp, uint32_t value);
  316 /*%<
  317  * Set publish safety interval.
  318  *
  319  * Requires:
  320  *
  321  *\li   'kasp' is a valid, thawed kasp.
  322  */
  323 
  324 uint32_t
  325 dns_kasp_retiresafety(dns_kasp_t *kasp);
  326 /*%<
  327  * Get retire safety interval.
  328  *
  329  * Requires:
  330  *
  331  *\li   'kasp' is a valid, frozen kasp.
  332  *
  333  * Returns:
  334  *
  335  *\li   Retire safety interval.
  336  */
  337 
  338 void
  339 dns_kasp_setretiresafety(dns_kasp_t *kasp, uint32_t value);
  340 /*%<
  341  * Set retire safety interval.
  342  *
  343  * Requires:
  344  *
  345  *\li   'kasp' is a valid, thawed kasp.
  346  */
  347 
  348 dns_ttl_t
  349 dns_kasp_zonemaxttl(dns_kasp_t *kasp);
  350 /*%<
  351  * Get maximum zone TTL.
  352  *
  353  * Requires:
  354  *
  355  *\li   'kasp' is a valid, frozen kasp.
  356  *
  357  * Returns:
  358  *
  359  *\li   Maximum zone TTL.
  360  */
  361 
  362 void
  363 dns_kasp_setzonemaxttl(dns_kasp_t *kasp, dns_ttl_t ttl);
  364 /*%<
  365  * Set maximum zone TTL.
  366  *
  367  * Requires:
  368  *
  369  *\li   'kasp' is a valid, thawed kasp.
  370  */
  371 
  372 uint32_t
  373 dns_kasp_zonepropagationdelay(dns_kasp_t *kasp);
  374 /*%<
  375  * Get zone propagation delay.
  376  *
  377  * Requires:
  378  *
  379  *\li   'kasp' is a valid, frozen kasp.
  380  *
  381  * Returns:
  382  *
  383  *\li   Zone propagation delay.
  384  */
  385 
  386 void
  387 dns_kasp_setzonepropagationdelay(dns_kasp_t *kasp, uint32_t value);
  388 /*%<
  389  * Set zone propagation delay.
  390  *
  391  * Requires:
  392  *
  393  *\li   'kasp' is a valid, thawed kasp.
  394  */
  395 
  396 dns_ttl_t
  397 dns_kasp_dsttl(dns_kasp_t *kasp);
  398 /*%<
  399  * Get DS TTL (should match that of the parent DS record).
  400  *
  401  * Requires:
  402  *
  403  *\li   'kasp' is a valid, frozen kasp.
  404  *
  405  * Returns:
  406  *
  407  *\li   Expected parent DS TTL.
  408  */
  409 
  410 void
  411 dns_kasp_setdsttl(dns_kasp_t *kasp, dns_ttl_t ttl);
  412 /*%<
  413  * Set DS TTL.
  414  *
  415  * Requires:
  416  *
  417  *\li   'kasp' is a valid, thawed kasp.
  418  */
  419 
  420 uint32_t
  421 dns_kasp_parentpropagationdelay(dns_kasp_t *kasp);
  422 /*%<
  423  * Get parent zone propagation delay.
  424  *
  425  * Requires:
  426  *
  427  *\li   'kasp' is a valid, frozen kasp.
  428  *
  429  * Returns:
  430  *
  431  *\li   Parent zone propagation delay.
  432  */
  433 
  434 void
  435 dns_kasp_setparentpropagationdelay(dns_kasp_t *kasp, uint32_t value);
  436 /*%<
  437  * Set parent propagation delay.
  438  *
  439  * Requires:
  440  *
  441  *\li   'kasp' is a valid, thawed kasp.
  442  */
  443 
  444 isc_result_t
  445 dns_kasplist_find(dns_kasplist_t *list, const char *name, dns_kasp_t **kaspp);
  446 /*%<
  447  * Search for a kasp with name 'name' in 'list'.
  448  * If found, '*kaspp' is (strongly) attached to it.
  449  *
  450  * Requires:
  451  *
  452  *\li   'kaspp' points to a NULL dns_kasp_t *.
  453  *
  454  * Returns:
  455  *
  456  *\li   #ISC_R_SUCCESS          A matching kasp was found.
  457  *\li   #ISC_R_NOTFOUND         No matching kasp was found.
  458  */
  459 
  460 dns_kasp_keylist_t
  461 dns_kasp_keys(dns_kasp_t *kasp);
  462 /*%<
  463  * Get the list of kasp keys.
  464  *
  465  * Requires:
  466  *
  467  *\li   'kasp' is a valid, frozen kasp.
  468  *
  469  * Returns:
  470  *
  471  *\li  #ISC_R_SUCCESS
  472  *\li  #ISC_R_NOMEMORY
  473  *
  474  *\li  Other errors are possible.
  475  */
  476 
  477 bool
  478 dns_kasp_keylist_empty(dns_kasp_t *kasp);
  479 /*%<
  480  * Check if the keylist is empty.
  481  *
  482  * Requires:
  483  *
  484  *\li   'kasp' is a valid kasp.
  485  *
  486  * Returns:
  487  *
  488  *\li  true if the keylist is empty, false otherwise.
  489  */
  490 
  491 void
  492 dns_kasp_addkey(dns_kasp_t *kasp, dns_kasp_key_t *key);
  493 /*%<
  494  * Add a key.
  495  *
  496  * Requires:
  497  *
  498  *\li   'kasp' is a valid, thawed kasp.
  499  *\li   'key' is not NULL.
  500  */
  501 
  502 isc_result_t
  503 dns_kasp_key_create(dns_kasp_t *kasp, dns_kasp_key_t **keyp);
  504 /*%<
  505  * Create a key inside a KASP.
  506  *
  507  * Requires:
  508  *
  509  *\li   'kasp' is a valid kasp.
  510  *
  511  *\li  keyp != NULL && *keyp == NULL
  512  *
  513  * Returns:
  514  *
  515  *\li  #ISC_R_SUCCESS
  516  *\li  #ISC_R_NOMEMORY
  517  *
  518  *\li  Other errors are possible.
  519  */
  520 
  521 void
  522 dns_kasp_key_destroy(dns_kasp_key_t *key);
  523 /*%<
  524  * Destroy a KASP key.
  525  *
  526  * Requires:
  527  *
  528  *\li  key != NULL
  529  */
  530 
  531 uint32_t
  532 dns_kasp_key_algorithm(dns_kasp_key_t *key);
  533 /*%<
  534  * Get the key algorithm.
  535  *
  536  * Requires:
  537  *
  538  *\li  key != NULL
  539  *
  540  * Returns:
  541  *
  542  *\li  Key algorithm.
  543  */
  544 
  545 unsigned int
  546 dns_kasp_key_size(dns_kasp_key_t *key);
  547 /*%<
  548  * Get the key size.
  549  *
  550  * Requires:
  551  *
  552  *\li  key != NULL
  553  *
  554  * Returns:
  555  *
  556  *\li  Configured key size, or default key size for key algorithm if no size
  557  *     configured.
  558  */
  559 
  560 uint32_t
  561 dns_kasp_key_lifetime(dns_kasp_key_t *key);
  562 /*%<
  563  * The lifetime of this key (how long may this key be active?)
  564  *
  565  * Requires:
  566  *
  567  *\li  key != NULL
  568  *
  569  * Returns:
  570  *
  571  *\li  Lifetime of key.
  572  *
  573  */
  574 
  575 bool
  576 dns_kasp_key_ksk(dns_kasp_key_t *key);
  577 /*%<
  578  * Does this key act as a KSK?
  579  *
  580  * Requires:
  581  *
  582  *\li  key != NULL
  583  *
  584  * Returns:
  585  *
  586  *\li  True, if the key role has DNS_KASP_KEY_ROLE_KSK set.
  587  *\li  False, otherwise.
  588  *
  589  */
  590 
  591 bool
  592 dns_kasp_key_zsk(dns_kasp_key_t *key);
  593 /*%<
  594  * Does this key act as a ZSK?
  595  *
  596  * Requires:
  597  *
  598  *\li  key != NULL
  599  *
  600  * Returns:
  601  *
  602  *\li  True, if the key role has DNS_KASP_KEY_ROLE_ZSK set.
  603  *\li  False, otherwise.
  604  *
  605  */
  606 
  607 ISC_LANG_ENDDECLS
  608 
  609 #endif /* DNS_KASP_H */