Home | History | Annotate | Line # | Download | only in dns 
      1 /*	$NetBSD: skr.h,v 1.3 2025/05/21 14:48:04 christos Exp $	*/
      2 
      3 /*
      4  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
      5  *
      6  * SPDX-License-Identifier: MPL-2.0
      7  *
      8  * This Source Code Form is subject to the terms of the Mozilla Public
      9  * License, v. 2.0. If a copy of the MPL was not distributed with this
     10  * file, you can obtain one at https://mozilla.org/MPL/2.0/.
     11  *
     12  * See the COPYRIGHT file distributed with this work for additional
     13  * information regarding copyright ownership.
     14  */
     15 
     16 #pragma once
     17 
     18 /*! \file dns/skr.h
     19  * \brief
     20  * A skr is a convenience type representing a Signed Key Response (SKR),
     21  * determining which DNSKEY, CDS, CDNSKEY and corresponding signatures
     22  * should be published at a given time. It is based on terminology used in
     23  * https://web.archive.org/web/20250121040252/https://www.iana.org/dnssec/archive/files/draft-icann-dnssec-keymgmt-01.txt
     24  */
     25 
     26 #include <isc/stdtime.h>
     27 
     28 #include <dns/diff.h>
     29 #include <dns/types.h>
     30 
     31 ISC_LANG_BEGINDECLS
     32 
     33 #define DNS_SKR_MAGIC	 ISC_MAGIC('S', 'K', 'R', '-')
     34 #define DNS_SKR_VALID(t) ISC_MAGIC_VALID(t, DNS_SKR_MAGIC)
     35 
     36 #define DNS_SKRBUNDLE_MAGIC    ISC_MAGIC('S', 'K', 'R', 'B')
     37 #define DNS_SKRBUNDLE_VALID(t) ISC_MAGIC_VALID(t, DNS_SKRBUNDLE_MAGIC)
     38 
     39 typedef struct dns_skrbundle dns_skrbundle_t;
     40 typedef ISC_LIST(dns_skrbundle_t) dns_skrbundlelist_t;
     41 
     42 /* Stores a Signed Key Response (SKR) */
     43 struct dns_skr {
     44 	unsigned int	    magic;
     45 	isc_mem_t	   *mctx;
     46 	char		   *filename;
     47 	isc_time_t	    loadtime;
     48 	dns_skrbundlelist_t bundles;
     49 	isc_refcount_t	    references;
     50 };
     51 
     52 struct dns_skrbundle {
     53 	unsigned int  magic;
     54 	isc_stdtime_t inception;
     55 	dns_diff_t    diff;
     56 	ISC_LINK(dns_skrbundle_t) link;
     57 };
     58 
     59 isc_result_t
     60 dns_skrbundle_getsig(dns_skrbundle_t *bundle, dst_key_t *key,
     61 		     dns_rdatatype_t covering_type, dns_rdata_t *sigrdata);
     62 /*%<
     63  * Retrieve the RRSIG rdata for 'covering_type' generated by 'key' from the
     64  * given 'bundle'.
     65  *
     66  * Requires:
     67  * \li   'bundle' is a valid bundle
     68  *
     69  * Returns:
     70  * \li   a possible error if we fail to convert the rdata to a struct
     71  * \li   ISC_R_SUCCESS if the signature is found
     72  * \li   ISC_R_NOTFOUND otherwise
     73  */
     74 
     75 void
     76 dns_skr_create(isc_mem_t *mctx, const char *filename, dns_name_t *origin,
     77 	       dns_rdataclass_t rdclass, dns_skr_t **skrp);
     78 /*%<
     79  * Create a SKR.
     80  *
     81  * Requires:
     82  * \li   mctx != NULL
     83  * \li   *skrp != NULL && *skrp == NULL
     84  */
     85 
     86 isc_result_t
     87 dns_skr_read(isc_mem_t *mctx, const char *filename, dns_name_t *origin,
     88 	     dns_rdataclass_t rdclass, dns_ttl_t dnskeyttl, dns_skr_t **skrp);
     89 /*%<
     90  * Read a SKR from 'filename'.
     91  *
     92  * Requires:
     93  * \li   mctx != NULL
     94  * \li   *skrp != NULL && *skrp == NULL
     95  */
     96 
     97 dns_skrbundle_t *
     98 dns_skr_lookup(dns_skr_t *skr, isc_stdtime_t time, uint32_t sigval);
     99 /*%<
    100  * Look up the currently active bundle. The active bundle is the one which
    101  * inception time is prior to 'time' and the next bundle inception is after
    102  " 'time'. In case of the last bundle in the SKR, 'time' is expected to be
    103  * lower than the last bundle inception time plus 'sigval'.
    104  *
    105  * Requires:
    106  * \li   'skr' is a valid SKR
    107  *
    108  * Returns:
    109  * \li   The currently active bundle, or NULL if no such bundle is found.
    110  */
    111 
    112 void
    113 dns_skr_attach(dns_skr_t *source, dns_skr_t **targetp);
    114 /*%<
    115  * Attach '*targetp' to 'source'.
    116  *
    117  * Requires:
    118  *
    119  *\li   'source' is a valid SKR.
    120  *
    121  *\li   'targetp' points to a NULL dns_skr_t *.
    122  *
    123  * Ensures:
    124  *
    125  *\li   *targetp is attached to source.
    126  */
    127 
    128 void
    129 dns_skr_detach(dns_skr_t **skrp);
    130 /*%<
    131  * Detach SKR.
    132  *
    133  * Requires:
    134  *
    135  *\li   'skrp' points to a valid dns_skr_t *
    136  *
    137  * Ensures:
    138  *
    139  *\li   *skrp is NULL.
    140  */
    141 
    142 void
    143 dns_skr_destroy(dns_skr_t *skr);
    144 /*%<
    145  * Destroy a SKR.
    146  *
    147  * Requires:
    148  * \li   'skr' is a valid SKR
    149  */
    150 
    151 ISC_LANG_ENDDECLS
    152