1<?xml version="1.0" encoding="utf-8"?> 2<!-- 3 - Copyright (C) 2010, 2011, 2015 Internet Systems Consortium, Inc. ("ISC") 4 - 5 - Permission to use, copy, modify, and/or distribute this software for any 6 - purpose with or without fee is hereby granted, provided that the above 7 - copyright notice and this permission notice appear in all copies. 8 - 9 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15 - PERFORMANCE OF THIS SOFTWARE. 16--> 17 18<sect1 id="dnssec.dynamic.zones"> 19 <title>DNSSEC, Dynamic Zones, and Automatic Signing</title> 20 <para>As of BIND 9.7.0 it is possible to change a dynamic zone 21 from insecure to signed and back again. A secure zone can use 22 either NSEC or NSEC3 chains.</para> 23 <sect2> 24 <title>Converting from insecure to secure</title> 25 </sect2> 26 <para>Changing a zone from insecure to secure can be done in two 27 ways: using a dynamic DNS update, or the 28 <command>auto-dnssec</command> zone option.</para> 29 <para>For either method, you need to configure 30 <command>named</command> so that it can see the 31 <filename>K*</filename> files which contain the public and private 32 parts of the keys that will be used to sign the zone. These files 33 will have been generated by 34 <command>dnssec-keygen</command>. You can do this by placing them 35 in the key-directory, as specified in 36 <filename>named.conf</filename>:</para> 37 <programlisting> 38 zone example.net { 39 type master; 40 update-policy local; 41 file "dynamic/example.net/example.net"; 42 key-directory "dynamic/example.net"; 43 }; 44</programlisting> 45 <para>If one KSK and one ZSK DNSKEY key have been generated, this 46 configuration will cause all records in the zone to be signed 47 with the ZSK, and the DNSKEY RRset to be signed with the KSK as 48 well. An NSEC chain will be generated as part of the initial 49 signing process.</para> 50 <sect2> 51 <title>Dynamic DNS update method</title> 52 </sect2> 53 <para>To insert the keys via dynamic update:</para> 54 <screen> 55 % nsupdate 56 > ttl 3600 57 > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8= 58 > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk= 59 > send 60</screen> 61 <para>While the update request will complete almost immediately, 62 the zone will not be completely signed until 63 <command>named</command> has had time to walk the zone and 64 generate the NSEC and RRSIG records. The NSEC record at the apex 65 will be added last, to signal that there is a complete NSEC 66 chain.</para> 67 <para>If you wish to sign using NSEC3 instead of NSEC, you should 68 add an NSEC3PARAM record to the initial update request. If you 69 wish the NSEC3 chain to have the OPTOUT bit set, set it in the 70 flags field of the NSEC3PARAM record.</para> 71 <screen> 72 % nsupdate 73 > ttl 3600 74 > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8= 75 > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk= 76 > update add example.net NSEC3PARAM 1 1 100 1234567890 77 > send 78</screen> 79 <para>Again, this update request will complete almost 80 immediately; however, the record won't show up until 81 <command>named</command> has had a chance to build/remove the 82 relevant chain. A private type record will be created to record 83 the state of the operation (see below for more details), and will 84 be removed once the operation completes.</para> 85 <para>While the initial signing and NSEC/NSEC3 chain generation 86 is happening, other updates are possible as well.</para> 87 <sect2> 88 <title>Fully automatic zone signing</title> 89 </sect2> 90 <para>To enable automatic signing, add the 91 <command>auto-dnssec</command> option to the zone statement in 92 <filename>named.conf</filename>. 93 <command>auto-dnssec</command> has two possible arguments: 94 <constant>allow</constant> or 95 <constant>maintain</constant>.</para> 96 <para>With 97 <command>auto-dnssec allow</command>, 98 <command>named</command> can search the key directory for keys 99 matching the zone, insert them into the zone, and use them to 100 sign the zone. It will do so only when it receives an 101 <command>rndc sign <zonename></command>.</para> 102 <para> 103 <!-- TODO: this is repeated in the ARM --> 104 <command>auto-dnssec maintain</command> includes the above 105 functionality, but will also automatically adjust the zone's 106 DNSKEY records on schedule according to the keys' timing metadata. 107 (See <xref linkend="man.dnssec-keygen"/> and 108 <xref linkend="man.dnssec-settime"/> for more information.) 109 </para> 110 <para> 111 <command>named</command> will periodically search the key directory 112 for keys matching the zone, and if the keys' metadata indicates 113 that any change should be made the zone, such as adding, removing, 114 or revoking a key, then that action will be carried out. By default, 115 the key directory is checked for changes every 60 minutes; this period 116 can be adjusted with the <option>dnssec-loadkeys-interval</option>, up 117 to a maximum of 24 hours. The <command>rndc loadkeys</command> forces 118 <command>named</command> to check for key updates immediately. 119 </para> 120 <para> 121 If keys are present in the key directory the first time the zone 122 is loaded, the zone will be signed immediately, without waiting for an 123 <command>rndc sign</command> or <command>rndc loadkeys</command> 124 command. (Those commands can still be used when there are unscheduled 125 key changes, however.) 126 </para> 127 <para> 128 When new keys are added to a zone, the TTL is set to match that 129 of any existing DNSKEY RRset. If there is no existing DNSKEY RRset, 130 then the TTL will be set to the TTL specified when the key was 131 created (using the <command>dnssec-keygen -L</command> option), if 132 any, or to the SOA TTL. 133 </para> 134 <para> 135 If you wish the zone to be signed using NSEC3 instead of NSEC, 136 submit an NSEC3PARAM record via dynamic update prior to the 137 scheduled publication and activation of the keys. If you wish the 138 NSEC3 chain to have the OPTOUT bit set, set it in the flags field 139 of the NSEC3PARAM record. The NSEC3PARAM record will not appear in 140 the zone immediately, but it will be stored for later reference. When 141 the zone is signed and the NSEC3 chain is completed, the NSEC3PARAM 142 record will appear in the zone. 143 </para> 144 <para>Using the 145 <command>auto-dnssec</command> option requires the zone to be 146 configured to allow dynamic updates, by adding an 147 <command>allow-update</command> or 148 <command>update-policy</command> statement to the zone 149 configuration. If this has not been done, the configuration will 150 fail.</para> 151 <sect2> 152 <title>Private-type records</title> 153 </sect2> 154 <para>The state of the signing process is signaled by 155 private-type records (with a default type value of 65534). When 156 signing is complete, these records will have a nonzero value for 157 the final octet (for those records which have a nonzero initial 158 octet).</para> 159 <para>The private type record format: If the first octet is 160 non-zero then the record indicates that the zone needs to be 161 signed with the key matching the record, or that all signatures 162 that match the record should be removed.</para> 163 <para> 164 <literallayout> 165<!-- TODO: how to format this? --> 166 algorithm (octet 1) 167 key id in network order (octet 2 and 3) 168 removal flag (octet 4) 169 complete flag (octet 5) 170</literallayout> 171 </para> 172 <para>Only records flagged as "complete" can be removed via 173 dynamic update. Attempts to remove other private type records 174 will be silently ignored.</para> 175 <para>If the first octet is zero (this is a reserved algorithm 176 number that should never appear in a DNSKEY record) then the 177 record indicates changes to the NSEC3 chains are in progress. The 178 rest of the record contains an NSEC3PARAM record. The flag field 179 tells what operation to perform based on the flag bits.</para> 180 <para> 181 <literallayout> 182<!-- TODO: how to format this? --> 183 0x01 OPTOUT 184 0x80 CREATE 185 0x40 REMOVE 186 0x20 NONSEC 187</literallayout> 188 </para> 189 <sect2> 190 <title>DNSKEY rollovers</title> 191 </sect2> 192 <para>As with insecure-to-secure conversions, rolling DNSSEC 193 keys can be done in two ways: using a dynamic DNS update, or the 194 <command>auto-dnssec</command> zone option.</para> 195 <sect2> 196 <title>Dynamic DNS update method</title> 197 </sect2> 198 <para> To perform key rollovers via dynamic update, you need to add 199 the <filename>K*</filename> files for the new keys so that 200 <command>named</command> can find them. You can then add the new 201 DNSKEY RRs via dynamic update. 202 <command>named</command> will then cause the zone to be signed 203 with the new keys. When the signing is complete the private type 204 records will be updated so that the last octet is non 205 zero.</para> 206 <para>If this is for a KSK you need to inform the parent and any 207 trust anchor repositories of the new KSK.</para> 208 <para>You should then wait for the maximum TTL in the zone before 209 removing the old DNSKEY. If it is a KSK that is being updated, 210 you also need to wait for the DS RRset in the parent to be 211 updated and its TTL to expire. This ensures that all clients will 212 be able to verify at least one signature when you remove the old 213 DNSKEY.</para> 214 <para>The old DNSKEY can be removed via UPDATE. Take care to 215 specify the correct key. 216 <command>named</command> will clean out any signatures generated 217 by the old key after the update completes.</para> 218 <sect2> 219 <title>Automatic key rollovers</title> 220 </sect2> 221 <para>When a new key reaches its activation date (as set by 222 <command>dnssec-keygen</command> or <command>dnssec-settime</command>), 223 if the <command>auto-dnssec</command> zone option is set to 224 <constant>maintain</constant>, <command>named</command> will 225 automatically carry out the key rollover. If the key's algorithm 226 has not previously been used to sign the zone, then the zone will 227 be fully signed as quickly as possible. However, if the new key 228 is replacing an existing key of the same algorithm, then the 229 zone will be re-signed incrementally, with signatures from the 230 old key being replaced with signatures from the new key as their 231 signature validity periods expire. By default, this rollover 232 completes in 30 days, after which it will be safe to remove the 233 old key from the DNSKEY RRset.</para> 234 <sect2> 235 <title>NSEC3PARAM rollovers via UPDATE</title> 236 </sect2> 237 <para>Add the new NSEC3PARAM record via dynamic update. When the 238 new NSEC3 chain has been generated, the NSEC3PARAM flag field 239 will be zero. At this point you can remove the old NSEC3PARAM 240 record. The old chain will be removed after the update request 241 completes.</para> 242 <sect2> 243 <title>Converting from NSEC to NSEC3</title> 244 </sect2> 245 <para>To do this, you just need to add an NSEC3PARAM record. When 246 the conversion is complete, the NSEC chain will have been removed 247 and the NSEC3PARAM record will have a zero flag field. The NSEC3 248 chain will be generated before the NSEC chain is 249 destroyed.</para> 250 <sect2> 251 <title>Converting from NSEC3 to NSEC</title> 252 </sect2> 253 <para>To do this, use <command>nsupdate</command> to 254 remove all NSEC3PARAM records with a zero flag 255 field. The NSEC chain will be generated before the NSEC3 chain is 256 removed.</para> 257 <sect2> 258 <title>Converting from secure to insecure</title> 259 </sect2> 260 <para>To convert a signed zone to unsigned using dynamic DNS, 261 delete all the DNSKEY records from the zone apex using 262 <command>nsupdate</command>. All signatures, NSEC or NSEC3 chains, 263 and associated NSEC3PARAM records will be removed automatically. 264 This will take place after the update request completes.</para> 265 <para> This requires the 266 <command>dnssec-secure-to-insecure</command> option to be set to 267 <userinput>yes</userinput> in 268 <filename>named.conf</filename>.</para> 269 <para>In addition, if the <command>auto-dnssec maintain</command> 270 zone statement is used, it should be removed or changed to 271 <command>allow</command> instead (or it will re-sign). 272 </para> 273 <sect2> 274 <title>Periodic re-signing</title> 275 </sect2> 276 <para>In any secure zone which supports dynamic updates, named 277 will periodically re-sign RRsets which have not been re-signed as 278 a result of some update action. The signature lifetimes will be 279 adjusted so as to spread the re-sign load over time rather than 280 all at once.</para> 281 <sect2> 282 <title>NSEC3 and OPTOUT</title> 283 </sect2> 284 <para> 285 <command>named</command> only supports creating new NSEC3 chains 286 where all the NSEC3 records in the zone have the same OPTOUT 287 state. 288 <command>named</command> supports UPDATES to zones where the NSEC3 289 records in the chain have mixed OPTOUT state. 290 <command>named</command> does not support changing the OPTOUT 291 state of an individual NSEC3 record, the entire chain needs to be 292 changed if the OPTOUT state of an individual NSEC3 needs to be 293 changed.</para> 294</sect1> 295