1*c0b5d9fbSchristos /* $NetBSD: keymgr.h,v 1.6 2022/09/23 12:15:30 christos Exp $ */ 2207778f5Schristos 3207778f5Schristos /* 4207778f5Schristos * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5207778f5Schristos * 6*c0b5d9fbSchristos * SPDX-License-Identifier: MPL-2.0 7*c0b5d9fbSchristos * 8207778f5Schristos * This Source Code Form is subject to the terms of the Mozilla Public 9207778f5Schristos * License, v. 2.0. If a copy of the MPL was not distributed with this 1073584a28Schristos * file, you can obtain one at https://mozilla.org/MPL/2.0/. 11207778f5Schristos * 12207778f5Schristos * See the COPYRIGHT file distributed with this work for additional 13207778f5Schristos * information regarding copyright ownership. 14207778f5Schristos */ 15207778f5Schristos 16207778f5Schristos #ifndef DNS_KEYMGR_H 17207778f5Schristos #define DNS_KEYMGR_H 1 18207778f5Schristos 19207778f5Schristos /*! \file dns/keymgr.h */ 20207778f5Schristos 21207778f5Schristos #include <isc/lang.h> 22207778f5Schristos #include <isc/stdtime.h> 23207778f5Schristos 24207778f5Schristos #include <dns/types.h> 25207778f5Schristos 26207778f5Schristos #include <dst/dst.h> 27207778f5Schristos 28207778f5Schristos ISC_LANG_BEGINDECLS 29207778f5Schristos 30207778f5Schristos isc_result_t 31207778f5Schristos dns_keymgr_run(const dns_name_t *origin, dns_rdataclass_t rdclass, 32207778f5Schristos const char *directory, isc_mem_t *mctx, 33fadf0758Schristos dns_dnsseckeylist_t *keyring, dns_dnsseckeylist_t *dnskeys, 34fadf0758Schristos dns_kasp_t *kasp, isc_stdtime_t now, isc_stdtime_t *nexttime); 35207778f5Schristos /*%< 36fadf0758Schristos * Manage keys in 'keyring' and update timing data according to 'kasp' policy. 37207778f5Schristos * Create new keys for 'origin' if necessary in 'directory'. Append all such 38fadf0758Schristos * keys, along with use hints gleaned from their metadata, onto 'keyring'. 39207778f5Schristos * 40207778f5Schristos * Update key states and store changes back to disk. Store when to run next 41207778f5Schristos * in 'nexttime'. 42207778f5Schristos * 43207778f5Schristos * Requires: 44207778f5Schristos *\li 'origin' is a valid FQDN. 45207778f5Schristos *\li 'mctx' is a valid memory context. 46207778f5Schristos *\li 'keyring' is not NULL. 47207778f5Schristos *\li 'kasp' is not NULL. 48207778f5Schristos * 49207778f5Schristos * Returns: 50207778f5Schristos *\li #ISC_R_SUCCESS 51207778f5Schristos *\li any error returned by dst_key_generate(), isc_dir_open(), 52207778f5Schristos * dst_key_to_file(), or dns_dnsseckey_create(). 53207778f5Schristos * 54207778f5Schristos * Ensures: 55207778f5Schristos *\li On error, keypool is unchanged 56207778f5Schristos */ 57207778f5Schristos 5873584a28Schristos isc_result_t 5973584a28Schristos dns_keymgr_checkds(dns_kasp_t *kasp, dns_dnsseckeylist_t *keyring, 6073584a28Schristos const char *directory, isc_stdtime_t now, isc_stdtime_t when, 6173584a28Schristos bool dspublish); 6273584a28Schristos isc_result_t 6373584a28Schristos dns_keymgr_checkds_id(dns_kasp_t *kasp, dns_dnsseckeylist_t *keyring, 6473584a28Schristos const char *directory, isc_stdtime_t now, 6573584a28Schristos isc_stdtime_t when, bool dspublish, dns_keytag_t id, 6673584a28Schristos unsigned int algorithm); 6773584a28Schristos /*%< 6873584a28Schristos * Check DS for one key in 'keyring'. The key must have the KSK role. 6973584a28Schristos * If 'dspublish' is set to true, set the DS Publish time to 'now'. 7073584a28Schristos * If 'dspublish' is set to false, set the DS Removed time to 'now'. 7173584a28Schristos * If a specific key 'id' is given it must match the keytag. 7273584a28Schristos * If the 'algorithm' is non-zero, it must match the key's algorithm. 7373584a28Schristos * The result is stored in the key state file. 7473584a28Schristos * 7573584a28Schristos * Requires: 7673584a28Schristos *\li 'kasp' is not NULL. 7773584a28Schristos *\li 'keyring' is not NULL. 7873584a28Schristos * 7973584a28Schristos * Returns: 8073584a28Schristos *\li #ISC_R_SUCCESS (No error). 8173584a28Schristos *\li #DNS_R_NOKEYMATCH (No matching keys found). 8273584a28Schristos *\li #DNS_R_TOOMANYKEYS (More than one matching keys found). 8373584a28Schristos * 8473584a28Schristos */ 8573584a28Schristos 8673584a28Schristos isc_result_t 8773584a28Schristos dns_keymgr_rollover(dns_kasp_t *kasp, dns_dnsseckeylist_t *keyring, 8873584a28Schristos const char *directory, isc_stdtime_t now, 8973584a28Schristos isc_stdtime_t when, dns_keytag_t id, 9073584a28Schristos unsigned int algorithm); 9173584a28Schristos /*%< 9273584a28Schristos * Rollover key with given 'id'. If the 'algorithm' is non-zero, it must 9373584a28Schristos * match the key's algorithm. The changes are stored in the key state file. 9473584a28Schristos * 9573584a28Schristos * A rollover means adjusting the key metadata so that keymgr will start the 9673584a28Schristos * actual rollover on the next run. Update the 'inactive' time and adjust 9773584a28Schristos * key lifetime to match the 'when' to rollover time. 9873584a28Schristos * 9973584a28Schristos * The 'when' time may be in the past. In that case keymgr will roll the 10073584a28Schristos * key as soon as possible. 10173584a28Schristos * 10273584a28Schristos * The 'when' time may be in the future. This may extend the lifetime, 10373584a28Schristos * overriding the default lifetime from the policy. 10473584a28Schristos * 10573584a28Schristos * Requires: 10673584a28Schristos *\li 'kasp' is not NULL. 10773584a28Schristos *\li 'keyring' is not NULL. 10873584a28Schristos * 10973584a28Schristos * Returns: 11073584a28Schristos *\li #ISC_R_SUCCESS (No error). 11173584a28Schristos *\li #DNS_R_NOKEYMATCH (No matching keys found). 11273584a28Schristos *\li #DNS_R_TOOMANYKEYS (More than one matching keys found). 11373584a28Schristos *\li #DNS_R_KEYNOTACTIVE (Key is not active). 11473584a28Schristos * 11573584a28Schristos */ 11673584a28Schristos 117803e9293Schristos void 118803e9293Schristos dns_keymgr_status(dns_kasp_t *kasp, dns_dnsseckeylist_t *keyring, 119803e9293Schristos isc_stdtime_t now, char *out, size_t out_len); 120803e9293Schristos /*%< 121803e9293Schristos * Retrieve the status of given 'kasp' policy and keys in the 122803e9293Schristos * 'keyring' and store the printable output in the 'out' buffer. 123803e9293Schristos * 124803e9293Schristos * Requires: 125803e9293Schristos *\li 'kasp' is not NULL. 126803e9293Schristos *\li 'keyring' is not NULL. 127803e9293Schristos *\li 'out' is not NULL. 128803e9293Schristos * 129803e9293Schristos * Returns: 130803e9293Schristos *\li Printable status in 'out'. 131803e9293Schristos * 132803e9293Schristos */ 133803e9293Schristos 134207778f5Schristos ISC_LANG_ENDDECLS 135207778f5Schristos 136207778f5Schristos #endif /* DNS_KEYMGR_H */ 137