1 /*------------------------------------------------------------------------------ 2 * 3 * Copyright (c) 2011-2021, EURid vzw. All rights reserved. 4 * The YADIFA TM software product is provided under the BSD 3-clause license: 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions 8 * are met: 9 * 10 * * Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * * Neither the name of EURid nor the names of its contributors may be 16 * used to endorse or promote products derived from this software 17 * without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 20 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 23 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29 * POSSIBILITY OF SUCH DAMAGE. 30 * 31 *------------------------------------------------------------------------------ 32 * 33 */ 34 35 #pragma once 36 37 #include <dnscore/host_address.h> 38 #include <dnscore/dnskey-keyring.h> 39 #include <dnscore/ptr_set.h> 40 #include <dnscore/u64_set.h> 41 42 #ifndef PACKAGE_VERSION 43 #include "keyroll-config.h" 44 #endif 45 46 #define YKEYROLL_NAME "yakeyrolld" 47 #define YKEYROLL_VERSION PACKAGE_VERSION 48 49 #define YKEYROLL_KSK_SUFFIX "_SECRET_KEYSIGNINGKEY" 50 51 #define DNSKEY_TTL_DEFAULT 86400 52 53 #define KEYROLL_QUERY_TIMEOUT_S 10 // seconds 54 55 #define KEYROLL_ERROR_BASE 0x80100000 56 #define KEYROLL_ERROR_CODE(code_) ((s32)(KEYROLL_ERROR_BASE+(code_))) 57 #define KEYROLL_EXPECTED_IDENTICAL_RECORDS KEYROLL_ERROR_CODE(1) 58 #define KEYROLL_EXPECTED_IDENTICAL_SIZE_RRSETS KEYROLL_ERROR_CODE(2) 59 #define KEYROLL_EXPECTED_DNSKEY_OR_RRSIG KEYROLL_ERROR_CODE(3) 60 #define KEYROLL_UPDATE_SUBCOMMAND_ERROR KEYROLL_ERROR_CODE(4) 61 #define KEYROLL_HOLE_IN_TIMELINE KEYROLL_ERROR_CODE(5) 62 #define KEYROLL_MUST_REINITIALIZE KEYROLL_ERROR_CODE(6) 63 64 enum KeyrollAction 65 { 66 Publish = 1, 67 Activate = 2, 68 Deactivate = 4, 69 Unpublish = 8 70 }; 71 72 struct keyroll_s; 73 74 typedef struct keyroll_step_s 75 { 76 struct keyroll_s* keyroll; // link back to the keyroll 77 s64 epochus; 78 ptr_vector dnskey_del; // keys added at this instant 79 ptr_vector dnskey_add; // keys demoved at this instant 80 ptr_vector rrsig_add; // signatures added at this instant 81 ptr_vector expect; // dns_resource_record vector 82 ptr_vector endresult; // dns_resource_record vector 83 ptr_set file_add; // list of the files to be added + content 84 ptr_vector file_del; // list of the files to be deleted 85 86 u64 fingerprint; // number generated from dnskey_set, based on currently present tags 87 u8 keyroll_action; 88 89 bool dirty; 90 bool from_merge; 91 } keyroll_step_t; 92 93 typedef struct keyroll_key_parameters_s 94 { 95 u32 activate_after; // publish + 96 u32 deactivate_after; // publish + 97 u32 delete_after; // publish + 98 u32 estimated_signing_time; 99 u16 size; 100 u8 algorithm; 101 } keyroll_key_parameters_t; 102 103 typedef struct keyroll_s 104 { 105 u8 *domain; 106 107 host_address *server; 108 dnskey_keyring *keyring; 109 char *plan_path; 110 char *keys_path; 111 char *private_keys_path; 112 113 u64_set steps; 114 115 keyroll_key_parameters_t ksk_parameters; 116 keyroll_key_parameters_t zsk_parameters; 117 118 s64 ksk_next_deactivation; 119 120 s64 zsk_next_deactivation; 121 122 u32 update_apply_verify_retries; // if an update wasn't applied successfully, retry CHECKING this amount of times 123 u32 update_apply_verify_retries_delay; // time between the above retries 124 125 u32 match_verify_retries; // if there is not match, retry checking this amount of times 126 u32 match_verify_retries_delay; // time between the above retries 127 128 bool generation_mode; 129 130 // current key records 131 } keyroll_t; 132 133 void keyroll_errors_register(); 134 135 s64 keyroll_set_timing_steps(keyroll_t *keyroll, dnssec_key *key, bool dirty); 136 137 /** 138 * Keyroll initialisation for a domain 139 * 140 * @param domain the domain 141 * @param plan_path the directory containing the plan files (the sequence of steps) 142 * @param keys_path the directory where to put the keys 143 * @param server the server address 144 */ 145 146 ya_result keyroll_init(keyroll_t* keyroll, const u8 *domain, const char *plan_path, const char *keys_path, const host_address *server, bool generation_mode); 147 148 /** 149 * Connects to the server, fetches the public keys and add them to the keyring. 150 */ 151 152 ya_result keyroll_fetch_public_keys_from_server(keyroll_t* keyroll); 153 154 /** 155 * Does an keyroll_init followed by a keyroll_fetch_public_keys_from_server. 156 */ 157 158 ya_result keyroll_init_from_server(keyroll_t* keyroll, const u8 *domain, const char *plan_path, const char *keys_path, const host_address *server); 159 160 ya_result keyroll_update_apply_verify_retries_set(keyroll_t* keyroll, u32 retries, u32 delay); 161 ya_result keyroll_match_verify_retries_set(keyroll_t* keyroll, u32 retries, u32 delay); 162 163 void keyroll_finalize(keyroll_t *keyroll); 164 165 /** 166 * Generates a DNSKEY to be published at the given epoch. 167 * The DNSKEY can be set as a KSK or ZSK using the ksk parameter. 168 * This function creates steps at the various time fields of the key. 169 */ 170 171 ya_result keyroll_generate_dnskey(keyroll_t *keyroll, s64 publication_epochus, bool ksk); 172 173 /** 174 * Generates a DNSKEY to be published at the given epoch. 175 * The DNSKEY can be set as a KSK or ZSK using the ksk parameter. 176 * This functions requires the time fields to be set manually. 177 * This function creates steps at the various time fields of the key. 178 */ 179 180 ya_result keyroll_generate_dnskey_ex(keyroll_t *keyroll, u32 size, u8 algorithm, 181 s64 creation_epochus, s64 publication_epochus, s64 activate_epochus, 182 s64 deactivate_epochus, s64 unpublish_epochus, bool ksk, dnssec_key **out_keyp); 183 184 /** 185 * Returns the step at the given epoch, or create an empty one 186 */ 187 188 keyroll_step_t* keyroll_get_step(keyroll_t *keyroll, s64 epochus); 189 190 /** 191 * Queries the server for its current state (DNSKEY + RRSIG DNSKEY records) 192 * 193 * Appends found dns_resource_record* to the ptr_vector 194 * 195 * The ptr_vector is expected to be initialised and empty, or at the very least only filled with 196 * dns_resource_record* 197 * 198 */ 199 200 ya_result keyroll_dnskey_state_query(const keyroll_t *keyroll, ptr_vector *current_dnskey_rrsig_rr); 201 202 /** 203 * Releases the memory used by dns_resource_record* in the ptr_vector 204 */ 205 206 void keyroll_dnskey_state_destroy(ptr_vector *current_dnskey_rrsig_rr); 207 208 /** 209 * Compares the expected state at a given step with the state on the server 210 * (queried with keyroll_dnskey_state_query) 211 * 212 * Returns SUCCESS iff it's a match. 213 */ 214 215 ya_result keyroll_step_expects_matched(const keyroll_step_t *step, const ptr_vector *dnskey_rrsig_rr); 216 217 /** 218 * Scans the plan for the step matching the given state 219 * 220 * Returns the matching step or NULL 221 */ 222 223 keyroll_step_t* keyroll_step_scan_matching_expectations(const keyroll_t *keyroll, ptr_vector *current_dnskey_rrsig_rr); 224 225 /** 226 * Plays a step on the server 227 * 228 * @param step the step to play 229 * @param delete_all_dnskey delete all keys on the server. 230 */ 231 232 ya_result keyroll_step_play(const keyroll_step_t *step, bool delete_all_dnskey); 233 234 /** 235 * Plays all the steps in a given epoch range. 236 */ 237 238 ya_result keyroll_step_play_range_ex(const keyroll_t *keyroll, s64 seek_from , s64 now, bool delete_all_dnskey, keyroll_step_t **first_stepp); 239 240 /** 241 * Plays all the steps in a given epoch range. 242 */ 243 244 ya_result keyroll_step_play_range(const keyroll_t *keyroll, s64 seek_from , s64 now); 245 246 /** 247 * Plays the first step of a plan if it's before a given epoch. 248 * If the first step is in the future, it's not played. 249 * Returns the first step in the parameter. 250 * Returns an error code. 251 */ 252 253 ya_result keyroll_play_first_step(const keyroll_t *keyroll, s64 now, keyroll_step_t **first_stepp); 254 255 /** 256 * Returns the step being active at the given epoch or NULL if there is no such step. 257 * If a step starts at the given epoch, it's the one returned. 258 */ 259 260 keyroll_step_t* keyroll_get_current_step_at(const keyroll_t *keyroll, s64 epochus); 261 262 /** 263 * Returns the next step to be active from the given epoch or NULL if there is no such step. 264 * If a step starts at the given epoch, it's the one returned. 265 */ 266 267 keyroll_step_t* keyroll_get_next_step_from(const keyroll_t *keyroll, s64 epochus); 268 269 /** 270 * Destroys all the .keyroll, .key and .private files of a plan (obviously dangerous) 271 */ 272 273 ya_result keyroll_plan_purge(keyroll_t *keyroll); 274 275 /** 276 * Loads a plan from disk (all the steps). 277 * Loads KSK private keys if they are available. 278 */ 279 280 ya_result keyroll_plan_load(keyroll_t *keyroll); 281 282 /** 283 * Generates a plan using a DNSSEC policy. 284 */ 285 286 ya_result keyroll_plan_with_policy(keyroll_t *keyroll, s64 generate_from, s64 generate_until, const char* policy_name); 287 288 /** 289 * Generates a simple plan. 290 * Do not use this. 291 * Use the DNSSEC policy one instead. 292 */ 293 294 ya_result keyroll_plan(keyroll_t *keyroll, s64 generate_until); 295 296 /** 297 * Prints a step. 298 */ 299 300 void keyroll_step_print(keyroll_step_t *step); 301 302 /** 303 * Prints a plan. 304 */ 305 306 ya_result keyroll_print(keyroll_t *keyroll, output_stream *os); 307 308 /** 309 * Prints a plan to the given output stream in a JSON format. 310 */ 311 312 ya_result keyroll_print_json(keyroll_t *keyroll, output_stream *os); 313 314 /** 315 * Stores the plan on disk (several files, private KSK files, ...) 316 */ 317 318 ya_result keyroll_store(keyroll_t *keyroll); 319 320 ya_result keyroll_get_state_find_match_and_play(const keyroll_t *keyrollp, s64 now, const keyroll_step_t *current_step, const keyroll_step_t ** matched_stepp); 321 322 /** 323 * Enables or disables dryrun mode (no updates is ever sent) 324 */ 325 326 void keyroll_set_dryrun_mode(bool enabled); 327 328 u32 keyroll_deactivation_margin(u32 activate_epoch, u32 deactivate_epoch, u32 delete_epoch); 329