1 /* $NetBSD: keymgr.h,v 1.6 2022/09/23 12:15:30 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 #ifndef DNS_KEYMGR_H 17 #define DNS_KEYMGR_H 1 18 19 /*! \file dns/keymgr.h */ 20 21 #include <isc/lang.h> 22 #include <isc/stdtime.h> 23 24 #include <dns/types.h> 25 26 #include <dst/dst.h> 27 28 ISC_LANG_BEGINDECLS 29 30 isc_result_t 31 dns_keymgr_run(const dns_name_t *origin, dns_rdataclass_t rdclass, 32 const char *directory, isc_mem_t *mctx, 33 dns_dnsseckeylist_t *keyring, dns_dnsseckeylist_t *dnskeys, 34 dns_kasp_t *kasp, isc_stdtime_t now, isc_stdtime_t *nexttime); 35 /*%< 36 * Manage keys in 'keyring' and update timing data according to 'kasp' policy. 37 * Create new keys for 'origin' if necessary in 'directory'. Append all such 38 * keys, along with use hints gleaned from their metadata, onto 'keyring'. 39 * 40 * Update key states and store changes back to disk. Store when to run next 41 * in 'nexttime'. 42 * 43 * Requires: 44 *\li 'origin' is a valid FQDN. 45 *\li 'mctx' is a valid memory context. 46 *\li 'keyring' is not NULL. 47 *\li 'kasp' is not NULL. 48 * 49 * Returns: 50 *\li #ISC_R_SUCCESS 51 *\li any error returned by dst_key_generate(), isc_dir_open(), 52 * dst_key_to_file(), or dns_dnsseckey_create(). 53 * 54 * Ensures: 55 *\li On error, keypool is unchanged 56 */ 57 58 isc_result_t 59 dns_keymgr_checkds(dns_kasp_t *kasp, dns_dnsseckeylist_t *keyring, 60 const char *directory, isc_stdtime_t now, isc_stdtime_t when, 61 bool dspublish); 62 isc_result_t 63 dns_keymgr_checkds_id(dns_kasp_t *kasp, dns_dnsseckeylist_t *keyring, 64 const char *directory, isc_stdtime_t now, 65 isc_stdtime_t when, bool dspublish, dns_keytag_t id, 66 unsigned int algorithm); 67 /*%< 68 * Check DS for one key in 'keyring'. The key must have the KSK role. 69 * If 'dspublish' is set to true, set the DS Publish time to 'now'. 70 * If 'dspublish' is set to false, set the DS Removed time to 'now'. 71 * If a specific key 'id' is given it must match the keytag. 72 * If the 'algorithm' is non-zero, it must match the key's algorithm. 73 * The result is stored in the key state file. 74 * 75 * Requires: 76 *\li 'kasp' is not NULL. 77 *\li 'keyring' is not NULL. 78 * 79 * Returns: 80 *\li #ISC_R_SUCCESS (No error). 81 *\li #DNS_R_NOKEYMATCH (No matching keys found). 82 *\li #DNS_R_TOOMANYKEYS (More than one matching keys found). 83 * 84 */ 85 86 isc_result_t 87 dns_keymgr_rollover(dns_kasp_t *kasp, dns_dnsseckeylist_t *keyring, 88 const char *directory, isc_stdtime_t now, 89 isc_stdtime_t when, dns_keytag_t id, 90 unsigned int algorithm); 91 /*%< 92 * Rollover key with given 'id'. If the 'algorithm' is non-zero, it must 93 * match the key's algorithm. The changes are stored in the key state file. 94 * 95 * A rollover means adjusting the key metadata so that keymgr will start the 96 * actual rollover on the next run. Update the 'inactive' time and adjust 97 * key lifetime to match the 'when' to rollover time. 98 * 99 * The 'when' time may be in the past. In that case keymgr will roll the 100 * key as soon as possible. 101 * 102 * The 'when' time may be in the future. This may extend the lifetime, 103 * overriding the default lifetime from the policy. 104 * 105 * Requires: 106 *\li 'kasp' is not NULL. 107 *\li 'keyring' is not NULL. 108 * 109 * Returns: 110 *\li #ISC_R_SUCCESS (No error). 111 *\li #DNS_R_NOKEYMATCH (No matching keys found). 112 *\li #DNS_R_TOOMANYKEYS (More than one matching keys found). 113 *\li #DNS_R_KEYNOTACTIVE (Key is not active). 114 * 115 */ 116 117 void 118 dns_keymgr_status(dns_kasp_t *kasp, dns_dnsseckeylist_t *keyring, 119 isc_stdtime_t now, char *out, size_t out_len); 120 /*%< 121 * Retrieve the status of given 'kasp' policy and keys in the 122 * 'keyring' and store the printable output in the 'out' buffer. 123 * 124 * Requires: 125 *\li 'kasp' is not NULL. 126 *\li 'keyring' is not NULL. 127 *\li 'out' is not NULL. 128 * 129 * Returns: 130 *\li Printable status in 'out'. 131 * 132 */ 133 134 ISC_LANG_ENDDECLS 135 136 #endif /* DNS_KEYMGR_H */ 137