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.dynamic.zones: 13 14DNSSEC, Dynamic Zones, and Automatic Signing 15-------------------------------------------- 16 17Converting From Insecure to Secure 18~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 19 20A zone can be changed from insecure to secure in three ways: using a 21dynamic DNS update, via the ``auto-dnssec`` zone option, or by setting a 22DNSSEC policy for the zone with ``dnssec-policy``. 23 24For any method, ``named`` must be configured so that it can see 25the ``K*`` files which contain the public and private parts of the keys 26that are used to sign the zone. These files are generated 27by ``dnssec-keygen``, or created when needed by ``named`` if 28``dnssec-policy`` is used. Keys should be placed in the 29key-directory, as specified in ``named.conf``: 30 31:: 32 33 zone example.net { 34 type primary; 35 update-policy local; 36 file "dynamic/example.net/example.net"; 37 key-directory "dynamic/example.net"; 38 }; 39 40If one KSK and one ZSK DNSKEY key have been generated, this 41configuration causes all records in the zone to be signed with the 42ZSK, and the DNSKEY RRset to be signed with the KSK. An NSEC 43chain is generated as part of the initial signing process. 44 45With ``dnssec-policy``, it is possible to specify which keys should be 46KSK and/or ZSK. To sign all records with a key, a CSK must be specified. 47For example: 48 49:: 50 51 dnssec-policy csk { 52 keys { 53 csk lifetime unlimited algorithm 13; 54 }; 55 }; 56 57Dynamic DNS Update Method 58~~~~~~~~~~~~~~~~~~~~~~~~~ 59 60To insert the keys via dynamic update: 61 62:: 63 64 % nsupdate 65 > ttl 3600 66 > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8= 67 > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk= 68 > send 69 70While the update request completes almost immediately, the zone is 71not completely signed until ``named`` has had time to "walk" the zone 72and generate the NSEC and RRSIG records. The NSEC record at the apex 73is added last, to signal that there is a complete NSEC chain. 74 75To sign using NSEC3 instead of NSEC, add an 76NSEC3PARAM record to the initial update request. The OPTOUT bit in the NSEC3 77chain can be set in the flags field of the 78NSEC3PARAM record. 79 80:: 81 82 % nsupdate 83 > ttl 3600 84 > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8= 85 > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk= 86 > update add example.net NSEC3PARAM 1 1 100 1234567890 87 > send 88 89Again, this update request completes almost immediately; however, 90the record does not show up until ``named`` has had a chance to 91build/remove the relevant chain. A private type record is created 92to record the state of the operation (see below for more details), and 93is removed once the operation completes. 94 95While the initial signing and NSEC/NSEC3 chain generation is happening, 96other updates are possible as well. 97 98Fully Automatic Zone Signing 99~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 100 101To enable automatic signing, set a ``dnssec-policy`` or add the 102``auto-dnssec`` option to the zone statement in ``named.conf``. 103``auto-dnssec`` has two possible arguments: ``allow`` or ``maintain``. 104 105With ``auto-dnssec allow``, ``named`` can search the key directory for 106keys matching the zone, insert them into the zone, and use them to sign 107the zone. It does so only when it receives an 108``rndc sign <zonename>``. 109 110``auto-dnssec maintain`` includes the above functionality, but also 111automatically adjusts the zone's DNSKEY records on a schedule according to 112the keys' timing metadata. (See :ref:`man_dnssec-keygen` and 113:ref:`man_dnssec-settime` for more information.) 114 115``dnssec-policy`` is similar to ``auto-dnssec maintain``, but 116``dnssec-policy`` also automatically creates new keys when necessary. In 117addition, any configuration related to DNSSEC signing is retrieved from the 118policy, ignoring existing DNSSEC ``named.conf`` options. 119 120``named`` periodically searches the key directory for keys matching 121the zone; if the keys' metadata indicates that any change should be 122made to the zone - such as adding, removing, or revoking a key - then that 123action is carried out. By default, the key directory is checked for 124changes every 60 minutes; this period can be adjusted with 125``dnssec-loadkeys-interval``, up to a maximum of 24 hours. The 126``rndc loadkeys`` command forces ``named`` to check for key updates immediately. 127 128If keys are present in the key directory the first time the zone is 129loaded, the zone is signed immediately, without waiting for an 130``rndc sign`` or ``rndc loadkeys`` command. Those commands can still be 131used when there are unscheduled key changes. 132 133When new keys are added to a zone, the TTL is set to match that of any 134existing DNSKEY RRset. If there is no existing DNSKEY RRset, the 135TTL is set to the TTL specified when the key was created (using the 136``dnssec-keygen -L`` option), if any, or to the SOA TTL. 137 138To sign the zone using NSEC3 instead of NSEC, submit an 139NSEC3PARAM record via dynamic update prior to the scheduled publication 140and activation of the keys. The OPTOUT bit for the NSEC3 chain can be set 141in the flags field of the NSEC3PARAM record. The 142NSEC3PARAM record does not appear in the zone immediately, but it is 143stored for later reference. When the zone is signed and the NSEC3 144chain is completed, the NSEC3PARAM record appears in the zone. 145 146Using the ``auto-dnssec`` option requires the zone to be configured to 147allow dynamic updates, by adding an ``allow-update`` or 148``update-policy`` statement to the zone configuration. If this has not 149been done, the configuration fails. 150 151Private Type Records 152~~~~~~~~~~~~~~~~~~~~ 153 154The state of the signing process is signaled by private type records 155(with a default type value of 65534). When signing is complete, those 156records with a non-zero initial octet have a non-zero value for the final octet. 157 158If the first octet of a private type record is non-zero, the 159record indicates either that the zone needs to be signed with the key matching 160the record, or that all signatures that match the record should be 161removed. Here are the meanings of the different values of the first octet: 162 163 - algorithm (octet 1) 164 165 - key id in network order (octet 2 and 3) 166 167 - removal flag (octet 4) 168 169 - complete flag (octet 5) 170 171Only records flagged as "complete" can be removed via dynamic update; attempts 172to remove other private type records are silently ignored. 173 174If the first octet is zero (this is a reserved algorithm number that 175should never appear in a DNSKEY record), the record indicates that 176changes to the NSEC3 chains are in progress. The rest of the record 177contains an NSEC3PARAM record, while the flag field tells what operation to 178perform based on the flag bits: 179 180 0x01 OPTOUT 181 182 0x80 CREATE 183 184 0x40 REMOVE 185 186 0x20 NONSEC 187 188DNSKEY Rollovers 189~~~~~~~~~~~~~~~~ 190 191As with insecure-to-secure conversions, DNSSEC keyrolls can be done 192in two ways: using a dynamic DNS update, or via the ``auto-dnssec`` zone 193option. 194 195Dynamic DNS Update Method 196~~~~~~~~~~~~~~~~~~~~~~~~~ 197 198To perform key rollovers via a dynamic update, the ``K*`` 199files for the new keys must be added so that ``named`` can find them. 200The new DNSKEY RRs can then be added via dynamic update. ``named`` then causes the 201zone to be signed with the new keys; when the signing is complete, the 202private type records are updated so that the last octet is non-zero. 203 204If this is for a KSK, the parent and any trust anchor 205repositories of the new KSK must be informed. 206 207The maximum TTL in the zone must expire before removing the 208old DNSKEY. If it is a KSK that is being updated, 209the DS RRset in the parent must also be updated and its TTL allowed to expire. This 210ensures that all clients are able to verify at least one signature 211when the old DNSKEY is removed. 212 213The old DNSKEY can be removed via UPDATE, taking care to specify the 214correct key. ``named`` cleans out any signatures generated by the 215old key after the update completes. 216 217Automatic Key Rollovers 218~~~~~~~~~~~~~~~~~~~~~~~ 219 220When a new key reaches its activation date (as set by ``dnssec-keygen`` 221or ``dnssec-settime``), and if the ``auto-dnssec`` zone option is set to 222``maintain``, ``named`` automatically carries out the key rollover. 223If the key's algorithm has not previously been used to sign the zone, 224then the zone is fully signed as quickly as possible. However, if 225the new key replaces an existing key of the same algorithm, the 226zone is re-signed incrementally, with signatures from the old key 227replaced with signatures from the new key as their signature 228validity periods expire. By default, this rollover completes in 30 days, 229after which it is safe to remove the old key from the DNSKEY RRset. 230 231NSEC3PARAM Rollovers via UPDATE 232~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 233 234The new NSEC3PARAM record can be added via dynamic update. When the new NSEC3 235chain has been generated, the NSEC3PARAM flag field is set to zero. At 236that point, the old NSEC3PARAM record can be removed. The old chain is 237removed after the update request completes. 238 239Converting From NSEC to NSEC3 240~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 241 242Add a ``nsec3param`` option to your ``dnssec-policy`` and 243run ``rndc reconfig``. 244 245Or use ``nsupdate`` to add an NSEC3PARAM record. 246 247In both cases, the NSEC3 chain is generated and the NSEC3PARAM record is 248added before the NSEC chain is destroyed. 249 250Converting From NSEC3 to NSEC 251~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 252 253To do this, remove the ``nsec3param`` option from the ``dnssec-policy`` and 254run ``rndc reconfig``. 255 256Or use ``nsupdate`` to remove all NSEC3PARAM records with a 257zero flag field. The NSEC chain is generated before the NSEC3 chain 258is removed. 259 260Converting From Secure to Insecure 261~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 262 263To convert a signed zone to unsigned using dynamic DNS, delete all the 264DNSKEY records from the zone apex using ``nsupdate``. All signatures, 265NSEC or NSEC3 chains, and associated NSEC3PARAM records are removed 266automatically. This takes place after the update request completes. 267 268This requires the ``dnssec-secure-to-insecure`` option to be set to 269``yes`` in ``named.conf``. 270 271In addition, if the ``auto-dnssec maintain`` zone statement is used, it 272should be removed or changed to ``allow`` instead; otherwise it will re-sign. 273 274Periodic Re-signing 275~~~~~~~~~~~~~~~~~~~ 276 277In any secure zone which supports dynamic updates, ``named`` 278periodically re-signs RRsets which have not been re-signed as a result of 279some update action. The signature lifetimes are adjusted to 280spread the re-sign load over time rather than all at once. 281 282NSEC3 and OPTOUT 283~~~~~~~~~~~~~~~~ 284 285``named`` only supports creating new NSEC3 chains where all the NSEC3 286records in the zone have the same OPTOUT state. ``named`` supports 287UPDATES to zones where the NSEC3 records in the chain have mixed OPTOUT 288state. ``named`` does not support changing the OPTOUT state of an 289individual NSEC3 record; if the 290OPTOUT state of an individual NSEC3 needs to be changed, the entire chain must be changed. 291