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