1 /* $NetBSD: keymgr.h,v 1.11 2026/01/29 18:37:50 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/keymgr.h */ 19 20 #include <isc/lang.h> 21 #include <isc/stdtime.h> 22 23 #include <dns/types.h> 24 25 #include <dst/dst.h> 26 27 ISC_LANG_BEGINDECLS 28 29 #define DNS_KEYMGRATTR_NONE 0x00 /*%< No ordering. */ 30 #define DNS_KEYMGRATTR_S2I 0x01 /*%< Secure to insecure. */ 31 #define DNS_KEYMGRATTR_NOROLL 0x02 /*%< No rollover allowed. */ 32 #define DNS_KEYMGRATTR_FORCESTEP 0x04 /*%< Force next step in manual-mode. */ 33 #define DNS_KEYMGRATTR_FULLSIGN 0x08 /*%< Full sign was issued. */ 34 35 void 36 dns_keymgr_settime_syncpublish(dst_key_t *key, dns_kasp_t *kasp, bool first); 37 /*%< 38 * Set the SyncPublish time (when the DS may be submitted to the parent). 39 * If 'first' is true, also make sure that the zone signatures are omnipresent. 40 * 41 * Requires: 42 *\li 'key' is a valid DNSSEC key. 43 *\li 'kasp' is a valid DNSSEC policy. 44 */ 45 46 void 47 dns_keymgr_key_init(dns_dnsseckey_t *key, dns_kasp_t *kasp, isc_stdtime_t now, 48 bool csk); 49 /* 50 * Initialize this key's properties if not already present. A key created 51 * and derived from a dnssec-policy will have the required metadata available, 52 * otherwise these may be missing and need to be initialized. The key states 53 * will be initialized according to existing timing metadata. If 'csk' is 54 * set to true, the key is considered a combined signing key (CSK). 55 * 56 * Requires: 57 *\li 'key' is a valid DNSSEC key. 58 *\li 'kasp' is a valid DNSSEC policy. 59 */ 60 61 isc_result_t 62 dns_keymgr_run(const dns_name_t *origin, dns_rdataclass_t rdclass, 63 isc_mem_t *mctx, dns_dnsseckeylist_t *keyring, 64 dns_dnsseckeylist_t *dnskeys, const char *keydir, 65 dns_kasp_t *kasp, uint8_t options, isc_stdtime_t now, 66 isc_stdtime_t *nexttime); 67 /*%< 68 * Manage keys in 'keyring' and update timing data according to 'kasp' policy. 69 * Create new keys for 'origin' if necessary. Append all such keys, along 70 * with use hints gleaned from their metadata, onto 'keyring'. 71 * 72 * Update key states and store changes back to disk. Store when to run next 73 * in 'nexttime'. 74 * 75 * If 'options' has DNS_KEYMGRATTR_FORCESTEP set, the next steps in the process 76 * are allowed, even if 'kasp' has 'manual-mode' enabled. Other options should 77 * not be set in 'options'. 78 * 79 * Requires: 80 *\li 'origin' is a valid FQDN. 81 *\li 'mctx' is a valid memory context. 82 *\li 'keyring' is not NULL. 83 *\li 'kasp' is not NULL. 84 * 85 * Returns: 86 *\li #ISC_R_SUCCESS 87 *\li any error returned by dst_key_generate(), isc_dir_open(), 88 * dst_key_to_file(), or dns_dnsseckey_create(). 89 * 90 * Ensures: 91 *\li On error, keypool is unchanged 92 */ 93 94 isc_result_t 95 dns_keymgr_offline(const dns_name_t *origin, dns_dnsseckeylist_t *keyring, 96 dns_kasp_t *kasp, isc_stdtime_t now, 97 isc_stdtime_t *nexttime); 98 /*%< 99 * Manage keys in 'keyring' when in offline-ksk mode, and update timing data 100 * according to the metadata in the key files. KSKs are skipped. 101 * 102 * Update key states and store changes back to disk. Store when to run next 103 * in 'nexttime'. 104 * 105 * Requires: 106 *\li 'origin' is a valid FQDN. 107 *\li 'mctx' is a valid memory context. 108 *\li 'keyring' is not NULL. 109 *\li 'kasp' is not NULL. 110 * 111 * Returns: 112 *\li #ISC_R_SUCCESS 113 *\li any error returned by dst_key_getstate(), dst_key_gettime(), 114 * isc_dir_open(), or dst_key_to_file(). 115 */ 116 117 isc_result_t 118 dns_keymgr_checkds(dns_kasp_t *kasp, dns_dnsseckeylist_t *keyring, 119 isc_stdtime_t now, isc_stdtime_t when, bool dspublish); 120 isc_result_t 121 dns_keymgr_checkds_id(dns_kasp_t *kasp, dns_dnsseckeylist_t *keyring, 122 isc_stdtime_t now, isc_stdtime_t when, bool dspublish, 123 dns_keytag_t id, unsigned int algorithm); 124 /*%< 125 * Check DS for one key in 'keyring'. The key must have the KSK role. 126 * If 'dspublish' is set to true, set the DS Publish time to 'now'. 127 * If 'dspublish' is set to false, set the DS Removed time to 'now'. 128 * If a specific key 'id' is given it must match the keytag. 129 * If the 'algorithm' is non-zero, it must match the key's algorithm. 130 * The result is stored in the key state file. 131 * 132 * Requires: 133 *\li 'kasp' is not NULL. 134 *\li 'keyring' is not NULL. 135 * 136 * Returns: 137 *\li #ISC_R_SUCCESS (No error). 138 *\li #DNS_R_NOKEYMATCH (No matching keys found). 139 *\li #DNS_R_TOOMANYKEYS (More than one matching keys found). 140 * 141 */ 142 143 isc_result_t 144 dns_keymgr_rollover(dns_kasp_t *kasp, dns_dnsseckeylist_t *keyring, 145 isc_stdtime_t now, isc_stdtime_t when, dns_keytag_t id, 146 unsigned int algorithm); 147 /*%< 148 * Rollover key with given 'id'. If the 'algorithm' is non-zero, it must 149 * match the key's algorithm. The changes are stored in the key state file. 150 * 151 * A rollover means adjusting the key metadata so that keymgr will start the 152 * actual rollover on the next run. Update the 'inactive' time and adjust 153 * key lifetime to match the 'when' to rollover time. 154 * 155 * The 'when' time may be in the past. In that case keymgr will roll the 156 * key as soon as possible. 157 * 158 * The 'when' time may be in the future. This may extend the lifetime, 159 * overriding the default lifetime from the policy. 160 * 161 * Requires: 162 *\li 'kasp' is not NULL. 163 *\li 'keyring' is not NULL. 164 * 165 * Returns: 166 *\li #ISC_R_SUCCESS (No error). 167 *\li #DNS_R_NOKEYMATCH (No matching keys found). 168 *\li #DNS_R_TOOMANYKEYS (More than one matching keys found). 169 *\li #DNS_R_KEYNOTACTIVE (Key is not active). 170 * 171 */ 172 173 isc_result_t 174 dns_keymgr_status(dns_kasp_t *kasp, dns_dnsseckeylist_t *keyring, 175 isc_stdtime_t now, char *out, size_t out_len); 176 /*%< 177 * Retrieve the status of given 'kasp' policy and keys in the 178 * 'keyring' and store the printable output in the 'out' buffer. 179 * 180 * Requires: 181 *\li 'kasp' is not NULL. 182 *\li 'keyring' is not NULL. 183 *\li 'out' is not NULL. 184 * 185 * Returns: 186 *\li ISC_R_SUCCESS on success. 187 *\li ISC_R_NOSPACE if the 'out' buffer is too small. 188 *\li ISC_R_FAILURE if other error occurred. 189 *\li Printable status in 'out'. 190 * 191 */ 192 193 bool 194 dns_keymgr_key_may_be_purged(const dst_key_t *key, uint32_t after, 195 isc_stdtime_t now); 196 /*%< 197 * Checks if the key files for 'key' may be removed from disk. 198 * 199 * Requires: 200 *\li 'key' is a valid key. 201 * 202 * Returns: 203 *\li true if the key files may be purged, false otherwise. 204 */ 205 206 ISC_LANG_ENDDECLS 207
Indexes created Mon Aug 17 00:26:26 UTC 2026