1 /* $NetBSD: kasp.h,v 1.5 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_KASP_H 17 #define DNS_KASP_H 1 18 19 /***** 20 ***** Module Info 21 *****/ 22 23 /*! \file dns/kasp.h 24 * \brief 25 * DNSSEC Key and Signing Policy (KASP) 26 * 27 * A "kasp" is a DNSSEC policy, that determines how a zone should be 28 * signed and maintained. 29 */ 30 31 #include <isc/lang.h> 32 #include <isc/magic.h> 33 #include <isc/mutex.h> 34 #include <isc/refcount.h> 35 36 #include <dns/types.h> 37 38 ISC_LANG_BEGINDECLS 39 40 /* Stores a KASP key */ 41 struct dns_kasp_key { 42 isc_mem_t *mctx; 43 44 /* Locked by themselves. */ 45 isc_refcount_t references; 46 47 /* Under owner's locking control. */ 48 ISC_LINK(struct dns_kasp_key) link; 49 50 /* Configuration */ 51 uint32_t lifetime; 52 uint8_t algorithm; 53 int length; 54 uint8_t role; 55 }; 56 57 struct dns_kasp_nsec3param { 58 uint8_t saltlen; 59 uint8_t algorithm; 60 uint8_t iterations; 61 bool optout; 62 }; 63 64 /* Stores a DNSSEC policy */ 65 struct dns_kasp { 66 unsigned int magic; 67 isc_mem_t *mctx; 68 char *name; 69 70 /* Internals. */ 71 isc_mutex_t lock; 72 bool frozen; 73 74 /* Locked by themselves. */ 75 isc_refcount_t references; 76 77 /* Under owner's locking control. */ 78 ISC_LINK(struct dns_kasp) link; 79 80 /* Configuration: signatures */ 81 uint32_t signatures_refresh; 82 uint32_t signatures_validity; 83 uint32_t signatures_validity_dnskey; 84 85 /* Configuration: Keys */ 86 dns_kasp_keylist_t keys; 87 dns_ttl_t dnskey_ttl; 88 89 /* Configuration: Denial of existence */ 90 bool nsec3; 91 dns_kasp_nsec3param_t nsec3param; 92 93 /* Configuration: Timings */ 94 uint32_t publish_safety; 95 uint32_t retire_safety; 96 uint32_t purge_keys; 97 98 /* Zone settings */ 99 dns_ttl_t zone_max_ttl; 100 uint32_t zone_propagation_delay; 101 102 /* Parent settings */ 103 dns_ttl_t parent_ds_ttl; 104 uint32_t parent_propagation_delay; 105 }; 106 107 #define DNS_KASP_MAGIC ISC_MAGIC('K', 'A', 'S', 'P') 108 #define DNS_KASP_VALID(kasp) ISC_MAGIC_VALID(kasp, DNS_KASP_MAGIC) 109 110 /* Defaults */ 111 #define DNS_KASP_SIG_REFRESH (86400 * 5) 112 #define DNS_KASP_SIG_VALIDITY (86400 * 14) 113 #define DNS_KASP_SIG_VALIDITY_DNSKEY (86400 * 14) 114 #define DNS_KASP_KEY_TTL (3600) 115 #define DNS_KASP_DS_TTL (86400) 116 #define DNS_KASP_PUBLISH_SAFETY (3600) 117 #define DNS_KASP_PURGE_KEYS (86400 * 90) 118 #define DNS_KASP_RETIRE_SAFETY (3600) 119 #define DNS_KASP_ZONE_MAXTTL (86400) 120 #define DNS_KASP_ZONE_PROPDELAY (300) 121 #define DNS_KASP_PARENT_PROPDELAY (3600) 122 123 /* Key roles */ 124 #define DNS_KASP_KEY_ROLE_KSK 0x01 125 #define DNS_KASP_KEY_ROLE_ZSK 0x02 126 127 isc_result_t 128 dns_kasp_create(isc_mem_t *mctx, const char *name, dns_kasp_t **kaspp); 129 /*%< 130 * Create a KASP. 131 * 132 * Requires: 133 * 134 *\li 'mctx' is a valid memory context. 135 * 136 *\li 'name' is a valid C string. 137 * 138 *\li kaspp != NULL && *kaspp == NULL 139 * 140 * Returns: 141 * 142 *\li #ISC_R_SUCCESS 143 *\li #ISC_R_NOMEMORY 144 * 145 *\li Other errors are possible. 146 */ 147 148 void 149 dns_kasp_attach(dns_kasp_t *source, dns_kasp_t **targetp); 150 /*%< 151 * Attach '*targetp' to 'source'. 152 * 153 * Requires: 154 * 155 *\li 'source' is a valid, frozen kasp. 156 * 157 *\li 'targetp' points to a NULL dns_kasp_t *. 158 * 159 * Ensures: 160 * 161 *\li *targetp is attached to source. 162 * 163 *\li While *targetp is attached, the kasp will not shut down. 164 */ 165 166 void 167 dns_kasp_detach(dns_kasp_t **kaspp); 168 /*%< 169 * Detach KASP. 170 * 171 * Requires: 172 * 173 *\li 'kaspp' points to a valid dns_kasp_t * 174 * 175 * Ensures: 176 * 177 *\li *kaspp is NULL. 178 */ 179 180 void 181 dns_kasp_freeze(dns_kasp_t *kasp); 182 /*%< 183 * Freeze kasp. No changes can be made to kasp configuration while frozen. 184 * 185 * Requires: 186 * 187 *\li 'kasp' is a valid, unfrozen kasp. 188 * 189 * Ensures: 190 * 191 *\li 'kasp' is frozen. 192 */ 193 194 void 195 dns_kasp_thaw(dns_kasp_t *kasp); 196 /*%< 197 * Thaw kasp. 198 * 199 * Requires: 200 * 201 *\li 'kasp' is a valid, frozen kasp. 202 * 203 * Ensures: 204 * 205 *\li 'kasp' is no longer frozen. 206 */ 207 208 const char * 209 dns_kasp_getname(dns_kasp_t *kasp); 210 /*%< 211 * Get kasp name. 212 * 213 * Requires: 214 * 215 *\li 'kasp' is a valid kasp. 216 * 217 * Returns: 218 * 219 *\li name of 'kasp'. 220 */ 221 222 uint32_t 223 dns_kasp_signdelay(dns_kasp_t *kasp); 224 /*%< 225 * Get the delay that is needed to ensure that all existing RRsets have been 226 * re-signed with a successor key. This is the signature validity minus the 227 * signature refresh time (that indicates how far before signature expiry an 228 * RRSIG should be refreshed). 229 * 230 * Requires: 231 * 232 *\li 'kasp' is a valid, frozen kasp. 233 * 234 * Returns: 235 * 236 *\li signature refresh interval. 237 */ 238 239 uint32_t 240 dns_kasp_sigrefresh(dns_kasp_t *kasp); 241 /*%< 242 * Get signature refresh interval. 243 * 244 * Requires: 245 * 246 *\li 'kasp' is a valid, frozen kasp. 247 * 248 * Returns: 249 * 250 *\li signature refresh interval. 251 */ 252 253 void 254 dns_kasp_setsigrefresh(dns_kasp_t *kasp, uint32_t value); 255 /*%< 256 * Set signature refresh interval. 257 * 258 * Requires: 259 * 260 *\li 'kasp' is a valid, thawed kasp. 261 */ 262 263 uint32_t 264 dns_kasp_sigvalidity(dns_kasp_t *kasp); 265 uint32_t 266 dns_kasp_sigvalidity_dnskey(dns_kasp_t *kasp); 267 /*%< 268 * Get signature validity. 269 * 270 * Requires: 271 * 272 *\li 'kasp' is a valid, frozen kasp. 273 * 274 * Returns: 275 * 276 *\li signature validity. 277 */ 278 279 void 280 dns_kasp_setsigvalidity(dns_kasp_t *kasp, uint32_t value); 281 void 282 dns_kasp_setsigvalidity_dnskey(dns_kasp_t *kasp, uint32_t value); 283 /*%< 284 * Set signature validity. 285 * 286 * Requires: 287 * 288 *\li 'kasp' is a valid, thawed kasp. 289 */ 290 291 dns_ttl_t 292 dns_kasp_dnskeyttl(dns_kasp_t *kasp); 293 /*%< 294 * Get DNSKEY TTL. 295 * 296 * Requires: 297 * 298 *\li 'kasp' is a valid, frozen kasp. 299 * 300 * Returns: 301 * 302 *\li DNSKEY TTL. 303 */ 304 305 void 306 dns_kasp_setdnskeyttl(dns_kasp_t *kasp, dns_ttl_t ttl); 307 /*%< 308 * Set DNSKEY TTL. 309 * 310 * Requires: 311 * 312 *\li 'kasp' is a valid, thawed kasp. 313 */ 314 315 uint32_t 316 dns_kasp_purgekeys(dns_kasp_t *kasp); 317 /*%< 318 * Get purge keys interval. 319 * 320 * Requires: 321 * 322 *\li 'kasp' is a valid, frozen kasp. 323 * 324 * Returns: 325 * 326 *\li Purge keys interval. 327 */ 328 329 void 330 dns_kasp_setpurgekeys(dns_kasp_t *kasp, uint32_t value); 331 /*%< 332 * Set purge keys interval. 333 * 334 * Requires: 335 * 336 *\li 'kasp' is a valid, thawed kasp. 337 */ 338 339 uint32_t 340 dns_kasp_publishsafety(dns_kasp_t *kasp); 341 /*%< 342 * Get publish safety interval. 343 * 344 * Requires: 345 * 346 *\li 'kasp' is a valid, frozen kasp. 347 * 348 * Returns: 349 * 350 *\li Publish safety interval. 351 */ 352 353 void 354 dns_kasp_setpublishsafety(dns_kasp_t *kasp, uint32_t value); 355 /*%< 356 * Set publish safety interval. 357 * 358 * Requires: 359 * 360 *\li 'kasp' is a valid, thawed kasp. 361 */ 362 363 uint32_t 364 dns_kasp_retiresafety(dns_kasp_t *kasp); 365 /*%< 366 * Get retire safety interval. 367 * 368 * Requires: 369 * 370 *\li 'kasp' is a valid, frozen kasp. 371 * 372 * Returns: 373 * 374 *\li Retire safety interval. 375 */ 376 377 void 378 dns_kasp_setretiresafety(dns_kasp_t *kasp, uint32_t value); 379 /*%< 380 * Set retire safety interval. 381 * 382 * Requires: 383 * 384 *\li 'kasp' is a valid, thawed kasp. 385 */ 386 387 dns_ttl_t 388 dns_kasp_zonemaxttl(dns_kasp_t *kasp); 389 /*%< 390 * Get maximum zone TTL. 391 * 392 * Requires: 393 * 394 *\li 'kasp' is a valid, frozen kasp. 395 * 396 * Returns: 397 * 398 *\li Maximum zone TTL. 399 */ 400 401 void 402 dns_kasp_setzonemaxttl(dns_kasp_t *kasp, dns_ttl_t ttl); 403 /*%< 404 * Set maximum zone TTL. 405 * 406 * Requires: 407 * 408 *\li 'kasp' is a valid, thawed kasp. 409 */ 410 411 uint32_t 412 dns_kasp_zonepropagationdelay(dns_kasp_t *kasp); 413 /*%< 414 * Get zone propagation delay. 415 * 416 * Requires: 417 * 418 *\li 'kasp' is a valid, frozen kasp. 419 * 420 * Returns: 421 * 422 *\li Zone propagation delay. 423 */ 424 425 void 426 dns_kasp_setzonepropagationdelay(dns_kasp_t *kasp, uint32_t value); 427 /*%< 428 * Set zone propagation delay. 429 * 430 * Requires: 431 * 432 *\li 'kasp' is a valid, thawed kasp. 433 */ 434 435 dns_ttl_t 436 dns_kasp_dsttl(dns_kasp_t *kasp); 437 /*%< 438 * Get DS TTL (should match that of the parent DS record). 439 * 440 * Requires: 441 * 442 *\li 'kasp' is a valid, frozen kasp. 443 * 444 * Returns: 445 * 446 *\li Expected parent DS TTL. 447 */ 448 449 void 450 dns_kasp_setdsttl(dns_kasp_t *kasp, dns_ttl_t ttl); 451 /*%< 452 * Set DS TTL. 453 * 454 * Requires: 455 * 456 *\li 'kasp' is a valid, thawed kasp. 457 */ 458 459 uint32_t 460 dns_kasp_parentpropagationdelay(dns_kasp_t *kasp); 461 /*%< 462 * Get parent zone propagation delay. 463 * 464 * Requires: 465 * 466 *\li 'kasp' is a valid, frozen kasp. 467 * 468 * Returns: 469 * 470 *\li Parent zone propagation delay. 471 */ 472 473 void 474 dns_kasp_setparentpropagationdelay(dns_kasp_t *kasp, uint32_t value); 475 /*%< 476 * Set parent propagation delay. 477 * 478 * Requires: 479 * 480 *\li 'kasp' is a valid, thawed kasp. 481 */ 482 483 isc_result_t 484 dns_kasplist_find(dns_kasplist_t *list, const char *name, dns_kasp_t **kaspp); 485 /*%< 486 * Search for a kasp with name 'name' in 'list'. 487 * If found, '*kaspp' is (strongly) attached to it. 488 * 489 * Requires: 490 * 491 *\li 'kaspp' points to a NULL dns_kasp_t *. 492 * 493 * Returns: 494 * 495 *\li #ISC_R_SUCCESS A matching kasp was found. 496 *\li #ISC_R_NOTFOUND No matching kasp was found. 497 */ 498 499 dns_kasp_keylist_t 500 dns_kasp_keys(dns_kasp_t *kasp); 501 /*%< 502 * Get the list of kasp keys. 503 * 504 * Requires: 505 * 506 *\li 'kasp' is a valid, frozen kasp. 507 * 508 * Returns: 509 * 510 *\li #ISC_R_SUCCESS 511 *\li #ISC_R_NOMEMORY 512 * 513 *\li Other errors are possible. 514 */ 515 516 bool 517 dns_kasp_keylist_empty(dns_kasp_t *kasp); 518 /*%< 519 * Check if the keylist is empty. 520 * 521 * Requires: 522 * 523 *\li 'kasp' is a valid kasp. 524 * 525 * Returns: 526 * 527 *\li true if the keylist is empty, false otherwise. 528 */ 529 530 void 531 dns_kasp_addkey(dns_kasp_t *kasp, dns_kasp_key_t *key); 532 /*%< 533 * Add a key. 534 * 535 * Requires: 536 * 537 *\li 'kasp' is a valid, thawed kasp. 538 *\li 'key' is not NULL. 539 */ 540 541 isc_result_t 542 dns_kasp_key_create(dns_kasp_t *kasp, dns_kasp_key_t **keyp); 543 /*%< 544 * Create a key inside a KASP. 545 * 546 * Requires: 547 * 548 *\li 'kasp' is a valid kasp. 549 * 550 *\li keyp != NULL && *keyp == NULL 551 * 552 * Returns: 553 * 554 *\li #ISC_R_SUCCESS 555 *\li #ISC_R_NOMEMORY 556 * 557 *\li Other errors are possible. 558 */ 559 560 void 561 dns_kasp_key_destroy(dns_kasp_key_t *key); 562 /*%< 563 * Destroy a KASP key. 564 * 565 * Requires: 566 * 567 *\li key != NULL 568 */ 569 570 uint32_t 571 dns_kasp_key_algorithm(dns_kasp_key_t *key); 572 /*%< 573 * Get the key algorithm. 574 * 575 * Requires: 576 * 577 *\li key != NULL 578 * 579 * Returns: 580 * 581 *\li Key algorithm. 582 */ 583 584 unsigned int 585 dns_kasp_key_size(dns_kasp_key_t *key); 586 /*%< 587 * Get the key size. 588 * 589 * Requires: 590 * 591 *\li key != NULL 592 * 593 * Returns: 594 * 595 *\li Configured key size, or default key size for key algorithm if no size 596 * configured. 597 */ 598 599 uint32_t 600 dns_kasp_key_lifetime(dns_kasp_key_t *key); 601 /*%< 602 * The lifetime of this key (how long may this key be active?) 603 * 604 * Requires: 605 * 606 *\li key != NULL 607 * 608 * Returns: 609 * 610 *\li Lifetime of key. 611 * 612 */ 613 614 bool 615 dns_kasp_key_ksk(dns_kasp_key_t *key); 616 /*%< 617 * Does this key act as a KSK? 618 * 619 * Requires: 620 * 621 *\li key != NULL 622 * 623 * Returns: 624 * 625 *\li True, if the key role has DNS_KASP_KEY_ROLE_KSK set. 626 *\li False, otherwise. 627 * 628 */ 629 630 bool 631 dns_kasp_key_zsk(dns_kasp_key_t *key); 632 /*%< 633 * Does this key act as a ZSK? 634 * 635 * Requires: 636 * 637 *\li key != NULL 638 * 639 * Returns: 640 * 641 *\li True, if the key role has DNS_KASP_KEY_ROLE_ZSK set. 642 *\li False, otherwise. 643 * 644 */ 645 646 bool 647 dns_kasp_nsec3(dns_kasp_t *kasp); 648 /*%< 649 * Return true if NSEC3 chain should be used. 650 * 651 * Requires: 652 * 653 *\li 'kasp' is a valid, frozen kasp. 654 * 655 */ 656 657 uint8_t 658 dns_kasp_nsec3iter(dns_kasp_t *kasp); 659 /*%< 660 * The number of NSEC3 iterations to use. 661 * 662 * Requires: 663 * 664 *\li 'kasp' is a valid, frozen kasp. 665 *\li 'kasp->nsec3' is true. 666 * 667 */ 668 669 uint8_t 670 dns_kasp_nsec3flags(dns_kasp_t *kasp); 671 /*%< 672 * The NSEC3 flags field value. 673 * 674 * Requires: 675 * 676 *\li 'kasp' is a valid, frozen kasp. 677 *\li 'kasp->nsec3' is true. 678 * 679 */ 680 681 uint8_t 682 dns_kasp_nsec3saltlen(dns_kasp_t *kasp); 683 /*%< 684 * The NSEC3 salt length. 685 * 686 * Requires: 687 * 688 *\li 'kasp' is a valid, frozen kasp. 689 *\li 'kasp->nsec3' is true. 690 * 691 */ 692 693 void 694 dns_kasp_setnsec3(dns_kasp_t *kasp, bool nsec3); 695 /*%< 696 * Set to use NSEC3 if 'nsec3' is 'true', otherwise policy will use NSEC. 697 * 698 * Requires: 699 * 700 *\li 'kasp' is a valid, unfrozen kasp. 701 * 702 */ 703 704 void 705 dns_kasp_setnsec3param(dns_kasp_t *kasp, uint8_t iter, bool optout, 706 uint8_t saltlen); 707 /*%< 708 * Set the desired NSEC3 parameters. 709 * 710 * Requires: 711 * 712 *\li 'kasp' is a valid, unfrozen kasp. 713 *\li 'kasp->nsec3' is true. 714 * 715 */ 716 717 ISC_LANG_ENDDECLS 718 719 #endif /* DNS_KASP_H */ 720