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