1 <?xml version="1.0" encoding="utf-8"?>
3 - Copyright (C) 2010, 2011 Internet Systems Consortium, Inc. ("ISC")
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.
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.
18 <!-- $Id: dnssec.xml,v 1.7 2011/10/13 23:47:10 tbox Exp $ -->
20 <sect1 id="dnssec.dynamic.zones">
21 <title>DNSSEC, Dynamic Zones, and Automatic Signing</title>
22 <para>As of BIND 9.7.0 it is possible to change a dynamic zone
23 from insecure to signed and back again. A secure zone can use
24 either NSEC or NSEC3 chains.</para>
26 <title>Converting from insecure to secure</title>
28 <para>Changing a zone from insecure to secure can be done in two
29 ways: using a dynamic DNS update, or the
30 <command>auto-dnssec</command> zone option.</para>
31 <para>For either method, you need to configure
32 <command>named</command> so that it can see the
33 <filename>K*</filename> files which contain the public and private
34 parts of the keys that will be used to sign the zone. These files
35 will have been generated by
36 <command>dnssec-keygen</command>. You can do this by placing them
37 in the key-directory, as specified in
38 <filename>named.conf</filename>:</para>
43 file "dynamic/example.net/example.net";
44 key-directory "dynamic/example.net";
47 <para>If one KSK and one ZSK DNSKEY key have been generated, this
48 configuration will cause all records in the zone to be signed
49 with the ZSK, and the DNSKEY RRset to be signed with the KSK as
50 well. An NSEC chain will be generated as part of the initial
51 signing process.</para>
53 <title>Dynamic DNS update method</title>
55 <para>To insert the keys via dynamic update:</para>
59 > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8=
60 > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=
63 <para>While the update request will complete almost immediately,
64 the zone will not be completely signed until
65 <command>named</command> has had time to walk the zone and
66 generate the NSEC and RRSIG records. The NSEC record at the apex
67 will be added last, to signal that there is a complete NSEC
69 <para>If you wish to sign using NSEC3 instead of NSEC, you should
70 add an NSEC3PARAM record to the initial update request. If you
71 wish the NSEC3 chain to have the OPTOUT bit set, set it in the
72 flags field of the NSEC3PARAM record.</para>
76 > update add example.net DNSKEY 256 3 7 AwEAAZn17pUF0KpbPA2c7Gz76Vb18v0teKT3EyAGfBfL8eQ8al35zz3Y I1m/SAQBxIqMfLtIwqWPdgthsu36azGQAX8=
77 > update add example.net DNSKEY 257 3 7 AwEAAd/7odU/64o2LGsifbLtQmtO8dFDtTAZXSX2+X3e/UNlq9IHq3Y0 XtC0Iuawl/qkaKVxXe2lo8Ct+dM6UehyCqk=
78 > update add example.net NSEC3PARAM 1 1 100 1234567890
81 <para>Again, this update request will complete almost
82 immediately; however, the record won't show up until
83 <command>named</command> has had a chance to build/remove the
84 relevant chain. A private type record will be created to record
85 the state of the operation (see below for more details), and will
86 be removed once the operation completes.</para>
87 <para>While the initial signing and NSEC/NSEC3 chain generation
88 is happening, other updates are possible as well.</para>
90 <title>Fully automatic zone signing</title>
92 <para>To enable automatic signing, add the
93 <command>auto-dnssec</command> option to the zone statement in
94 <filename>named.conf</filename>.
95 <command>auto-dnssec</command> has two possible arguments:
96 <constant>allow</constant> or
97 <constant>maintain</constant>.</para>
99 <command>auto-dnssec allow</command>,
100 <command>named</command> can search the key directory for keys
101 matching the zone, insert them into the zone, and use them to
102 sign the zone. It will do so only when it receives an
103 <command>rndc sign <zonename></command>.</para>
105 <!-- TODO: this is repeated in the ARM -->
106 <command>auto-dnssec maintain</command> includes the above
107 functionality, but will also automatically adjust the zone's
108 DNSKEY records on schedule according to the keys' timing metadata.
109 (See <xref linkend="man.dnssec-keygen"/> and
110 <xref linkend="man.dnssec-settime"/> for more information.)
113 <command>named</command> will periodically search the key directory
114 for keys matching the zone, and if the keys' metadata indicates
115 that any change should be made the zone, such as adding, removing,
116 or revoking a key, then that action will be carried out. By default,
117 the key directory is checked for changes every 60 minutes; this period
118 can be adjusted with the <option>dnssec-loadkeys-interval</option>, up
119 to a maximum of 24 hours. The <command>rndc loadkeys</command> forces
120 <command>named</command> to check for key updates immediately.
123 If keys are present in the key directory the first time the zone
124 is loaded, the zone will be signed immediately, without waiting for an
125 <command>rndc sign</command> or <command>rndc loadkeys</command>
126 command. (Those commands can still be used when there are unscheduled
127 key changes, however.)
130 If you wish the zone to be signed using NSEC3 instead of NSEC,
131 submit an NSEC3PARAM record via dynamic update prior to the
132 scheduled publication and activation of the keys. If you wish the
133 NSEC3 chain to have the OPTOUT bit set, set it in the flags field
134 of the NSEC3PARAM record. The NSEC3PARAM record will not appear in
135 the zone immediately, but it will be stored for later reference. When
136 the zone is signed and the NSEC3 chain is completed, the NSEC3PARAM
137 record will appear in the zone.
140 <command>auto-dnssec</command> option requires the zone to be
141 configured to allow dynamic updates, by adding an
142 <command>allow-update</command> or
143 <command>update-policy</command> statement to the zone
144 configuration. If this has not been done, the configuration will
147 <title>Private-type records</title>
149 <para>The state of the signing process is signaled by
150 private-type records (with a default type value of 65534). When
151 signing is complete, these records will have a nonzero value for
152 the final octet (for those records which have a nonzero initial
154 <para>The private type record format: If the first octet is
155 non-zero then the record indicates that the zone needs to be
156 signed with the key matching the record, or that all signatures
157 that match the record should be removed.</para>
160 <!-- TODO: how to format this? -->
162 key id in network order (octet 2 and 3)
163 removal flag (octet 4)
164 complete flag (octet 5)
167 <para>Only records flagged as "complete" can be removed via
168 dynamic update. Attempts to remove other private type records
169 will be silently ignored.</para>
170 <para>If the first octet is zero (this is a reserved algorithm
171 number that should never appear in a DNSKEY record) then the
172 record indicates changes to the NSEC3 chains are in progress. The
173 rest of the record contains an NSEC3PARAM record. The flag field
174 tells what operation to perform based on the flag bits.</para>
177 <!-- TODO: how to format this? -->
185 <title>DNSKEY rollovers</title>
187 <para>As with insecure-to-secure conversions, rolling DNSSEC
188 keys can be done in two ways: using a dynamic DNS update, or the
189 <command>auto-dnssec</command> zone option.</para>
191 <title>Dynamic DNS update method</title>
193 <para> To perform key rollovers via dynamic update, you need to add
194 the <filename>K*</filename> files for the new keys so that
195 <command>named</command> can find them. You can then add the new
196 DNSKEY RRs via dynamic update.
197 <command>named</command> will then cause the zone to be signed
198 with the new keys. When the signing is complete the private type
199 records will be updated so that the last octet is non
201 <para>If this is for a KSK you need to inform the parent and any
202 trust anchor repositories of the new KSK.</para>
203 <para>You should then wait for the maximum TTL in the zone before
204 removing the old DNSKEY. If it is a KSK that is being updated,
205 you also need to wait for the DS RRset in the parent to be
206 updated and its TTL to expire. This ensures that all clients will
207 be able to verify at least one signature when you remove the old
209 <para>The old DNSKEY can be removed via UPDATE. Take care to
210 specify the correct key.
211 <command>named</command> will clean out any signatures generated
212 by the old key after the update completes.</para>
214 <title>Automatic key rollovers</title>
216 <para>When a new key reaches its activation date (as set by
217 <command>dnssec-keygen</command> or <command>dnssec-settime</command>),
218 if the <command>auto-dnssec</command> zone option is set to
219 <constant>maintain</constant>, <command>named</command> will
220 automatically carry out the key rollover. If the key's algorithm
221 has not previously been used to sign the zone, then the zone will
222 be fully signed as quickly as possible. However, if the new key
223 is replacing an existing key of the same algorithm, then the
224 zone will be re-signed incrementally, with signatures from the
225 old key being replaced with signatures from the new key as their
226 signature validity periods expire. By default, this rollover
227 completes in 30 days, after which it will be safe to remove the
228 old key from the DNSKEY RRset.</para>
230 <title>NSEC3PARAM rollovers via UPDATE</title>
232 <para>Add the new NSEC3PARAM record via dynamic update. When the
233 new NSEC3 chain has been generated, the NSEC3PARAM flag field
234 will be zero. At this point you can remove the old NSEC3PARAM
235 record. The old chain will be removed after the update request
238 <title>Converting from NSEC to NSEC3</title>
240 <para>To do this, you just need to add an NSEC3PARAM record. When
241 the conversion is complete, the NSEC chain will have been removed
242 and the NSEC3PARAM record will have a zero flag field. The NSEC3
243 chain will be generated before the NSEC chain is
246 <title>Converting from NSEC3 to NSEC</title>
248 <para>To do this, use <command>nsupdate</command> to
249 remove all NSEC3PARAM records with a zero flag
250 field. The NSEC chain will be generated before the NSEC3 chain is
253 <title>Converting from secure to insecure</title>
255 <para>To convert a signed zone to unsigned using dynamic DNS,
256 delete all the DNSKEY records from the zone apex using
257 <command>nsupdate</command>. All signatures, NSEC or NSEC3 chains,
258 and associated NSEC3PARAM records will be removed automatically.
259 This will take place after the update request completes.</para>
260 <para> This requires the
261 <command>dnssec-secure-to-insecure</command> option to be set to
262 <userinput>yes</userinput> in
263 <filename>named.conf</filename>.</para>
264 <para>In addition, if the <command>auto-dnssec maintain</command>
265 zone statement is used, it should be removed or changed to
266 <command>allow</command> instead (or it will re-sign).
269 <title>Periodic re-signing</title>
271 <para>In any secure zone which supports dynamic updates, named
272 will periodically re-sign RRsets which have not been re-signed as
273 a result of some update action. The signature lifetimes will be
274 adjusted so as to spread the re-sign load over time rather than
277 <title>NSEC3 and OPTOUT</title>
280 <command>named</command> only supports creating new NSEC3 chains
281 where all the NSEC3 records in the zone have the same OPTOUT
283 <command>named</command> supports UPDATES to zones where the NSEC3
284 records in the chain have mixed OPTOUT state.
285 <command>named</command> does not support changing the OPTOUT
286 state of an individual NSEC3 record, the entire chain needs to be
287 changed if the OPTOUT state of an individual NSEC3 needs to be