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