1.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") 2.. 3.. SPDX-License-Identifier: MPL-2.0 4.. 5.. This Source Code Form is subject to the terms of the Mozilla Public 6.. License, v. 2.0. If a copy of the MPL was not distributed with this 7.. file, you can obtain one at https://mozilla.org/MPL/2.0/. 8.. 9.. See the COPYRIGHT file distributed with this work for additional 10.. information regarding copyright ownership. 11 12.. _dnssec_recipes: 13 14Recipes 15------- 16 17This chapter provides step-by-step "recipes" for some common 18DNSSEC configurations. 19 20.. _recipes_inline_signing: 21 22DNSSEC Signing 23~~~~~~~~~~~~~~ 24 25There are two recipes here: the first shows an example using DNSSEC 26signing on the primary server, which has been covered in this 27guide; the second shows how to setup a "bump in the 28wire" between a hidden primary and the secondary servers to seamlessly 29sign the zone "on the fly." 30 31.. _recipes_inline_signing_primary: 32 33Primary Server DNSSEC Signing 34^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 35 36In this recipe, our servers are illustrated as shown in 37:ref:`dnssec-signing-1`: we have a primary server 38(192.168.1.1) and three secondary servers (192.168.1.2, 192.168.1.3, and 39192.168.1.4) that receive zone transfers. To get the zone 40signed, we need to reconfigure the primary server. Once reconfigured, a 41signed version of the zone is generated on the fly; 42zone transfers take care of synchronizing the signed zone data 43to all secondary name servers, without configuration or software changes 44on them. 45 46.. _dnssec-signing-1: 47 48.. figure:: ../dnssec-guide/img/dnssec-inline-signing-1.png 49 :alt: DNSSEC Signing Recipe #1 50 :width: 80.0% 51 52 DNSSEC Signing Recipe #1 53 54Using the method described in 55:ref:`easy_start_guide_for_authoritative_servers`, we just need to 56add a :any:`dnssec-policy` statement to the relevant zone clause. This is 57what the :iscman:`named.conf` zone statement looks like on the primary server, 192.168.1.1: 58 59:: 60 61 zone "example.com" IN { 62 type primary; 63 file "db/example.com.db"; 64 key-directory "keys/example.com"; 65 dnssec-policy default; 66 allow-transfer { 192.168.1.2; 192.168.1.3; 192.168.1.4; }; 67 }; 68 69We have chosen to use the default policy, storing the keys generated for 70the zone in the directory ``keys/example.com``. To use a 71custom policy, define the policy in the configuration 72file and select it in the zone statement (as described in 73:ref:`signing_custom_policy`). 74 75On the secondary servers, :iscman:`named.conf` does not need to be updated, 76and it looks like this: 77 78:: 79 80 zone "example.com" IN { 81 type secondary; 82 file "db/example.com.db"; 83 primaries { 192.168.1.1; }; 84 }; 85 86In fact, the secondary servers do not even need to be running BIND; they 87can run any DNS product that supports DNSSEC. 88 89.. _recipes_inline_signing_bump_in_the_wire: 90 91"Bump in the Wire" Signing 92^^^^^^^^^^^^^^^^^^^^^^^^^^ 93 94In this recipe, we take advantage of the power of automated signing 95by placing an additional name server (192.168.1.5) between the hidden 96primary (192.168.1.1) and the DNS secondaries (192.168.1.2, 192.168.1.3, 97and 192.168.1.4). The additional name server, 192.168.1.5, acts as a "bump 98in the wire," taking an unsigned zone from the hidden primary, 99and sending out signed data on the other end to the secondary name 100servers. The steps described in this recipe may be used as part of a 101DNSSEC deployment strategy, since it requires only minimal changes made to 102the existing hidden DNS primary and DNS secondaries. 103 104.. _dnssec-signing-2: 105 106.. figure:: ../dnssec-guide/img/dnssec-inline-signing-2.png 107 :alt: DNSSEC Signing Recipe #2 108 :width: 100.0% 109 110 DNSSEC Signing Recipe #2 111 112It is important to remember that 192.168.1.1 in this case is a hidden 113primary not exposed to the world, and it must not be listed in the NS RRset. 114Otherwise the world will get conflicting answers: unsigned answers from 115the hidden primary and signed answers from the other name servers. 116 117The only configuration change needed on the hidden primary, 192.168.1.1, 118is to make sure it allows our middle box to perform a zone transfer: 119 120:: 121 122 zone "example.com" IN { 123 ... 124 allow-transfer { 192.168.1.5; }; 125 ... 126 }; 127 128On the middle box, 192.168.1.5, all the tasks described in 129:ref:`easy_start_guide_for_authoritative_servers` still need to be 130performed, such as generating key pairs and uploading information to 131the parent zone. This server is configured as secondary to the hidden 132primary 192.168.1.1 to receive the unsigned data; then, using keys 133accessible to this middle box, to sign data on the fly; and finally, to send out the 134signed data via zone transfer to the other three DNS secondaries. Its 135:iscman:`named.conf` zone statement looks like this: 136 137:: 138 139 zone example.com { 140 type secondary; 141 primaries { 192.168.1.1; }; 142 file "db/example.com.db"; 143 key-directory "keys/example.com"; 144 dnssec-policy default; 145 allow-transfer { 192.168.1.2; 192.168.1.3; 192.168.1.4; }; 146 }; 147 148(As before, the default policy has been selected here. See 149:ref:`signing_custom_policy` for instructions on how to define 150and use a custom policy.) 151 152Finally, on the three secondary servers, the configuration should be updated 153to receive a zone transfer from 192.168.1.5 (the middle box) instead of 154from 192.168.1.1 (the hidden primary). If using BIND, the :iscman:`named.conf` file looks 155like this: 156 157:: 158 159 zone "example.com" IN { 160 type secondary; 161 file "db/example.com.db"; 162 primaries { 192.168.1.5; }; # this was 192.168.1.1 before! 163 }; 164 165.. _recipes_rollovers: 166 167Rollovers 168~~~~~~~~~ 169 170If you are signing your zone using a :any:`dnssec-policy` statement, this 171section is not really relevant to you. In the policy statement, you set how long 172you want your keys to be valid for, the time 173taken for information to propagate through your zone, the time it takes 174for your parent zone to register a new DS record, etc., and that's more 175or less it. :iscman:`named` implements everything for you automatically, apart from 176uploading the new DS records to your parent zone - which is covered in 177:ref:`signing_easy_start_upload_to_parent_zone`. (Some 178screenshots from a session where a KSK is uploaded to the parent zone 179are presented here for convenience.) However, these recipes may be useful 180in describing what happens 181through the rollover process and what you should be monitoring. 182 183.. _recipes_zsk_rollover: 184 185ZSK Rollover 186^^^^^^^^^^^^ 187 188This recipe covers how to perform a ZSK rollover using what is known as 189the Pre-Publication method. For other ZSK rolling methods, please see 190:ref:`zsk_rollover_methods` in :ref:`dnssec_advanced_discussions`. 191 192Below is a sample timeline for a ZSK rollover to occur on January 1, 2021: 193 1941. December 1, 2020 (one month before rollover) 195 196 - Generate new ZSK 197 198 - Add DNSKEY for new ZSK to zone 199 2002. January 1, 2021 (day of rollover) 201 202 - New ZSK used to replace RRSIGs for the bulk of the zone 203 2043. February 1, 2021 (one month after rollover) 205 206 - Remove old ZSK DNSKEY RRset from zone 207 208 - DNSKEY signatures made with KSK are changed 209 210The current active ZSK has the ID 17694 in the example below. For more 211information on key management and rollovers, please see 212:ref:`advanced_discussions_key_management`. 213 214One Month Before ZSK Rollover 215+++++++++++++++++++++++++++++ 216 217On December 1, 2020, a month before the example rollover, you (as administrator) 218should change the parameters on the current key (17694). Set it to become inactive on 219January 1, 2021 and be deleted from the zone on February 1, 2021; also, 220generate a successor key (51623): 221 222:: 223 224 # cd /etc/bind/keys/example.com/ 225 # dnssec-settime -I 20210101 -D 20210201 Kexample.com.+008+17694 226 ./Kexample.com.+008+17694.key/GoDaddy 227 228 ./Kexample.com.+008+17694.private 229 # dnssec-keygen -S Kexample.com.+008+17694 230 Generating key pair..++++++ ...........++++++ 231 Kexample.com.+008+51623 232 233The first command gets us into the key directory 234``/etc/bind/keys/example.com/``, where keys for ``example.com`` are 235stored. 236 237The second, :iscman:`dnssec-settime`, sets an inactive (:option:`-I <dnssec-settime -I>`) date of January 1, 2382021, and a deletion (:option:`-D <dnssec-settime -D>`) date of February 1, 2021, for the current ZSK 239(``Kexample.com.+008+17694``). 240 241The third command, :iscman:`dnssec-keygen`, creates a successor key, using 242the exact same parameters (algorithms, key sizes, etc.) as the current 243ZSK. The new ZSK created in our example is ``Kexample.com.+008+51623``. 244 245Make sure the successor keys are readable by :iscman:`named`. 246 247:iscman:`named`'s logging messages indicate when the next 248key checking event is scheduled to occur, the frequency of which can be 249controlled by :any:`dnssec-loadkeys-interval`. The log message looks like 250this: 251 252:: 253 254 zone example.com/IN (signed): next key event: 01-Dec-2020 00:13:05.385 255 256And you can check the publish date of the key by looking at the key 257file: 258 259:: 260 261 # cd /etc/bind/keys/example.com 262 # cat Kexample.com.+008+51623.key 263 ; This is a zone-signing key, keyid 11623, for example.com. 264 ; Created: 20201130160024 (Mon Dec 1 00:00:24 2020) 265 ; Publish: 20201202000000 (Fri Dec 2 08:00:00 2020) 266 ; Activate: 20210101000000 (Sun Jan 1 08:00:00 2021) 267 ... 268 269Since the publish date is set to the morning of December 2, and our example 270scenario takes place on December 1, the next 271morning you will notice that your zone has gained a new DNSKEY record, 272but the new ZSK is not yet being used to generate signatures. Below is 273the abbreviated output - with shortened DNSKEY and RRSIG - when querying the 274authoritative name server, 192.168.1.13: 275 276:: 277 278 $ dig @192.168.1.13 example.com. DNSKEY +dnssec +multiline 279 280 ... 281 ;; ANSWER SECTION: 282 example.com. 600 IN DNSKEY 257 3 8 ( 283 AwEAAcWDps...lM3NRn/G/R 284 ) ; KSK; alg = RSASHA256; key id = 6817 285 example.com. 600 IN DNSKEY 256 3 8 ( 286 AwEAAbi6Vo...qBW5+iAqNz 287 ) ; ZSK; alg = RSASHA256; key id = 51623 288 example.com. 600 IN DNSKEY 256 3 8 ( 289 AwEAAcjGaU...0rzuu55If5 290 ) ; ZSK; alg = RSASHA256; key id = 17694 291 example.com. 600 IN RRSIG DNSKEY 8 2 600 ( 292 20210101000000 20201201230000 6817 example.com. 293 LAiaJM26T7...FU9syh/TQ= ) 294 example.com. 600 IN RRSIG DNSKEY 8 2 600 ( 295 20210101000000 20201201230000 17694 example.com. 296 HK4EBbbOpj...n5V6nvAkI= ) 297 ... 298 299For good measure, let's take a look at the SOA record and its 300signature for this zone. Notice the RRSIG is signed by the current ZSK, 30117694. This will come in handy later when you want to verify whether 302the new ZSK is in effect: 303 304:: 305 306 $ dig @192.168.1.13 example.com. SOA +dnssec +multiline 307 308 ... 309 ;; ANSWER SECTION: 310 example.com. 600 IN SOA ns1.example.com. admin.example.com. ( 311 2020120102 ; serial 312 1800 ; refresh (30 minutes) 313 900 ; retry (15 minutes) 314 2419200 ; expire (4 weeks) 315 300 ; minimum (5 minutes) 316 ) 317 example.com. 600 IN RRSIG SOA 8 2 600 ( 318 20201230160109 20201130150109 17694 example.com. 319 YUTC8rFULaWbW+nAHzbfGwNqzARHevpryzRIJMvZBYPo 320 NAeejNk9saNAoCYKWxGJ0YBc2k+r5fYq1Mg4ll2JkBF5 321 buAsAYLw8vEOIxVpXwlArY+oSp9T1w2wfTZ0vhVIxaYX 322 6dkcz4I3wbDx2xmG0yngtA6A8lAchERx2EGy0RM= ) 323 324These are all the manual tasks you need to perform for a ZSK rollover. 325If you have followed the configuration examples in this guide of using 326:any:`inline-signing` and :any:`dnssec-policy`, everything else is automated for 327you by BIND. 328 329Day of ZSK Rollover 330+++++++++++++++++++ 331 332On the actual day of the rollover, although there is technically nothing 333for you to do, you should still keep an eye on the zone to make sure new 334signatures are being generated by the new ZSK (51623 in this example). 335The easiest way is to query the authoritative name server 192.168.1.13 336for the SOA record as you did a month ago: 337 338:: 339 340 $ dig @192.168.1.13 example.com. SOA +dnssec +multiline 341 342 ... 343 ;; ANSWER SECTION: 344 example.com. 600 IN SOA ns1.example.com. admin.example.com. ( 345 2020112011 ; serial 346 1800 ; refresh (30 minutes) 347 900 ; retry (15 minutes) 348 2419200 ; expire (4 weeks) 349 300 ; minimum (5 minutes) 350 ) 351 example.com. 600 IN RRSIG SOA 8 2 600 ( 352 20210131000000 20201231230000 51623 example.com. 353 J4RMNpJPOmMidElyBugJp0RLqXoNqfvo/2AT6yAAvx9X 354 zZRL1cuhkRcyCSLZ9Z+zZ2y4u2lvQGrNiondaKdQCor7 355 uTqH5WCPoqalOCBjqU7c7vlAM27O9RD11nzPNpVQ7xPs 356 y5nkGqf83OXTK26IfnjU1jqiUKSzg6QR7+XpLk0= ) 357 ... 358 359As you can see, the signature generated by the old ZSK (17694) has 360disappeared, replaced by a new signature generated from the new ZSK 361(51623). 362 363.. note:: 364 365 Not all signatures will disappear magically on the same day; 366 it depends on when each one was generated. In the worst-case scenario, 367 a new signature could have been signed by the old ZSK (17694) moments 368 before it was deactivated, meaning that the signature could live for almost 369 30 more days, until just before February 1. 370 371 This is why it is important to keep the old ZSK in the 372 zone and not delete it right away. 373 374One Month After ZSK Rollover 375++++++++++++++++++++++++++++ 376 377Again, technically there is nothing you need to do on this day, 378but it doesn't hurt to verify that the old ZSK (17694) is now completely 379gone from your zone. :iscman:`named` will not touch 380``Kexample.com.+008+17694.private`` and ``Kexample.com.+008+17694.key`` 381on your file system. Running the same :iscman:`dig` command for DNSKEY should 382suffice: 383 384:: 385 386 $ dig @192.168.1.13 example.com. DNSKEY +multiline +dnssec 387 388 ... 389 ;; ANSWER SECTION: 390 example.com. 600 IN DNSKEY 257 3 8 ( 391 AwEAAcWDps...lM3NRn/G/R 392 ) ; KSK; alg = RSASHA256; key id = 6817 393 example.com. 600 IN DNSKEY 256 3 8 ( 394 AwEAAdeCGr...1DnEfX+Xzn 395 ) ; ZSK; alg = RSASHA256; key id = 51623 396 example.com. 600 IN RRSIG DNSKEY 8 2 600 ( 397 20170203000000 20170102230000 6817 example.com. 398 KHY8P0zE21...Y3szrmjAM= ) 399 example.com. 600 IN RRSIG DNSKEY 8 2 600 ( 400 20170203000000 20170102230000 51623 example.com. 401 G2g3crN17h...Oe4gw6gH8= ) 402 ... 403 404Congratulations, the ZSK rollover is complete! As for the actual key 405files (the files ending in ``.key`` and ``.private``), they may be deleted at this 406point, but they do not have to be. 407 408.. _recipes_ksk_rollover: 409 410KSK Rollover 411^^^^^^^^^^^^ 412 413This recipe describes how to perform KSK rollover using the Double-DS 414method. For other KSK rolling methods, please see 415:ref:`ksk_rollover_methods` in 416:ref:`dnssec_advanced_discussions`. The registrar used in this 417recipe is `GoDaddy <https://www.godaddy.com>`__. Also for this recipe, 418we are keeping the number of DS records down to just one per active set 419using just SHA-1, for the sake of better clarity, although in practice 420most zone operators choose to upload two DS records as shown in 421:ref:`working_with_parent_zone`. For more information on key 422management and rollovers, 423please see :ref:`advanced_discussions_key_management`. 424 425Below is a sample timeline for a KSK rollover to occur on January 1, 2021: 426 4271. December 1, 2020 (one month before rollover) 428 429 - Change timer on the current KSK 430 431 - Generate new KSK and DS records 432 433 - Add DNSKEY for the new KSK to zone 434 435 - Upload new DS records to parent zone 436 4372. January 1, 2021 (day of rollover) 438 439 - Use the new KSK to sign all DNSKEY RRsets, which generates new 440 RRSIGs 441 442 - Add new RRSIGs to the zone 443 444 - Remove RRSIG for the old ZSK from zone 445 446 - Start using the new KSK to sign DNSKEY 447 4483. February 1, 2021 (one month after rollover) 449 450 - Remove the old KSK DNSKEY from zone 451 452 - Remove old DS records from parent zone 453 454The current active KSK has the ID 24828, and this is the DS record that 455has already been published by the parent zone: 456 457:: 458 459 # dnssec-dsfromkey -a SHA-1 Kexample.com.+007+24828.key 460 example.com. IN DS 24828 7 1 D4A33E8DD550A9567B4C4971A34AD6C4B80A6AD3 461 462.. _one_month_before_ksk_rollover: 463 464One Month Before KSK Rollover 465+++++++++++++++++++++++++++++ 466 467On December 1, 2020, a month before the planned rollover, you (as 468administrator) should 469change the parameters on the current key. Set it to become inactive on January 4701, 2021, and be deleted from the zone on February 1st, 2021; 471also generate a successor key (23550). Finally, generate a new 472DS record based on the new key, 23550: 473 474:: 475 476 # cd /etc/bind/keys/example.com/ 477 # dnssec-settime -I 20210101 -D 20210201 Kexample.com.+007+24828 478 ./Kexample.com.+007+24848.key 479 ./Kexample.com.+007+24848.private 480 # dnssec-keygen -S Kexample.com.+007+24848 481 Generating key pair.......................................................................................++ ...................................++ 482 Kexample.com.+007+23550 483 # dnssec-dsfromkey -a SHA-1 Kexample.com.+007+23550.key 484 example.com. IN DS 23550 7 1 54FCF030AA1C79C0088FDEC1BD1C37DAA2E70DFB 485 486The first command gets us into the key directory 487``/etc/bind/keys/example.com/``, where keys for ``example.com`` are 488stored. 489 490The second, :iscman:`dnssec-settime`, sets an inactive (:option:`-I <dnssec-settime -I>`) date of January 1, 4912021, and a deletion (:option:`-D <dnssec-settime -D>`) date of February 1, 2021 for the current KSK 492(``Kexample.com.+007+24848``). 493 494The third command, :iscman:`dnssec-keygen`, creates a successor key, using 495the exact same parameters (algorithms, key sizes, etc.) as the current 496KSK. The new key pair created in our example is ``Kexample.com.+007+23550``. 497 498The fourth and final command, :iscman:`dnssec-dsfromkey`, creates a DS record 499from the new KSK (23550), using SHA-1 as the digest type. Again, in 500practice most people generate two DS records for both supported digest 501types (SHA-1 and SHA-256), but for our example here we are only using 502one to keep the output small and hopefully clearer. 503 504Make sure the successor keys are readable by :iscman:`named`. 505 506The :any:`syslog` message indicates when the next key 507checking event is. The log message looks like this: 508 509:: 510 511 zone example.com/IN (signed): next key event: 01-Dec-2020 00:13:05.385 512 513You can check the publish date of the key by looking at the key 514file: 515 516:: 517 518 # cd /etc/bind/keys/example.com 519 # cat Kexample.com.+007+23550.key 520 ; This is a key-signing key, keyid 23550, for example.com. 521 ; Created: 20201130160024 (Thu Dec 1 00:00:24 2020) 522 ; Publish: 20201202000000 (Fri Dec 2 08:00:00 2020) 523 ; Activate: 20210101000000 (Sun Jan 1 08:00:00 2021) 524 ... 525 526Since the publish date is set to the morning of December 2, and our example 527scenario takes place on December 1, the next 528morning you will notice that your zone has gained a new DNSKEY record 529based on your new KSK, but with no corresponding RRSIG yet. Below is the 530abbreviated output - with shortened DNSKEY and RRSIG - when querying the 531authoritative name server, 192.168.1.13: 532 533:: 534 535 $ dig @192.168.1.13 example.com. DNSKEY +dnssec +multiline 536 537 ... 538 ;; ANSWER SECTION: 539 example.com. 300 IN DNSKEY 256 3 7 ( 540 AwEAAdYqAc...TiSlrma6Ef 541 ) ; ZSK; alg = NSEC3RSASHA1; key id = 29747 542 example.com. 300 IN DNSKEY 257 3 7 ( 543 AwEAAeTJ+w...O+Zy9j0m63 544 ) ; KSK; alg = NSEC3RSASHA1; key id = 24828 545 example.com. 300 IN DNSKEY 257 3 7 ( 546 AwEAAc1BQN...Wdc0qoH21H 547 ) ; KSK; alg = NSEC3RSASHA1; key id = 23550 548 example.com. 300 IN RRSIG DNSKEY 7 2 300 ( 549 20201206125617 20201107115617 24828 example.com. 550 4y1iPVJOrK...aC3iF9vgc= ) 551 example.com. 300 IN RRSIG DNSKEY 7 2 300 ( 552 20201206125617 20201107115617 29747 example.com. 553 g/gfmPjr+y...rt/S/xjPo= ) 554 555 ... 556 557Anytime after generating the DS record, you can upload it; 558it is not necessary to wait for the DNSKEY to be published in your zone, 559since this new KSK is not active yet. You can do it 560immediately after the new DS record has been generated on December 1, 561or you can wait until the next day after you have verified that the 562new DNSKEY record is added to the zone. Below are some screenshots from 563GoDaddy's web-based interface, used to add a new DS record. 564[#godaddy_iface_note]_ 565 5661. After logging in, click the green "Launch" button next to the domain 567 name you want to manage. 568 569 .. _add-ds-1: 570 571 .. figure:: ../dnssec-guide/img/add-ds-1.png 572 :alt: Upload DS Record Step #1 573 :width: 70.0% 574 575 Upload DS Record Step #1 576 5772. Scroll down to the "DS Records" section and click "Manage." 578 579 .. _add-ds-2: 580 581 .. figure:: ../dnssec-guide/img/add-ds-2.png 582 :alt: Upload DS Record Step #2 583 :width: 40.0% 584 585 Upload DS Record Step #2 586 5873. A dialog appears, displaying the current key (24828). Click "Add DS 588 Record." 589 590 .. _add-ds-3: 591 592 .. figure:: ../dnssec-guide/img/add-ds-3.png 593 :alt: Upload DS Record Step #3 594 :width: 80.0% 595 596 Upload DS Record Step #3 597 5984. Enter the Key ID, algorithm, digest type, and the digest, then click 599 "Next." 600 601 .. _add-ds-4: 602 603 .. figure:: ../dnssec-guide/img/add-ds-4.png 604 :alt: Upload DS Record Step #4 605 :width: 80.0% 606 607 Upload DS Record Step #4 608 6095. Address any errors and click "Finish." 610 611 .. _add-ds-5: 612 613 .. figure:: ../dnssec-guide/img/add-ds-5.png 614 :alt: Upload DS Record Step #5 615 :width: 80.0% 616 617 Upload DS Record Step #5 618 6196. Both DS records are shown. Click "Save." 620 621 .. _add-ds-6: 622 623 .. figure:: ../dnssec-guide/img/add-ds-6.png 624 :alt: Upload DS Record Step #6 625 :width: 80.0% 626 627 Upload DS Record Step #6 628 629Finally, let's verify that the registrar has published the new DS 630record. This may take anywhere from a few minutes to a few days, 631depending on your parent zone. You can verify whether your 632parent zone has published the new DS record by querying for the DS 633record of your zone. In the example below, the Google public DNS server 6348.8.8.8 is used: 635 636:: 637 638 $ dig @8.8.8.8 example.com. DS 639 640 ... 641 ;; ANSWER SECTION: 642 example.com. 21552 IN DS 24828 7 1 D4A33E8DD550A9567B4C4971A34AD6C4B80A6AD3 643 example.com. 21552 IN DS 23550 7 1 54FCF030AA1C79C0088FDEC1BD1C37DAA2E70DFB 644 645You can also query your parent zone's authoritative name servers 646directly to see if these records have been published. DS records will 647not show up on your own authoritative zone, so you cannot query your own 648name servers for them. In this recipe, the parent zone is ``.com``, so 649querying a few of the ``.com`` name servers is another appropriate 650verification. 651 652Day of KSK Rollover 653+++++++++++++++++++ 654 655If you have followed the examples in this document, as described in 656:ref:`easy_start_guide_for_authoritative_servers`, there is 657technically nothing you need to do manually on the actual day of the 658rollover. However, you should still keep an eye on the zone to make sure 659new signature(s) are being generated by the new KSK (23550 in this 660example). The easiest way is to query the authoritative name server 661192.168.1.13 for the same DNSKEY and signatures, as you did a month 662ago: 663 664:: 665 666 $ dig @192.168.1.13 example.com. DNSKEY +dnssec +multiline 667 668 ... 669 ;; ANSWER SECTION: 670 example.com. 300 IN DNSKEY 256 3 7 ( 671 AwEAAdYqAc...TiSlrma6Ef 672 ) ; ZSK; alg = NSEC3RSASHA1; key id = 29747 673 example.com. 300 IN DNSKEY 257 3 7 ( 674 AwEAAeTJ+w...O+Zy9j0m63 675 ) ; KSK; alg = NSEC3RSASHA1; key id = 24828 676 example.com. 300 IN DNSKEY 257 3 7 ( 677 AwEAAc1BQN...Wdc0qoH21H 678 ) ; KSK; alg = NSEC3RSASHA1; key id = 23550 679 example.com. 300 IN RRSIG DNSKEY 7 2 300 ( 680 20210201074900 20210101064900 23550 mydnssecgood.org. 681 S6zTbBTfvU...Ib5eXkbtE= ) 682 example.com. 300 IN RRSIG DNSKEY 7 2 300 ( 683 20210105074900 20201206064900 29747 mydnssecgood.org. 684 VY5URQA2/d...OVKr1+KX8= ) 685 ... 686 687As you can see, the signature generated by the old KSK (24828) has 688disappeared, replaced by a new signature generated from the new KSK 689(23550). 690 691One Month After KSK Rollover 692++++++++++++++++++++++++++++ 693 694While the removal of the old DNSKEY from the zone should be automated by 695:iscman:`named`, the removal of the DS record is manual. You should make sure 696the old DNSKEY record is gone from your zone first, by querying for the 697DNSKEY records of the zone; this time we expect not to see 698the key with an ID of 24828: 699 700:: 701 702 $ dig @192.168.1.13 example.com. DNSKEY +dnssec +multiline 703 704 ... 705 ;; ANSWER SECTION: 706 example.com. 300 IN DNSKEY 256 3 7 ( 707 AwEAAdYqAc...TiSlrma6Ef 708 ) ; ZSK; alg = NSEC3RSASHA1; key id = 29747 709 example.com. 300 IN DNSKEY 257 3 7 ( 710 AwEAAc1BQN...Wdc0qoH21H 711 ) ; KSK; alg = NSEC3RSASHA1; key id = 23550 712 example.com. 300 IN RRSIG DNSKEY 7 2 300 ( 713 20210208000000 20210105230000 23550 mydnssecgood.org. 714 Qw9Em3dDok...bNCS7KISw= ) 715 example.com. 300 IN RRSIG DNSKEY 7 2 300 ( 716 20210208000000 20210105230000 29747 mydnssecgood.org. 717 OuelpIlpY9...XfsKupQgc= ) 718 ... 719 720Since the key with the ID 24828 is gone, you can now remove the old DS 721record for that key from our parent zone. 722Be careful to remove the correct DS record. If you accidentally remove 723the new DS record(s) with key ID 23550, it could lead to a problem called 724"security lameness," as discussed in 725:ref:`troubleshooting_security_lameness`, and may cause users to be unable 726to resolve any names in the zone. 727 7281. After logging in (again, GoDaddy.com in our example) and launching the domain, scroll down to the "DS 729 Records" section and click Manage. 730 731 .. _remove-ds-1: 732 733 .. figure:: ../dnssec-guide/img/remove-ds-1.png 734 :alt: Remove DS Record Step #1 735 :width: 40.0% 736 737 Remove DS Record Step #1 738 7392. A dialog appears, displaying both keys (24828 and 23550). Use the far 740 right-hand X button to remove key 24828. 741 742 .. _remove-ds-2: 743 744 .. figure:: ../dnssec-guide/img/remove-ds-2.png 745 :alt: Remove DS Record Step #2 746 :width: 80.0% 747 748 Remove DS Record Step #2 749 7503. Key 24828 now appears crossed out; click "Save" to complete the 751 removal. 752 753 .. _remove-ds-3: 754 755 .. figure:: ../dnssec-guide/img/remove-ds-3.png 756 :alt: Remove DS Record Step #3 757 :width: 80.0% 758 759 Remove DS Record Step #3 760 761Congratulations, the KSK rollover is complete! As for the actual key 762files (ending in ``.key`` and ``.private``), they may be deleted at this 763point, but they do not have to be. 764 765.. [#godaddy_iface_note] 766 The screenshots were taken from GoDaddy's interface at the time the 767 original version of this guide was published (2015). It may have 768 changed since then. 769 770.. _recipes_nsec3: 771 772NSEC and NSEC3 773~~~~~~~~~~~~~~ 774 775.. _recipes_nsec_to_nsec3: 776 777Migrating from NSEC to NSEC3 778^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 779 780This recipe describes how to transition from using NSEC to NSEC3, as described 781in :ref:`advanced_discussions_proof_of_nonexistence`. This recipe 782assumes that the zones are already signed, and that :iscman:`named` is configured 783according to the steps described in 784:ref:`easy_start_guide_for_authoritative_servers`. 785 786.. warning:: 787 788 If your zone is signed with RSASHA1 (algorithm 5), you cannot migrate 789 to NSEC3 without also performing an 790 algorithm rollover 791 to RSASHA1-NSEC3-SHA1 (algorithm 7), as described in 792 :ref:`advanced_discussions_DNSKEY_algorithm_rollovers`. This 793 ensures that older validating resolvers that do not understand 794 NSEC3 will fall back to treating the zone as unsecured (rather than 795 "bogus"), as described in Section 2 of :rfc:`5155`. 796 797To enable NSEC3, update your :any:`dnssec-policy` and add the desired NSEC3 798parameters. The example below enables NSEC3 for zones with the ``standard`` 799DNSSEC policy, using 0 additional iterations, no opt-out, and a zero-length salt: 800 801:: 802 803 dnssec-policy "standard" { 804 nsec3param iterations 0 optout no salt-length 0; 805 }; 806 807Then reconfigure the server with :iscman:`rndc`. You can tell that it worked if you 808see the following debug log messages: 809 810:: 811 812 Oct 21 13:47:21 received control channel command 'reconfig' 813 Oct 21 13:47:21 zone example.com/IN (signed): zone_addnsec3chain(1,CREATE,0,-) 814 815You can also verify that it worked by querying for a name that you know 816does not exist, and checking for the presence of the NSEC3 record. 817For example: 818 819:: 820 821 $ dig @192.168.1.13 thereisnowaythisexists.example.com. A +dnssec +multiline 822 823 ... 824 5A03TL362CS8VSIH69CVA4MJIKRHFQH3.example.com. 300 IN NSEC3 1 0 0 - ( 825 TQ9QBEGA6CROHEOC8KIH1A2C06IVQ5ER 826 NS SOA RRSIG DNSKEY NSEC3PARAM ) 827 ... 828 829Our example used four parameters: 1, 0, 0, and -, in 830order. 1 represents the algorithm, 0 represents the 831opt-out flag, 0 represents the number of additional iterations, and 832- denotes no salt is used. To learn more about each of these 833parameters, please see :ref:`advanced_discussions_nsec3param`. 834 835.. _recipes_nsec3_to_nsec: 836 837Migrating from NSEC3 to NSEC 838^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 839 840Migrating from NSEC3 back to NSEC is easy; just remove the :any:`nsec3param` 841configuration option from your :any:`dnssec-policy` and reconfigure the name 842server. You can tell that it worked if you see these messages in the log: 843 844:: 845 846 named[14093]: received control channel command 'reconfig' 847 named[14093]: zone example.com/IN: zone_addnsec3chain(1,REMOVE,0,-) 848 849You can also query for a name that you know does not exist, 850and you should no longer see any traces of NSEC3 records. 851 852:: 853 854 $ dig @192.168.1.13 reieiergiuhewhiouwe.example.com. A +dnssec +multiline 855 856 ... 857 example.com. 300 IN NSEC aaa.example.com. NS SOA RRSIG NSEC DNSKEY 858 ... 859 ns1.example.com. 300 IN NSEC web.example.com. A RRSIG NSEC 860 ... 861 862.. _recipes_nsec3_optout: 863 864NSEC3 Opt-Out 865^^^^^^^^^^^^^ 866 867This recipe discusses how to enable and disable NSEC3 opt-out, and how to show 868the results of each action. As discussed in 869:ref:`advanced_discussions_nsec3_optout`, NSEC3 opt-out is a feature 870that can help conserve resources on parent zones with many 871delegations that have not yet been signed. 872 873.. warning:: 874 NSEC3 Opt-Out feature brings benefit only to _extremely_ large zones with lots 875 of insecure delegations. It's use is counterproductive in all other cases as 876 it decreases tamper-resistance of the zone and also decreases efficiency of 877 resolver cache (see :rfc:`8198`). 878 879 In other words, don't enable Opt-Out unless you are serving an equivalent of 880 ``com.`` zone. 881 882Because the NSEC3PARAM record does not keep track of whether opt-out is used, 883it is hard to check whether changes need to be made to the NSEC3 chain if the flag 884is changed. Similar to changing the NSEC3 salt, your best option is to change 885the value of ``optout`` together with another NSEC3 parameter, like 886``iterations``, and in a following step restore the ``iterations`` value. 887 888For this recipe we assume the zone ``example.com`` 889has the following four entries (for this example, it is not relevant what 890record types these entries are): 891 892- ``ns1.example.com`` 893 894- ``ftp.example.com`` 895 896- ``www.example.com`` 897 898- ``web.example.com`` 899 900And the zone ``example.com`` has five delegations to five subdomains, only one of 901which is signed and has a valid DS RRset: 902 903- ``aaa.example.com``, not signed 904 905- ``bbb.example.com``, signed 906 907- ``ccc.example.com``, not signed 908 909- ``ddd.example.com``, not signed 910 911- ``eee.example.com``, not signed 912 913Before enabling NSEC3 opt-out, the zone ``example.com`` contains ten 914NSEC3 records; below is the list with the plain text name before the actual 915NSEC3 record: 916 917- *aaa.example.com*: IFA1I3IE7EKCTPHM6R58URO3Q846I52M.example.com 918 919- *bbb.example.com*: ROJUF3VJSJO6LQ2LC1DNSJ5GBAUJPVHE.example.com 920 921- *ccc.example.com*: 0VPUT696LUVDPDS5NIHSHBH9KLV20V5K.example.com 922 923- *ddd.example.com*: UHPBD5U4HRGB84MLC2NQOVEFNAKJU0CA.example.com 924 925- *eee.example.com*: NF7I61FA4C2UEKPMEDSOC25FE0UJIMKT.example.com 926 927- *ftp.example.com*: 8P15KCUAT1RHCSDN46HBQVPI5T532IN1.example.com 928 929- *ns1.example.com*: GUFVRA2SFIO8RSFP7UO41E8AD1KR41FH.example.com 930 931- *web.example.com*: CVQ4LA4ALPQIAO2H3N2RB6IR8UHM91E7.example.com 932 933- *www.example.com*: MIFDNDT3NFF3OD53O7TLA1HRFF95JKUK.example.com 934 935- *example.com*: ONIB9MGUB9H0RML3CDF5BGRJ59DKJHVK.example.com 936 937We can enable NSEC3 opt-out with the following configuration, changing 938the ``optout`` configuration value from ``no`` to ``yes``: 939 940:: 941 942 dnssec-policy "standard" { 943 nsec3param iterations 0 optout yes salt-length 0; 944 }; 945 946After NSEC3 opt-out is enabled, the number of NSEC3 records is reduced. 947Notice that the unsigned delegations ``aaa``, ``ccc``, ``ddd``, and 948``eee`` no longer have corresponding NSEC3 records. 949 950- *bbb.example.com*: ROJUF3VJSJO6LQ2LC1DNSJ5GBAUJPVHE.example.com 951 952- *ftp.example.com*: 8P15KCUAT1RHCSDN46HBQVPI5T532IN1.example.com 953 954- *ns1.example.com*: GUFVRA2SFIO8RSFP7UO41E8AD1KR41FH.example.com 955 956- *web.example.com*: CVQ4LA4ALPQIAO2H3N2RB6IR8UHM91E7.example.com 957 958- *www.example.com*: MIFDNDT3NFF3OD53O7TLA1HRFF95JKUK.example.com 959 960- *example.com*: ONIB9MGUB9H0RML3CDF5BGRJ59DKJHVK.example.com 961 962To undo NSEC3 opt-out, change the configuration again: 963 964:: 965 966 dnssec-policy "standard" { 967 nsec3param iterations 0 optout no salt-length 0; 968 }; 969 970.. note:: 971 972 NSEC3 hashes the plain text domain name, and we can compute our own 973 hashes using the tool :iscman:`nsec3hash`. For example, to compute the 974 hashed name for ``www.example.com`` using the parameters we listed 975 above, we can execute this command: 976 977 :: 978 979 # nsec3hash - 1 0 www.example.com. 980 MIFDNDT3NFF3OD53O7TLA1HRFF95JKUK (salt=-, hash=1, iterations=0) 981 982.. _revert_to_unsigned: 983 984Reverting to Unsigned 985~~~~~~~~~~~~~~~~~~~~~ 986 987This recipe describes how to revert from a signed zone (DNSSEC) back to 988an unsigned (DNS) zone. 989 990Here is what :iscman:`named.conf` looks like when it is signed: 991 992.. code-block:: none 993 :emphasize-lines: 4 994 995 zone "example.com" IN { 996 type primary; 997 file "db/example.com.db"; 998 dnssec-policy "default"; 999 }; 1000 1001To indicate the reversion to unsigned, change the :any:`dnssec-policy` line: 1002 1003.. code-block:: none 1004 :emphasize-lines: 4 1005 1006 zone "example.com" IN { 1007 type primary; 1008 file "db/example.com.db"; 1009 dnssec-policy "insecure"; 1010 }; 1011 1012Then use :option:`rndc reload` to reload the zone. 1013 1014The "insecure" policy is a built-in policy (like "default"). It makes sure 1015the zone is still DNSSEC-maintained, to allow for a graceful transition to 1016unsigned. It also publishes the CDS and CDNSKEY DELETE records automatically 1017at the appropriate time. 1018 1019If the parent zone allows management of DS records via CDS/CDNSKEY, as described in 1020:rfc:`8078`, the DS record should be removed from the parent automatically. 1021 1022Otherwise, DS records can be removed via the registrar. Below is an example 1023showing how to remove DS records using the 1024`GoDaddy <https://www.godaddy.com>`__ web-based interface: 1025 10261. After logging in, click the green "Launch" button next to the domain 1027 name you want to manage. 1028 1029.. _unsign-1: 1030 1031 .. figure:: ../dnssec-guide/img/unsign-1.png 1032 :alt: Revert to Unsigned Step #1 1033 :width: 60.0% 1034 1035 Revert to Unsigned Step #1 1036 10372. Scroll down to the "DS Records" section and click Manage. 1038 1039.. _unsign-2: 1040 1041 .. figure:: ../dnssec-guide/img/unsign-2.png 1042 :alt: Revert to Unsigned Step #2 1043 :width: 40.0% 1044 1045 Revert to Unsigned Step #2 1046 10473. A dialog appears, displaying all current keys. Use the far right-hand 1048 X button to remove each key. 1049 1050.. _unsign-3: 1051 1052 .. figure:: ../dnssec-guide/img/unsign-3.png 1053 :alt: Revert to Unsigned Step #3 1054 :width: 70.0% 1055 1056 Revert to Unsigned Step #3 1057 10584. Click Save. 1059 1060.. _unsign-4: 1061 1062 .. figure:: ../dnssec-guide/img/unsign-4.png 1063 :alt: Revert to Unsigned Step #4 1064 :width: 70.0% 1065 1066 Revert to Unsigned Step #4 1067 1068When the DS records have been removed from the parent zone, use 1069:option:`rndc dnssec -checkds -key id withdrawn example.com <rndc dnssec>` to tell :iscman:`named` that 1070the DS is removed, and the remaining DNSSEC records will be removed in a timely 1071manner. Or, if parental agents are configured, the DNSSEC records will be 1072automatically removed after BIND has seen that the parental agents no longer 1073serve the DS RRset for this zone. 1074 1075After a while, the zone is reverted back to the traditional, insecure DNS 1076format. This can be verified by checking that all DNSKEY and RRSIG records have been 1077removed from the zone. 1078 1079The :any:`dnssec-policy` line can then be removed from :iscman:`named.conf` and 1080the zone reloaded. The zone will no longer be subject to any DNSSEC 1081maintenance. 1082
